include("file.jl")
.Main
, the default module for global objects in Julia, and each module defines its own set of global names.using
and import
, when they are followed with either Main.x
or .x
, look for a module already loaded and bring it and its exported objects into scope (for import
only 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 x
embedded inside package x
, it loads it, and it bring it and its exported objects into scope (again, for import x
only those explicitly specified).julia> command
the command has to be issued in a Julia session, while with (@v1.X) pkg> command
the 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 MyAwesomePackage.jl
.Julia
as 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
.MyAwesomePackage
with a src
subfolder that includes a "Hello world" version of our awesome package and, most importantly, the Project.toml
file. 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.1
rather than the default 0.1.0
).Project.toml
will also hold the dependencies that our package will require. So, for example, let's assume that MyAwesomePackage
depends from the packages LinearAlgebra
(a standard lib package) and DataFrames
(a popular third-party package to work with tabular data, aka "dataframes").MyAwesomePackage
folder with (@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.toml
file, the two packages should have been added to the [deps]
section. We now want to specify the version of the third-party packages our MyAwesomePackage
works 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 Project.toml
a new [compat]
section where we write down DataFrames = "0.21, 0.22"
, that is we allow MyAwesomePackage
to work with any DataFrames
in the v0.21.x
or v0.22.x
series. In other words, we assume that the functionality our package depends from has been introduced in DataFrames
v0.21.O
, and it is still available in the v0.22.x
serie.julia = "1.2.1"
assuming that our package works only with Julia >= v1.2.1
within the v1.x
serie.v1.x
serie 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.x
serie so that certain packages work only with them.Project.toml
should look at the end similar to this :generate
has produced to your github repository.(@v1.X) pkg> add https://github.com/sylvaticus/MyAwesomePackage.jl.git
and (@v1.X) pkg> dev MyAwesomePackage
. The package should now located in [USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage
, where [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).Revise
in 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.plusTwo
to our package by editing MyAwesomePackage/src/MyAwesomePackage.jl
as follow:[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/test/runtests.jl
:Test
needs to be added to the package:activate [USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage
and (MyAwesomePackage) pkg> add MyDependencyPackage
--> the new package will be recorded in the [deps]
section of [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)activate [USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/test
and (test) pkg> add MyDependencyPackage
--> the new package will be recorded in the [deps]
section of [USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/test/Project.toml
git commit
and git push
our 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.[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/.github/workflows/ci.yml
: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/.github/workflows/CompatHelper.yml
:[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/
we can continue to develop it, commit the changes and push them to GitHub (behind the scenes, the add
and dev
Julia 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 git push
).Arguments
and an Examples
sections.
For example, this is the documentation string for our plusTwo
function.?<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 Documenter
own documentation. Note that the docs
folder has its own Project.toml
, so you can add documentation-specific packages there.[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/docs/make.jl
:[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/docs/anotherPage.md
:anotherPage.md
we first document the module, we then create an "index" of all the documented items, and we finally detail them.index.md
to 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 stable
directory.[USER_HOME_FOLDER]/.julia/dev/MyAwesomePackage/.github/workflows/TagBot.yml
, documented here:@JuliaRegistrator register
"command" in the comment section of the commit we want to register.Release notes:
after the @JuliaRegistrator
command, 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).main
branch locally, continue our development, and when we consider it is "time" to release a new version we just change the version
information 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.