Ferrocene Documentation › Evaluation Report
Ferrocene logo

Evaluation Report

3. Use Cases

3.1. Installing Ferrocene

Identifier: RUSTC_UC0_INST

Actor(s): User, tar (compression utility)

Input: A Ferrocene release tarball.

Output: The directory structure and contents of Ferrocene.

Environment constraints: tar is correctly installed.

Description:

  1. The user downloads all the archives needed to install Ferrocene.

  2. The user extracts each archive into the installation directory using tar:

    tar -C path/to/installation -xf path/to/archive.tar.xz

3.2. Building a Library

3.2.1. rlib

Identifier: RUSTC_UC1_RLIB

Actor(s): User, rustc.

Input: A Rust compilation unit.

Output: A static Rust library.

Environment constraints: Ferrocene is correctly installed and the environment is correctly set.

Description:

  1. The user calls rustc with the following command line arguments:

    --edition 2021
--crate-type rlib
<path>
# where <path> is the path to the root of the compilation unit, as a
# positional argument.

  2. rustc parses the command line arguments.

  3. rustc parses the Rust compilation unit.

  4. rustc analyzes the Rust compilation unit.

  5. rustc generates LLVM IR for the Rust compilation unit.

  6. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

  7. LLVM generates a static Rust library.

  8. (Optional): If the user is building a certified library, the user must verify that only certified functions from the core library are used.

3.2.2. staticlib

Identifier: RUSTC_UC2_STATICLIB

Actor: User, rustc.

Input: A Rust compilation unit.

Output: A C-compatible static library.

Environment constraints: Ferrocene is correctly installed and the environment is correctly set.

Description:

  1. The user calls rustc with the following command line arguments:

    --edition 2021
--crate-type staticlib
<path>
# where <path> is the path to the root of the compilation unit, as a
# positional argument.

  2. rustc parses the command line arguments.

  3. rustc parses the Rust compilation unit.

  4. rustc analyzes the Rust compilation unit.

  5. rustc generates LLVM IR for the Rust compilation unit.

  6. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

  7. LLVM generates a C-compatible static library.

  8. (Optional): If the user is building a certified library, the user must verify that only certified functions from the core library are used.

3.3. Building an Executable

Identifier: RUSTC_UC3_EXEC

Actor: User, rustc.

Input: A Rust compilation unit.

Output: A Rust executable.

Environment constraints: Ferrocene is correctly installed, the compilation unit has the proper file extension, and the environment is correctly set.

Description:

  1. The user calls rustc with the following command line arguments:

    --codegen-units 1
--edition 2021
<path>
# where <path> is the path to the root of the compilation unit, as a
# positional argument.

  2. rustc parses the command line arguments.

  3. rustc parses the Rust compilation unit.

  4. rustc analyzes the Rust compilation unit.

  5. rustc generates LLVM IR for the Rust compilation unit.

  6. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

  7. LLVM generates an object file.

  8. rustc invokes the linker, passing the generated object file along with linker-related arguments.

  9. The linker generates a Rust executable.

  10. (Optional): If the user is building a certified executable, the user must verify that only certified functions from the core library are used.

3.3.1. Linked to a static Rust library

Identifier: RUSTC_UC4_EXEC_RLIB

Actor: User, rustc.

Input: A Rust compilation unit, a static Rust library.

Output: A Rust executable linked to a static Rust library.

Environment constraints: Ferrocene is correctly installed, a static Rust library generated with the same rustc, the compilation unit has the proper file extension, and the environment is correctly set. If multiple static Rust libraries are used, then their names must be unique within the set of all directories included by compiler argument -L.

Description:

  1. (Optional): The user performs use case RUSTC_UC1_RLIB to generate a static Rust library.

  2. The user calls rustc with the following command line arguments:

    --codegen-units 1
--edition 2021
-L <directory>
--extern <name>
<path>
# where <directory> is the path to the directory that contains the static
# Rust library, <name> is the name of the static Rust library, and <path>
# is the path to the root of the compilation unit, as a positional argument.

  3. rustc parses the command line arguments.

  4. rustc parses the Rust compilation unit.

  5. rustc analyzes both the Rust compilation unit and the Rust library.

  6. rustc generates LLVM IR for the Rust compilation unit.

  7. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

  8. LLVM generates an object file.

  9. rustc invokes the linker, passing the generated object file along with linker-related arguments.

  10. The linker generates a Rust executable that links to a static Rust library.

  11. (Optional): If the user is building a certified executable, the user must verify that only certified functions from the core library are used.

3.4. Building Mixed-Language Programs

Identifier: RUSTC_UC5_EXEC_CLIB

Actor: User, rustc, a C toolchain.

Input: A Rust compilation unit, a C library.

Output: A Rust executable that links to a C library.

Environment constraints: The C and Ferrocene toolchains are installed, the compilation unit has the proper file extension, and the environment is correctly set. If multiple C libraries are used, then their names must be unique within the set of all directories included by compiler argument -L.

Description:

  1. (Optional): The user generates a library using a C toolchain.

  2. The user calls rustc with the following command line arguments:

    --codegen-units 1
--edition 2021
-L <directory>
-l <name>
<path>
# where <directory> is the path to the directory that contains the C
# library, <name> is the name of the C library, and <path> is the path to
# the root of the compilation unit, as a positional argument.

  3. rustc parses the command line arguments.

  4. rustc parses the Rust compilation unit.

  5. rustc analyzes the Rust compilation unit.

  6. rustc generates LLVM IR for the Rust compilation unit.

  7. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

  8. LLVM generates an object file.

  9. rustc invokes the linker, passing the generated object file along with linker-related arguments.

  10. The linker generates a Rust executable that links to a C library.

  11. (Optional): If the user is building a certified executable, the user must verify that only certified functions from the core library are used.

3.5. Building a procedural macro and using it in another crate

Note

The second part “Use the proc-macro crate” can be done for any crate type. It will be done on the example of an rlib, but this can be adapted by changing the passed --crate-type. For the purpose of analysing potential errors related to procedural macros, the crate type of the second part does not matter.

Identifier: RUSTC_UC6_PROC_MACRO

Actor(s): User, rustc.

Input: Two Rust compilation units.

Output: A static Rust library.

Environment constraints: Ferrocene is correctly installed and the environment is correctly set.

Description:

  1. Compile the proc-macro crate

    1. The user calls rustc with the following command line arguments

      --edition 2021
--crate-name <name>
--crate-type proc-macro
--extern proc_macro
<proc_macro_path>
# <proc_macro_path> is the path to the root of the first compilation unit, as a positional argument.
# <name> is the name given to the proc-macro library

    2. rustc parses the command line arguments.

    3. rustc parses the Rust compilation unit.

    4. rustc analyzes the Rust compilation unit.

    5. rustc generates LLVM IR for the Rust compilation unit.

    6. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

    7. LLVM generates an object file.

    8. rustc invokes the linker, passing the generated object file along with linker-related arguments.

    9. The linker generates a dynamic Rust library lib<name>.so that links to the proc_macro library.

  2. Use the proc-macro crate

    1. The user calls rustc with the following command line arguments

      --edition 2021
--crate-type rlib
--extern <name>=lib<name>.so
<path>
# <path> is the path to the root of the second compilation unit, as a positional argument.
# <name> is the name given to the proc-macro library in the step before

    2. rustc parses the command line arguments.

    3. rustc parses the Rust compilation unit.

    4. rustc dynamically loads lib<name>.so

    5. rustc executes all procedural macros on the syntax tree.

    6. rustc analyzes the Rust compilation unit.

    7. rustc generates LLVM IR for the Rust compilation unit.

    8. rustc invokes LLVM, passing the generated LLVM IR along with LLVM-related arguments.

    9. LLVM generates a static Rust library.

    10. (Optional): If the user is building a certified executable, the user must verify that only certified functions from the core library are used.