Ferrocene logo

CriticalUp Documentation

7. Running Tools

This chapter describes how to run specific tools using CriticalUp.

The examples in this chapter assume the following directory structure:

.
└── project
   └── criticalup.toml

After installing CriticalUp, authenticating, and installing a toolchain, CriticalUp can be used to run the specified tools from the installed toolchain.

CriticalUp will scan the working directory, then any parents, to discover the relevant criticalup.toml and determine which version of the tool to execute.

Note

If CriticalUp does not find a criticalup.toml in the current directory, it will search the parent directory, then the parent of that, up to the root directory of the system.

Any binary package installed via CriticalUp you can be run with the command criticalup run <binary>

cd project
criticalup run rustc --help

Important

Ferrocene binaries share the same binary names as any Rust toolchain that may already be installed.

If necessary, to make sure you only execute the specified binary if it is part of the installation, run the command with the --strict flag.

cd project
criticalup run --strict rustc --help

7.1. Locating Tools

It is possible to find the absolute path of a tool for the current toolchain with the which command:

cd project
criticalup which rustc

7.2. Using the Binary Proxies

CriticalUp creates a number of binary proxies which can be used to run the appropriate Ferrocene binaries for a given workspace. These can be added to your shell path on any OS. See On your shell path for more details. They can also be used as a rustup toolchain, as described in the next section As a rustup toolchain.

Important

To prevent executing an unintended binary, If you already have Rust installed via rustup you should add the CriticalUp installation as a rustup toolchain.

7.2.1. As a rustup toolchain

Ferrocene can be used as a rustup toolchain that may feel familiar to some developers.

criticalup link create

Alternatively:

rustup toolchain link ferrocene "$(criticalup link show)"

To verify the link was created, validate there is a ‘ferrocene’ line in the toolchain list:

rustup toolchain list -v

To remove the link:

criticalup link remove

Example usage:

cargo +ferrocene build --release
cargo +ferrocene test

It’s also possible to have rustup use the Ferrocene toolchain by default:

rustup default ferrocene

You can configure your project to use the ferrocene toolchain by default by creating a rust-toolchain.toml:

[toolchain]
channel = "ferrocene"

Then, by default, the Ferrocene toolchain created above should be used. Other rustup toolchains can still be used, for example, cargo +stable run.

7.2.2. On your shell path

7.2.2.1. Linux

Proxies are located at $XDG_DATA_HOME/criticalup/proxy/bin, typically this is ~/.local/share/criticalup/proxy/bin/.

You can add the following line to your ~/.bashrc or ~/.zshrc to add the binary proxies to your PATH:

export PATH="$PATH:$HOME/.local/share/criticalup/proxy/bin"

If you’re using a different shell, such as nushell, you may need to consult the shell’s documentation on how to add to the path.

7.2.2.2. macOS

Proxies are located at ~/Library/Application Support/criticalup/proxy/bin/.

You can add the following line to your ~/.zshrc to add the binary proxies to your PATH:

export PATH="$PATH:$HOME/Library/Application Support/criticalup/proxy/bin"

If you’re using a different shell, such as nushell, you may need to consult the shell’s documentation on how to add to the path.

7.2.2.3. Windows

Proxies are located at %appdata%\criticalup\proxy\bin\, typically this is ~\AppData\Roaming\criticalup\proxy\bin\.

On Windows 11, you can add the folder to your system path by hitting the Windows key and searching ‘Edit environment variables for your account’, then selecting the control panel. If you can’t find it, you can use the ‘Run’ dialog to directly launch it:

rundll32.exe sysdm.cpl,EditEnvironmentVariables

Once there, edit the PATH variable to include the following entry:

%USERPROFILE%\AppData\Roaming\criticalup\proxy\bin\

You’ll then need to sign out, and back in for changes to take effect.

If you’re using a different shell, such as nushell, you may need to consult the shell’s documentation on how to add to the path.