nrfutil-toolchain-manager documentation

Toolchain manager

nRF Util’s toolchain-manager is a CLI tool for managing and using toolchains for the nRF Connect SDK.

Each version of nRF Connect SDK has an associated toolchain, which includes tools and modules specific to the nRF Connect SDK that are required to build nRF Connect SDK samples and applications. Multiple SDK versions can share the same toolchain version.

You can interact with toolchains through their associated version of the nRF Connect SDK (shortened to “ncs-version” in the CLI). There is however an additional functionality to allow advanced users to move beyond this limitation.

Toolchain installation location

The toolchain-manager has its own, dedicated installation directory for downloading and installing toolchains. The location of this directory varies depending on your operating system.

Windows

On Windows, the default install directory is C:\\ncs. You can override this (for any relevant command) with the --install-dir flag.

Linux

On Linux, the default install directory is $HOME/ncs, commonly written as ~/ncs. You can override this (for any relevant command) with the --install-dir flag.

macOS

On macOS, the install directory is /opt/nordic/ncs, and no other directory can be used. This is because of a requirement from Python and the dynamic loader to have a deterministic path for the toolchain.

This limitation means that a fixed, absolute path must be used, which is why /opt/nordic/ncs was chosen (instead of something like $HOME/ncs). This, in turn, requires root access for creating the directory: You will be prompted to grant the program admin rights for the creation of the folder on their first install. The folder will be created with some access rights to the user, so subsequent installs do not require root access. It is not recommended to run the toolchain-manager as root (for example, using sudo), as this will cause the directory to only grant access to root, meaning subsequent installs also need root access.

Available subcommands

Use this tool for the following actions:

Once you’ve installed your toolchain, you can start using it with the following subcommands:

You can use the --help flag to get information on the options that are available to you.

Completion

Command line completion suggestions for nrfutil toolchain-manager subcommands, flags and arguments are available using the nRF Util’s completion command. See the Setting up autocompletion page on TechDocs.

Configuration values

Some parts of the completion system for nrfutil toolchain-manager are based on the current configuration options set by the user (controlled using the config subcommand). These options can, for any relevant command, be overridden using a corresponding flag. For example, the install-dir config variable can be overridden using the --install-dir flag. The overridden value will not be picked up by the completion system (since it’s based on the current config options), meaning the values given by the completion system are likely going to be wrong.

If you rely on the completion system, it is therefore recommended to use the config subcommand to update the config variables instead of using the override flags. The override flags are more useful in scripts (where updating the config may be unfeasible) or if the value is only changed for a brief time.

Available toolchains

The install command features completion for toolchains that are available to install. These values are based on the most recently cached copy of the index (for the index given by the current configuration value of toolchain-index).

The cache for any given index is updated whenever it is successfully retrieved, for example when running search. A natural workflow is therefore to run the search command before installing a new toolchain. This will both make sure you know what toolchains are available and make sure the completion is giving values that are up-to-date.