Creating a Julia package

Julia comes with a built-in package manager, you can read its detailed documentation, including how to create packages.

Julia packages consist of modules. Hence, before creating a package, make sure to understand how modules work in Julia.

Here we provide a step-by-step example, using PkgTemplates.jl, inspired by a videoof Chris Rackauckas (please note that the video uses Travis as a Continuous Integration tool which we no longer encourage, and prefer Github Actions instead). Here is the video:

In case of any issues, remember that help is available.

Prerequisites

Starting a package

  1. You need to create a folder to store a new package. For example, if you use Atom as an IDE, create a new folder called Tiddlywinks.jl (packages in Julia generally have a capital first letter). Then, open the GitHub panel and select Initialize and publish on GitHub. Now, you can go to your GitHub page and see that 'Tiddlywinks.jl' has appeared there, as well as locally.

  2. In your terminal application, use the change directory (cd) command to change the current working directory to the location of your package.

  3. In the Julia REPL, install PkgTemplate.jl as follows:

using Pkg
   Pkg.add("PkgTemplates")

Creating package template

Now PkgTemplates.jl has been installed and we want to use it to create a template for a package.

Run the following commands in the Julia REPL to create the template (make sure to replace myusername with your username and your name with your name):

using PkgTemplates

t = Template(;
           user="myusername",
           license="MIT",
           authors=["your name"],
           plugins=[
           ],
       )

The package called "Tiddlywinks" can now be created using the template t by running the following line in Julia REPL:

t("Tiddlywinks")

Last line in the REPL shows where the new package has been created: Info: New package is at *package_repo*. As the folder has not been specified, the package has been created at ~/.julia/dev on Linux, and at %USERNAME%/.julia/dev on Windows. If this is not the repository you want to be working from, move the files to the original repo which you have created. Now in Tiddlywinks.jl you should have

Writing code

Everything is ready for you to write code. Folder /src already contains a file with the same name as the name of the package (Tiddlywinks.jl). You may not want to write all of the code in this file directly. Instead, you can create various pieces in external files within the /src directory, and then assemble them in the main file with the include command. Here are the steps to follow:

function tiddly_greet()
    println("Tiddlywinks")
end

Writing tests

Tests are necessary to make sure that the code is working correctly. There is never enough testing. The /test folder already has a starter. We edit it to call the newly implemented function:

using Tiddlywinks
using Test

@testset "Tiddlywinks.jl" begin
    @test Tiddlywinks.tiddly_greet() == "Tiddlywinks is working"
    @test Tiddlywinks.tiddly_greet() != "hello world"
end

Running tests

To run tests on your package:

Continuous integration

Continuous integration (CI) is a software development practice of merging all working copies into a mainline repository. CI tools can help you test the package on various versions of Julia, as well as various operating systems. We recommend using Github Actions.

Propose changes via Pull Requests

To make your first Julia pull request, we recommend reading the detailed guide by Katharine Hyatt. Here we provide the summary of required steps, using the example package from above.

To propose a change to an existing repository, you need to create a pull request (PR). Follow the steps below. The example describes a case when you would like to add more testing options to your package:

Example: create a branch of Tiddlywinks.jl called more_testing_options

Now your request has appeared on the tab Pull requests of the package. If you click on this tab, Files changed will show you exact changes that you are proposing. Continuous integration tools, if they have been included into the project, will run the tests to check that they can be passed by the new branch.

If all test will be passed, package maintainers will review your code and either leave comments or approve it to be merged into the main branch.

More to come

Stay tuned for more: publishing a package, branches and pull requests, code review