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.
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.
On Windows, the default install directory is C:\\ncs
.
You can override this (for any relevant command) with the
--install-dir
flag.
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.
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.
Use this tool for the following actions:
nrfutil toolchain-manager search
nrfutil toolchain-manager install --ncs-version <VERSION>
nrfutil toolchain-manager list
Once you’ve installed your toolchain, you can start using it with the following subcommands:
nrfutil toolchain-manager env
lets you inspect the
environment variables which sets up the toolchain environment. Use the
--as-script
flag to output a script to set these up for you
(supported shells can be seen in the command line tool itself).nrfutil toolchain-manager launch
lets you launch
commands in the environment directly. It also supports launching a new
terminal or shell in the given toolchain environment.You can use the --help
flag to get information on the
options that are available to you.
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.
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.
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.