Using Julia Projects

To ensure that your carefully crafted Julia code works with future updates of the Julia standard libraries (the core Julia packages), you should organize your work in projects.

A Julia project is generally a folder with which you have associated specific Julia packages, e.g. DataFrames, Distributions, or Plots, and the Julia scripts that rely on those packages.

To set up a project, you

• activate the project, and
• add packages.

To use a project, in your script you

• activate the project
• use the packages
• run code that depends on those packages

Future-proofing

The SSCC updates the Julia standard libraries twice each year, usually in August and January. The packages you install depend on the standard libraries. An update to the standard libraries may require an update to some of your packages.

Meanwhile, your packages also often rely on each other. But as open-sourced software, package updates are seldom fully in sync. An update to the standard libraries may require an update to a package, which then breaks the functionality of another package.

The “Julia” answer to all of this is the Julia package manager, Pkg. When you organize your work in projects, the Julia package manager establishes which packages are to be used together for a specific body of work, the scripts in that folder (or subfolders). The package manager does the work of identifying which package versions can work together, and ensuring that they are installed.

The key component is a register file called Project.toml, which records your package requests. A secondary file is the Manifest.toml, which records which versions are to be used for this project and where they are installed on the computer you are using.

Using the Project.toml, the Julia package manager can ensure that appropriate package versions are installed and used, even if you move your files to a different computer or are using a different version of Julia (perhaps after an SSCC update).

Creating a Project

To start a project in a new folder, type

using Pkg
Pkg.activate("newproject")

  Activating new project at `~/newproject`

(The folder is not actually created until you add packages.)

Then add the packages you need for your project.

Pkg.add("Example")

   Resolving package versions...
    Updating `~/newproject/Project.toml`
  [7876af07] + Example v0.5.3
    Updating `~/newproject/Manifest.toml`
  [7876af07] + Example v0.5.3

A note on project names

• the current folder iself is "." To activate the project in the current folder, use Pkg.activate(".").

  Pkg.activate(".")

    Activating new project at `~`

• simple project names like "myproject", are always understood to belong in your current folder, the folder from which you started Julia.

  Pkg.activate("newproject")

    Activating project at `~/newproject`

• the default project is what you are using if you have not activated another project. This can be explicitly activated with Pkg.activate().

  Pkg.activate()

    Activating project at `~/.julia/environments/v1.9`

A note on the package load path

Julia generally uses packages registered in three locations, and not just those you have explictly added to a project. These are

• the standard libraries
• your default environment
• your project

println(join(Base.load_path(), "\n"))

/home/h/hemken/.julia/environments/v1.9/Project.toml
/private/linux64/julia-1.9.4/share/julia/stdlib/v1.9

This means you need to be careful what packages you place in your default environment (“home” project).

Using a Project

At the beginning of your script, include a Pkg.activate("myproject").

For example, using the “newproject” above, a script might begin with

using Pkg
Pkg.activate("newproject")

  Activating project at `~/newproject`

And continue with

using Example

println(hello("SSCC member!"))
println("domath() adds 5 to it's input")
println(domath(6))

Hello, SSCC member!
domath() adds 5 to it's input
11

In the Future

When trying to use a project with an upgraded (or downgraded!) version of Julia, the changes in the standard libraries and the changes in your default environment can create incompatabilites with your current set of packages. The error messages produced by package incompatabilities can take many forms.

Resolving incompatabilities

Often the simplest way to resolve these incompatabilities is to remove (or rename) the Manifest.toml file.