Main, the default module for global objects in Julia, and each module defines its own set of global names.
import, when they are followed with either
.x, look for a module already loaded and bring it and its exported objects into scope (for
importonly those explicitly specified). Otherwise, they do a completely different job: they expects a package, and the package system lookups the correct version of the module
xembedded inside package
x, it loads it, and it bring it and its exported objects into scope (again, for
import xonly those explicitly specified).
julia> commandthe command has to be issued in a Julia session, while with
(@v1.X) pkg> commandthe command has to be issued in the special "package" mode of Julia (type
]in a Julia session to access it,
[DEL]to return to the Julia main prompt).
MyAwesomePackage, and the corresponding GitHub repository will be
Juliaas gitignore template:
generate. We will then commit and link this git repository with the remote GitHub repository we just made, push the basic package structure to GitHub and, at that point, we can download it again as a Julia Package and continue its development.
(@v1.X) pkg> generate MyAwesomePackage.
srcsubfolder that includes a "Hello world" version of our awesome package and, most importantly, the
Project.tomlfile. For now, this includes just: (a) the name of the package; (b) the author; (c ) the unique id that has been assigned to the new package (this is a code that depends from stuff like the MAC address, the exact time, the process id, etc...) and (d) the initial version of the package. Check that the author and initial version are ok for you (for example I prefer to start a package with version
0.0.1rather than the default
Project.tomlwill also hold the dependencies that our package will require. So, for example, let's assume that
MyAwesomePackagedepends from the packages
LinearAlgebra(a standard lib package) and
DataFrames(a popular third-party package to work with tabular data, aka "dataframes").
(@v1.X) pkg> activate(FULL_PATH/MyAwesomePackage). We can now add the two packages with
(MyAwesomePackage) pkg> add LinearAlgebra DataFrames. From the message in output, we take note that the DataFrame version is
v0.22.2. Going back to our new
Project.tomlfile, the two packages should have been added to the
[deps]section. We now want to specify the version of the third-party packages our
MyAwesomePackageworks with, and in particular, if we want to register it in the official Julia registry, we need to specify an upper version. We can do that by adding to
[compat]section where we write down
DataFrames = "0.21, 0.22", that is we allow
MyAwesomePackageto work with any
v0.22.xseries. In other words, we assume that the functionality our package depends from has been introduced in
v0.21.O, and it is still available in the
julia = "1.2.1"assuming that our package works only with
Julia >= v1.2.1within the
v1.xserie are "guaranteed" to be backward compatible with code wrote for Julia
v1.0.0, but the reverse is not true, e.g. new features could still be added in the
v1.xserie so that certain packages work only with them.
Project.tomlshould look at the end similar to this :
generatehas produced to your github repository.
(@v1.X) pkg> add https://github.com/sylvaticus/MyAwesomePackage.jl.gitand
(@v1.X) pkg> dev MyAwesomePackage. The package should now located in
[USER_HOME_FOLDER]is the home folder for the local user, e.g.
~in Linux or
%HOMEPATH%in Windows and we can cancel the original location where we generated it (for example in our Desktop).
Revisein a new Julia session before importing a package it lets you account for changes that you make when you save on disk any modification you make on the package without having to restart the Julia session.
plusTwoto our package by editing
Testneeds to be added to the package:
(MyAwesomePackage) pkg> add MyDependencyPackage--> the new package will be recorded in the
[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/Project.toml(don't forget to add a upper bound if the package is not in the standard library)
(test) pkg> add MyDependencyPackage--> the new package will be recorded in the
MyAwesomePackage, let's add a functionality that at each time the package is pushed, github performs an operation (github calls these operation "actions"), and in particular it automatically runs the test for us.
Project.toml. But attention, it is still up to us to check that indeed the new version works with our package!
[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/we can continue to develop it, commit the changes and push them to GitHub (behind the scenes, the
devJulia package commands did actually cloned the GitHub repository to
.julia/dev/MyAwesomePackage/, so we can use directly git commands on that directory, like
git commit -a -m "Commit message"or
Examplessections. For example, this is the documentation string for our
?<FUNCTION OR MODULE NAME>or in the documentation pages that we are going to build.
generate()produce a basic documentation configuration we are going to extend it a bit in order to have (a) multiple pages, (b) automatic inclusion of all documented items and (c ) hosting (deployment) of the documentation in GitHub pages. All these steps are documented in deep in the
Documenterown documentation. Note that the
docsfolder has its own
Project.toml, so you can add documentation-specific packages there.
anotherPage.mdwe first document the module, we then create an "index" of all the documented items, and we finally detail them.
index.mdto provide a link back to the github repository.
[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/docs/build. We finally "solve" the warning above and take care of documentation's deployment, whose steps are documented in detail here.
gh-pages. This branch is added automatically during the process of deploying the documentation the first time. At the same time the "source branch" for the documentation pages in the repository settings (https://github.com/YOUR_USERNAME/MyAwesomePackage.jl/settings) should already be set to
gh-pages(see the GitHub pages documentation to set it manually if this for any reason doesn't happen).
gh-pages. The first time we will make a release, its documentation will be available under the
@JuliaRegistrator register"command" in the comment section of the commit we want to register.
Release notes:after the
@JuliaRegistratorcommand, for example:
(@v1.X) pkg> add MyAwesomePackage. If something goes wrong - in our case let's say that we forgot to put the upper bound for Julia itself - you will receive an informative message explaining what went wrong and we can try the registration again (issuing an other
@JuliaRegistrator register"command", that in turn will update the pull request).
mainbranch locally, continue our development, and when we consider it is "time" to release a new version we just change the
versioninformation in the package
Project.toml, we commit/push the new "version" and we raise the
@JuliaRegistrator register"command" again in GitHub. This will have the effect to register the new version in the Julia official Register, with TagBot creating an equivalent version on the GitHub repository.