How to Create a Julia Package

4 min read

NOTE

This post is outdated. With the advent of Julia 1.0, the workflow for creating packages was significantly altered. An excellent guide can be found here.

In this post, my goal is to briefly explain how to create an unregistered Julia package for Julia 0.6.4, how to synchronize it with your Github account, and how to start testing your code automatically using TRAVIS CI. I started writing this post as a reminder to myself. I am posting it here with the hope that it may be useful for someone else. More on this topic can be found by reading the official Julia’s manual.

Why Creating a Package?

A package to share academic work

My research projects often involve data manipulation and/or implementing algorithms. I discovered that writing my codes in the form of a package helps me in producing better and reusable code. Creating a package to share your academic work is also very much in line with the idea that scientific research should be reproducible. Users can download your work and install the required dependencies using a single line :

git.clone("https://github.com/YourGithubUsername/YourPackage.jl.git")

Continuous Integration

Another major advantage of creating a package is that it makes your life much easier when it comes to testing your code automatically using TRAVIS CI. TRAVIS CI is a continuous integration system, which considerably helps in detecting and resolving bugs at an early stage.

Step-by-step tutorial

In what follows, I am assuming you are using Linux, with julia version 0.6 installed. If you are using a different version, just replace v0.6 by the number corresponding to your current version of julia. You also need to have the package PkgDev installed.

Step 1: Generate your package

The following two lines will create a directory called "MyPackage.jl" with an MIT License, in Julia’s package location:

using PkgDev
PkgDev.generate("MyPackage.jl","MIT")

By convention, Julia repository names and with .jl. If you change your working directory to your newly created package (cd ~/.julia/v0.6/MyPackage), you will notice that the following files and directories have been created:

\src

The \src folder will contain your source code. By default, it contains a file “MyPackage.jl”, which you will use to load other packages and to include .jl files that you created. In this file, you also state the functions and types you want to export. As an example, you may consult the package Distributions.

\test

This folder contains a file runtests.jl, in which you can include unit-tests. Within julia, you can simply run your series of unit-tests with the command:

Pkg.test("MyPackage")

REQUIRE

This file is used to specify the required dependencies. When a user Pkg.clone() your package, Julia’s package manager will make sure that these requirements are met. For instance, let’s say that your package relies on the version 0.6 of Julia (or higher) and the package JSON. The REQUIRE file will be the following :

julia 0.6
JSON

README.md

You can use this file to add a description of you package.

LICENSE.md

To guide you in the choice of a licence, you may want to consult the following website: https://choosealicense.com/

Step 2: Set-up your working environment

This step is optional. While you may want to develop you package directly from Julia’s package directory (~/.julia/v0.6 if you are using julia v0.6), I personally find it unpleasant. I usually create a symlink to a more convenient location:

ln -s ~/.julia/v0.6/MyPackage your/convenient/directory/MyPackage

After running this line in the terminal, you can start working on your package directly from your/convenient/directory.

Step 3: Synchronize with GitHub

The following step will synchronize your package with your GitHub account. After creating a repository named “MyPackage.jl” on GitHub, enter the following commands in the terminal:

git add -A
git commit -m "First commit"
git remote add origin https://github.com/YourGithubUsername/MyPackage.jl.git
git push -u origin master

Going to the page https://github.com/YourGithubUsername/MyPackage.jl.git, you should now see folders and files mentioned above. Some extra files are also going to be there, for instance .gitignore or appveyor.yml. You can ignore them for the time being. After this initial commit, you are almost all set and you can use the usual GitHub workflow. A good idea though is to enable TRAVIS CI for the repository just you created.

Step 4: Set-up TRAVIS CI

From your GitHub account, sign in to either:

  • TravisCI.org if your repository is public
  • TravisCI.com if your repository is private

On TRAVIS CI, go to your profile page. Enable your repository “YourGithubUsername/MyPackage.jl” by flicking the switch one. Every time you push a new commit, your set of tests, launched by the file /test/runtests.jl, will be automatically executed on a separate virtual environment. If one of your tests fails, you will be notified by e-mail and (most of the time) you will be able to spot the origin of the error quite easily.

Avatar
Julien Pascal, PhD
Economist