Build Modes

cuNumeric.jl gets its cupynumeric / Legate binaries from one of three providers, chosen through CNPreferences (writes LocalPreferences.toml; restart Julia after changing mode):

Mode	When to use
JLL (default)	Normal installs; prebuilt artifacts from the Julia package server
Developer	Building or hacking the in-tree C++ wrapper, or a custom cupynumeric tree
Conda	Linking against an existing conda env that already has cupynumeric

Install CNPreferences on its own if you want to set the mode before adding cuNumeric:

using Pkg
Pkg.add("CNPreferences")

Default Build (jlls)

using Pkg
Pkg.add("cuNumeric")

If you previously used a custom build or conda build and would like to revert back to using prebuilt JLLs:

using CNPreferences
CNPreferences.use_jll_binary()

Then restart Julia. Run Pkg.build("cuNumeric") if you left a non-JLL mode.

Developer mode

This gives the most flexibility in installs. It is meant for developing on cuNumeric.jl. For rebuilding `lib/cunumeric_jl_wrapper` after C++ changes, see [Developer Mode](developer_mode.md).

We support using a custom install version of cupynumeric. See https://docs.nvidia.com/cupynumeric/latest/installation.html for details about different install configurations, or building cupynumeric from source.

We require that you have a g++ capable compiler of C++ 20, and a recent version CMake >= 3.26.

To use developer mode,

using CNPreferences; CNPreferences.use_developer_mode(; use_jll=true, path=nothing)

By default use_jll will be set to true. However, you can use a custom path of cupynumeric. By setting use_jll=false, you can set path to your custom install.

using CNPreferences; CNPreferences.use_developer_mode(;use_jll=false, path="/path/to/cupynumeric/root")

After enabling developer mode (and after any wrapper edits), rebuild with Pkg.build("cuNumeric") and restart Julia. Details are on Developer Mode.

Link Against Existing Conda Environment

This feature is not passing our CI currently. Please use with caution. We are failing to currently match proper versions of .so libraries together. Our hope is to get this functional for users already using Legate within conda.

Note, you need conda >= 24.1 to install the conda package. More installation details are found here.

Supported cupynumeric versions match the cupynumeric_jll major.minor in this repo's Project.toml. Currently that pin is cupynumeric_jll = "26.6.0", so use the 26.6 conda line:

# with a new environment
conda create -n myenv -c conda-forge -c cupynumeric cupynumeric=26.6
# into an existing environment
conda install -c conda-forge -c cupynumeric cupynumeric=26.6

Once you have the conda package installed, you can activate here.

conda activate [conda-env-with-cupynumeric]

To update LocalPreferences.toml so that a local conda environment is used as the binary provider for cupynumeric run the following command. conda_env should be the absolute path to the conda environment (e.g., the value of CONDA_PREFIX when your environment is active). For example, this path is: /home/JuliaLegate/.conda/envs/cupynumeric-gpu.

using CNPreferences
using Pkg

CNPreferences.use_conda(ENV["CONDA_PREFIX"])  # absolute path, e.g. from CONDA_PREFIX
Pkg.build("cuNumeric")

Then restart Julia so the new mode loads.