Julia Development Notes

This repository is meant to collect some notes and useful code snippets for working on and with Julia packages.

Two notes for this document:

1. Any command prefixed with ] is meant to be run in the package management REPL that is activated by prissing ] in the regular Julia REPL.
2. Any (set of) command(s) that is used repeatedly but not part of the code should be written down somewhere – either just in e.g. the README but preferably as a recipe in a Makefile or (better) a justfile. This document contains code snippets for just recipes. Naming the justfile without a dot, i.e. not having it hidden, is often better because it makes it more obvious that these helper commands are available. It is also good to include a recipe

   _default:
     @just --list

   to help with discoverability. Recipes can also include a “shebang line” to run the commands as a single script rather than individual shell commands. In this case, it is useful to include set positional-arguments so the scripts have direct access to the command-line arguments; the recipes below assume this setting is active.

Project Environments

Always work with environments: It is almost always better to avoid using the global package environment and use a separate environment for the specific task instead. An environment is just a folder that contains a Project.toml and (usually) a Manifest.toml, and the currently active environment determines which Julia packages can be loaded with using (but not which ones are downloaded on the computer – packages are always downloaded to the ~/.julia folder, where unused packages are occasionally deleted). It is worth spending a bit of time studying the Pkg.jl docs to get comfortable with how environments work in Julia.

There are three useful types of environments:

1. To use Julia for a specific task such as a research project, go to the folder that will contain the code and launch Julia with julia --project=.. This sets the project environment to the current folder, which can also be done with ] activate . from within the Julia REPL. The project/manifest files are only created once a package dependency is added. Once there is a Project.toml, you can also just run julia --project from within the folder or any of its subfolders.
2. If code is meant to be used by other projects, set up a new Julia package by running ] generate NAME in the Julia REPL, where NAME would be something like BoundaryLayerDynamics.jl. This will create a new folder with that name and a Project.toml for the new package. You can omit the .jl in the name, which only affects the folder name that is created.
3. Often it is useful to create temporary environments to try out things. This can be done with ] activate --temp or Pkg.activate(temp = true) after importing Pkg.

For non-temporary environments it is also good to set up a repository right away, either with git init . or (better) with jj git init . using the Git-compatible Jujutsu VCS. For packages, the Manifest.toml should be excluded and added to the .gitignore file, as the compatible versions should be defined in the Project.toml.

Testing

Create a file test/runtests.jl which contains code making use of the package and checking whether it works as expected. To correctly handle package dependencies, the tests should be run with julia --project -e "using Pkg; Pkg.test() or interactively with ] test rather than just running the runtests.jl script directly.

test *params:
  #!/usr/bin/env -S julia --project
  using Pkg; Pkg.test(test_args = ARGS)

Tests often have additional dependencies that the package itself does not require, starting with the Test module from the standard library. As of Julia 1.10, there are two not-ideal ways of adding these dependencies proposed in the Pkg docs. The [targets]-based approach tends to be a bit cleaner and less error-prone, but needs hand-editing of Project.toml; the easiest way to add a package is adding it to the regular dependencies and then manually moving it to the [extras]section. Julia 1.12 introduces a new way of handling this issue using “workspaces”, which allows a sub-project in the test folder to use the same manifest as the main project. Once Julia 1.12 is widely available, this is likely the best approach, as it allows adding test dependencies with the package REPL by activating the test environment.