Setting up a Julia Package

In Julia, packages are the natural medium for code that doesn't fit in a simple script or notebook. While this might sound excessive at first, it provides many conveniences. This page serves as a guide for creating your first Julia package. It walks you through the process of the initial setup and the structure of a Julia package.

Table of Contents

PkgTemplates.jl

PkgTemplates.jl is a highly configurable package for project templates. Thanks to these templates, setting up the file structure for a Julia package takes seconds.

We suggest you use the following template for your project work at TU Berlin:

using PkgTemplates

template = Template(;
    user="YourGitHubUsername",
    authors="FirstName LastName <YourEmail@campus.tu-berlin.de>",
    julia=v"1.10",
    plugins=[
        License(; name="MIT"),
        Git(; ssh=true, manifest=false),
        Tests(; project=true),
        GitHubActions(; x64=true, extra_versions=[v"1.10"]),
        Codecov(),
        Documenter{GitHubActions}(),
    ],
)

Let's go through this template step by step:

• user: the GitHub (or other hosting platform) account name under which the project is hosted

• authors: your authorship details

• julia=v"1.10": sets the minimum Julia version requirement to 1.10 for package compatibility. Usually, developers strive to support the last long-term support (LTS) release of Julia, which currently is 1.6. Since this is the first package we write, we only target 1.10. Thanks to packages like Compat.jl, backwards compatibility is usually easy to achieve.

We also use the following plugins to customize our template, most of which are defaults:

• License(name="MIT"): add the MIT License, which is permissive with minimal restrictions.

• Git(manifest=false): initialize a Git repository and opt out of tracking the Manifest.

• Test(; project=true): set up package testing and add a Project.toml for tests.

• GitHubActions(): set up continuous integration (CI) via GitHub Actions to run our package tests.

• Codecov(): set up CodeCov to assess code coverage. This tells you how much of your code is covered by package tests.

• Documenter{GitHubActions}(): use Documenter.jl to generate package documentation. Build the documentation using GitHub and deploy it via GitHub Pages.

• Formatter(; style="blue"): tells JuliaFormatter.jl and the Julia VSCode extension to use the Blue code style for automatic code formatting

After you created the template, run

julia> template("MyPackage")

At the end of the package generation, Julia will inform us that our project has been created in the ~/.julia/dev folder:

[ Info: New package is at ~/.julia/dev/MyPackage

You can set a custom directory via the keyword argument dir of your template.

Project structure

Let's take a look at the structure of the files generated by PkgTemplates.jl by opening our project in VSCode. The file explorer on the left should show the following files:

├── .github
│   └── workflows
│       ├── CI.yml
│       ├── CompatHelper.yml
│       └── TagBot.yml
├── .gitignore
├── docs
│  ├── make.jl
│  ├── Manifest.toml
│  ├── Project.toml
│  └── src
│     └── index.md
├── LICENSE
├── Manifest.toml
├── Project.toml
├── README.md
├── src
│   └── MyPackage.jl
└── test
   ├── Manifest.toml
   ├── Project.toml
   └── runtests.jl

5 directories, 10 files

Let's go through this step by step:

• README.md: the "landing page" of your repository. Should describe what the code is about, link to your documentation and maybe give a usage example.

• LICENSE: the license you chose for your project, e.g. the MIT license

• Project.toml and Manifest.toml: you should already be familiar with these files, which specify your package environment

• src: your source code goes in here. The file named after your package is the "main" file.

• test: your package tests go in here. The runtests.jl is the "main" file of your tests.

• docs: your package documentation goes in here:

  • make.jl: the build

• .github/workflows: the files in here specify GitHub Actions, commands that will be run on GitHub's remote computers.

  • CI.yml: runs your package tests, builds the documentation and computes code coverage.

  • CompatHelper.yml: automatically opens an issue when new versions of your dependencies have been released

  • TagBot.yml: automatically tags releases when using JuliaRegistrator (you can ignore this).

• .gitignore: specifies files you don't want to commit to Git, like the Manifest

Further reading

• PkgTemplates.jl documentation

• Modern Julia Workflows on setting up a package