Merge pull request #177 from ferrous-systems/update-ferrocene-install…

…-notes

Update ferrocene install notes

example-code/qemu-aarch32v78r/Cargo.toml

@@ -5,6 +5,7 @@ edition = "2021"
 authors = ["Ferrous Systems"]
 license = "MIT OR Apache-2.0"
 description = "A simple ARMv8-R demo application that runs in QEMU and compiles with Ferrocene"
+default-run = "global_uart"
 
 [dependencies]
 critical-section = { version = "1.1.2", features = ["restore-state-bool"] }

example-code/qemu-aarch64v8a/Cargo.toml

@@ -5,6 +5,7 @@ edition = "2021"
 authors = ["Ferrous Systems"]
 license = "MIT OR Apache-2.0"
 description = "A simple Aarch64 demo application that runs in QEMU and compiles with Ferrocene"
+default-run = "global_uart"
 
 [dependencies]
 critical-section = { version = "1.1.2", features = ["restore-state-bool"] }

training-slides/src/ferrocene-installing.md

@@ -1,10 +1,11 @@
-# Installing Ferrocene
+# Installing and Using Ferrocene
 
 ## What's in the box?
 
 * `rustc` - a compiler (★)
-* `lld` - the LLVM linker (★)
-* `cargo`/`rustdoc`/`rustfmt`/`clippy` - our usual friends
+  * `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
@@ -14,78 +15,223 @@
 
 ★: qualified tool ☆: certification in progress
 
-## Installation
+Note:
 
-* Ferrocene runs on x86-64 Linux, only (for now)
-* Ferrocene 23.06 shipped as tarballs
-* Ferrocene 24.05+ now has `criticalup`
-* Either way, get `rustc` in your `PATH`
+The lld linker and rustdoc come with the `rustc-${rustc-host}` package.
 
-## Read the Manual
+---
 
-* `/opt/ferrocene-23.06/share/doc/ferrocene/html/user-manual`
-* <https://public-docs.ferrocene.dev/main/user-manual/>
+![Portal](./images/portal.png)
+
+<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](./images/portal-docs.png)
+
+<https://docs.ferrocene.dev>
 
 ## Targets
 
-* Supported targets installed as per the rest of the toolchain
-* [Currently]:
-  * `x86_64-unknown-linux-gnu`
-  * `aarch64-unknown-none`
-  * `thumbv7em-none-eabi` + `-eabihf` (☆)
-  * `armv8r-none-eabihf` (☆)
-  * `wasm32-unknown-unknown` (☆)
+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:
 
-☆: experimental
+In stable-24.08 and earlier, these were called "Supported Targets"
 
-[Currently]: https://public-docs.ferrocene.dev/main/user-manual/targets/index.html
+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.
 
-## Downloading a release
+## Quality Managed (QM) Targets
 
-Check out the Customer Portal
+* Production Ready
+* Passes the Rust Test Suite
+* Support is available
+* ~~Signed qualification material~~
 
-<https://customers.ferrocene.dev>
+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:
+  * See [the public docs](https://public-docs.ferrocene.dev/main/user-manual/targets/index.html)
+  * Or [the customer portal](https://customers.ferrocene.dev)
+* Ferrocene is installed with [`criticalup`](https://criticalup.ferrocene.dev)
+  * It's also [open-source](https://github.com/ferrocene/criticalup)
+  * Or, you can install a specific Ferrocene release from tarballs
+* Hosts always compile for themselves (proc-macros, `build.rs`, etc)
+
+## Cross-Compilation Targets
+
+* Compiling for a machine that is not the current host
+* The list of targets from release to release
+* See [the public docs](https://public-docs.ferrocene.dev/main/user-manual/targets/index.html)
+* Or [the customer portal](https://customers.ferrocene.dev)
 
 ## Using criticalup
 
 * Our equivalent of `rustup`
 * Fetches the appropriate Ferrocene toolchain packages
-* No global Ferrocene toolchain - always specified per-project
-* Need a `criticalup.toml` file and a login token
+  * Packages are signed with [`criticaltrust`](https://docs.rs/criticaltrust)
+* 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
 
 ```toml
 manifest-version = 1
 
 [products.ferrocene]
-release = "beta-24.05-2024-03-21"
+release = "stable-24.08.0"
 packages = [
   "rustc-${rustc-host}", "rust-std-${rustc-host}", "cargo-${rustc-host}",
   "rust-src", "rust-std-aarch64-unknown-none"
 ]
 ```
 
-## Process
+## Installing Ferrocene
 
+1. Install [criticalup](https://criticalup.ferrocene.dev)
 1. Make a [token](https://customers.ferrocene.dev/users/tokens)
-2. Login with `criticalup auth set`
-3. Go to your project dir
-4. Run `criticalup install`
-5. Add `~/.local/share/criticalup/bin` to your PATH
-6. Or `rustup toolchain link ferrocene ~/.local/share/criticalup/bin`
+1. Store your token with `criticalup auth set`
+1. Go to your project dir
+1. Run `criticalup install`
 
 ## Example
 
 ```console
 $ criticalup auth set
 $ criticalup install
-info: installing product 'ferrocene' (beta-24.05-2024-03-21)
-info: downloading component 'cargo-x86_64-unknown-linux-gnu' for 'ferrocene' (beta-24.05-2024-03-21)
+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' (beta-24.05-2024-03-21)
-info: installing component 'rustc-x86_64-unknown-linux-gnu' for 'ferrocene' (beta-24.05-2024-03-21)
-$ export PATH=$HOME/.local/share/criticalup/bin:$PATH
-$ rustc --version
-rustc 1.76.0 (28b06b23f 2024-03-20) (Ferrocene by Ferrous Systems)
+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
+
+```console
+$ 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:
+
+```console
+$ 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:
+
+```console
+$ 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
+
+```text
+$ 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>

training-slides/src/ferrocene-what-it-is.md

@@ -9,6 +9,7 @@
 * Qualified per ISO 26262 / IEC 61508
 * Supplied with a warranty
 * Available with support
+* Tested differently
 
 ## Rust, not a subset
 
@@ -48,14 +49,13 @@
 
 ## Long-term Stable
 
-As of 11 March 2024, the Ferrocene releases are:
+As of 3 September 2024, the Ferrocene releases are:
 
 * *nightly* (upstream *nightly*)
 * *pre-rolling* (upstream *beta*)
 * *rolling* (upstream *stable*)
-* beta-23.06 (upstream *1.68.2*)
-* stable-23.06 (upstream *1.68.2*)
-* beta-24.05 (upstream *1.76.0*)
+* stable-24.05 (upstream *1.76*)
+* stable-24.08 (upstream *1.79*)
 
 Note:
 
@@ -95,3 +95,12 @@ If you find a bug in the compiler, we will fix it or give you details on how to
 * A subscription gets you binary downloads and access to the Known Problems list
 * Signed Qualification Documents are available (call us)
 * If you need additional support with your Rust development, we can help
+
+## Tested Differently
+
+* The Rust Project only tests *Tier 1* targets
+* We have developed our own CI
+  * Separate and parallel to that used by The Rust Project
+  * They have different goals!
+* Having multiple independent, parallel, rock solid CI pipelines can only benefit Rust
+* Our CI produces the artefacts we need for qualification