Installing and Using Ferrocene

What's in the box?

  • rustc - a compiler (★)
    • lld - the LLVM linker (★)
    • rustdoc - the docs generator
  • cargo/rustfmt/clippy - our usual friends
  • llvm-tools - objcopy, size, etc
  • rust-analyzer - for IDE integration
  • rust-src - libstd source code
  • rust-std-xxx - precompiled standard libraries (☆)
  • ferrocene-self-test - checks your installation
  • ferrocene-docs-xxx - documentation

★: qualified tool ☆: certification in progress

Note:

The lld linker and rustdoc come with the rustc-${rustc-host} package.

Portal

https://releases.ferrocene.dev

Note:

channels contain releases

Examples of channels include:

  • nightly
  • pre-rolling
  • rolling
  • beta-24.05
  • beta-24.08
  • stable-24.05
  • stable-24.08
  • etc

Examples of releases include:

  • nightly-2024-08-29
  • pre-rolling-2024-08-28
  • rolling-2024-08-08
  • beta-24.05-2024-06-19
  • beta-24.08-2024-08-22
  • stable-24.05.0
  • stable-24.08.0
  • etc

Portal

https://docs.ferrocene.dev

Targets

We have two dimensions:

  • Qualified, or not
  • Host or Cross-compiled

Qualified Targets

  • Production Ready
  • Passes the Rust Test Suite
  • Support is available
  • Signed qualification material
    • stable channel only

Note:

In stable-24.08 and earlier, these were called "Supported Targets"

Each release has a User Manual and it is important to follow the instructions for that target in that release otherwise you may be outside the qualification scope. As an example, we don't let you give arbitrary arguments to the linker - you can only pass the arguments we say are OK.

Quality Managed (QM) Targets

  • Production Ready
  • Passes the Rust Test Suite
  • Support is available
  • Signed qualification material

Note:

It may be that the target is en-route to being a Qualified Target, or it may be that it is deemed unlikely that the target would be useful in a safety critical context. Talk to us if you would like a QM Target available as a Qualified Target.

Experimental Targets

  • Not Production Ready
  • Not qualified
  • Might not pass the test suite
  • But useful for getting started early

Note:

A Ferrocene 'Experimental Target' is broadly equivalent to an upstream Tier 2 or Tier 1 target, depending on whether we're running the Test Suite in CI. And, to be fair, plenty of people use upstream Rust in production.

Host Targets

  • Ferrocene runs on a limited number of hosts:
  • Ferrocene is installed with criticalup
    • It's also open-source
    • Or, you can install a specific Ferrocene release from tarballs
  • Hosts always compile for themselves (proc-macros, build.rs, etc)

Cross-Compilation Targets

Using criticalup

  • Our equivalent of rustup
  • Fetches the appropriate Ferrocene toolchain packages
  • Need a criticalup.toml file for each project, and a global login token
    • Token only required to download a toolchain
    • You can burn the toolchain to a CD-R if you want

criticalup.toml

manifest-version = 1

[products.ferrocene]
release = "stable-24.08.0"
packages = [
  "rustc-${rustc-host}", "rust-std-${rustc-host}", "cargo-${rustc-host}",
  "rust-src", "rust-std-aarch64-unknown-none"
]

Installing Ferrocene

  1. Install criticalup
  2. Make a token
  3. Store your token with criticalup auth set
  4. Go to your project dir
  5. Run criticalup install

Example

$ criticalup auth set
$ criticalup install
info: installing product 'ferrocene' (stable-24.08.0)
info: downloading component 'cargo-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-24.08.0)
...
info: downloading component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-24.08.0)
info: installing component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (stable-24.08.0)
$ criticalup run rustc --version

Local State

Criticalup maintains local state in one of the following locations:

  • Linux: ~/.local/share/criticalup
  • macOS: ~/Library/Application Support/criticalup
  • Windows: %APPDATA%\criticalup

Running Ferrocene

You can execute the tool directly from the install dir

$ criticalup which rustc
/home/user/.local/criticalup/toolchains/cbfe2b...21e8b/bin/rustc

$ /home/user/.local/criticalup/toolchains/cbfe2b...21e8b/bin/rustc --version
rustc 1.79.0 (02baf75fd 2024-08-23) (Ferrocene by Ferrous Systems)

NB: cargo uses whichever rustc is in your PATH.

You can use the tool proxies:

$ ls /home/user/.local/criticalup/bin
cargo       rust-gdb    rust-gdbgui rust-lldb   rustc       rustdoc

$ /home/user/.local/criticalup/bin/rustc --version
rustc 1.79.0 (02baf75fd 2024-08-23) (Ferrocene by Ferrous Systems)

NB: cargo uses the corresponding rustc

You can use criticalup as a proxy:

$ criticalup run rustc --version
rustc 1.79.0 (02baf75fd 2024-08-23) (Ferrocene by Ferrous Systems)

NB: cargo uses the corresponding rustc

rust-analyzer in VS Code

Set RUSTC to tell it which rustc to use

$ RUSTC=$(criticalup which rustc) code .

PS D:\project> $Env:RUSTC=$(criticalup which rustc)
PS D:\project> code .

Ensure you have the rust-src package installed.

Our Rust Training has both 32-bit and 64-bit Arm bare-metal examples:

https://github.com/ferrous-systems/rust-training/tree/main/example-code