3. Installing Ferrocene

This chapter describes how to install and validate the Ferrocene toolchain.

Before proceeding, you should identify the targets you want to install. You must pick the target of the host platform you’re going to install Ferrocene on, and optionally one or more cross-compilation targets (depending on the hardware you’ll deploy the executable or library on).

3.1. Prerequisites

The prerequisites of Ferrocene depend on the targets you are going to install. For each of the targets you identified above, follow the “prerequisites” section of the target documentation.

3.2. Installation

Preferred way of installing and managing Ferrocene toolchain(s) is via our rustup like tool called criticalup.

Find more details about using criticalup in the CriticalUp User Documentation.

3.2.1. Manual installation

Ferrocene installation archives are available for manual download at releases.ferrocene.dev. The website requires authentication through the customer portal, and doesn’t allow programmatic access.

On the channel list, select the channel you want to view the latest release published in it (and its files). For each of the targets you identified above, download all the archives listed in the “installation archives” section of the target documentation.

You must extract all downloaded archives in the same directory to finish the Ferrocene installation. Ferrocene binaries will then be available in the bin subdirectory inside of the extraction location.

For example, to install Ferrocene in /opt/ferrocene you can run:

sudo tar -C /opt/ferrocene -xf path/to/first-archive.tar.xz
sudo tar -C /opt/ferrocene -xf path/to/second-archive.tar.xz
# ...repeat for all the downloaded archives

To make Ferrocene available system-wide, consult the manual of your operating system on how to add the bin sub-directory into the system $PATH.

Note

Ferrocene can be installed anywhere on the system, including inside of a user’s home directory. It is portable, can be moved to different storage locations after its installation, and you can have multiple installations of Ferrocene in different directories.

Caution

Ferrocene does not support in-place upgrades: you cannot install Ferrocene inside a directory that contains another Ferrocene installation. To upgrade Ferrocene, you must remove all the contents of the existing directory before extracting the new Ferrocene version.

Because of this, we do not recommend installing Ferrocene in shared directories like /usr/local, as removing old Ferrocene versions would prove tricky.

3.3. Validation

Caution

The procedure described below relies on a tool that is not qualified, and thus can’t be used in a safety critical environment: in that case, you must follow the instructions in RUSTC_CSTR_0010_INSTALL.

The Ferrocene toolchain contains a validation binary called ferrocene-self-test, useful to verify the installation of the Ferrocene toolchain. The tool will analyze the installation and the surrounding environment, and note if known installation problems are detected. To execute the tool, run:

PATH_TO_INSTALLATION_DIRECTORY/bin/ferrocene-self-test

All the performed checks will be displayed. If any check fails, an error will be emitted along with an ID. You can look up the identifier in the error codes list to learn more about the failure and ways to fix it.