forked from microsoft/mu_basecore
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move Rust documentation to Project Mu repo
Updates the repo to transition the existing Rust documentation to the [Project Mu documentation](https://microsoft.github.io/mu/). `rust_build.md` is retained since it is referenced in a number of pre-existing places and can provide a pointer to the new location. Signed-off-by: Michael Kubacki <[email protected]>
- Loading branch information
1 parent
d425f4e
commit 681dcb6
Showing
3 changed files
with
5 additions
and
492 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,144 +1,5 @@ | ||
| # Rust Build | ||
|
|
||
| Mu Basecore has integrated support to build Rust modules in the normal firmware build process. | ||
| The Rust build instructions have moved to the centralized [Project Mu documentation repo](https://microsoft.github.io/mu/). | ||
|
|
||
| [Cargo make](https://crates.io/crates/cargo-make/) is used as a build runner to allow users to build Rust packages | ||
| individually and simply on the command line similar to the way they are built during the firmware build process. It | ||
| is a CLI tool that helps abstract away many of the CLI arguments necessary to build a Rust module so that developers | ||
| can easily check, test, and build individual Rust packages without the need to copy and/or memorize a long list of | ||
| arguments. | ||
|
|
||
| Based on changes in: https://github.com/tianocore/edk2-staging/tree/edkii-rust | ||
|
|
||
| ## Generally Getting Started with Rust | ||
|
|
||
| It is recommended to: | ||
|
|
||
| 1. Update `mu_basecore` to ensure it includes the changes needed for Rust build support (as of this file being added). | ||
|
|
||
| 2. Download and install `Rust` and `cargo` from [Getting Started - Rust Programming Language (rust-lang.org)](https://www.rust-lang.org/learn/get-started) | ||
|
|
||
| 3. Verify `cargo` is working: | ||
|
|
||
| \>`cargo --version` | ||
|
|
||
| 4. Install the desired Rust tool chain | ||
|
|
||
| - Example: `1.68.2 x86_64 toolchain` | ||
|
|
||
| - Windows: | ||
|
|
||
| \>`rustup toolchain install 1.68.2-x86_64-pc-windows-msvc` | ||
|
|
||
| \>`rustup component add rust-src --toolchain 1.68.2-x86_64-pc-windows-msvc` | ||
|
|
||
| - Linux: | ||
|
|
||
| \>`rustup toolchain install 1.68.2-x86_64-unknown-linux-gnu` | ||
|
|
||
| \>`rustup component add rust-src --toolchain 1.68.2-x86_64-unknown-linux-gnu` | ||
|
|
||
| 5. Install `cargo make` | ||
|
|
||
| \>`cargo install --force cargo-make` | ||
|
|
||
| At this point, the essential Rust applications are installed, and a repo can begin to add and build Rust code. | ||
|
|
||
| ## Important Build and Config Files | ||
|
|
||
| Currently, two files are provided in Mu Basecore that play an important role in the building and formatting of Rust | ||
| code in Project Mu based repositories. | ||
|
|
||
| - `Makefile.toml` - Defines the tasks and environment settings use within the Project Mu build system to buid and | ||
| test code. | ||
|
|
||
| - `rustfmt.toml` - Defines Rust formatting options used. | ||
|
|
||
| Projects are recommended to "extend" `Makefile.toml` by following the instructions in the "Default Tasks and Extending" | ||
| section of the [cargo make documentation](https://sagiegurari.github.io/cargo-make/). Note that the file path to the | ||
| Mu Basecore file will be relative to the project's own makefile. | ||
|
|
||
| The `rustfmt.toml` file is directly provided for use in Mu Basecore and to define the formatting options expected for | ||
| Rust code in other Project Mu based repositories. | ||
|
|
||
| ## Build Variations | ||
|
|
||
| First, the simplest case is a new user approaching a package that supports Rust modules. In that case, just build the | ||
| package like "normal" (e.g., stuart build) and the "normal" build output (i.e., EFI drivers and firmware volumes) will | ||
| be produced. | ||
|
|
||
| ### Build an Individual Module | ||
|
|
||
| ```cmd | ||
| cargo make build <Module Name> | ||
| ``` | ||
|
|
||
| The following command line options are available: | ||
|
|
||
| 1. `-p PROFILE [development|release]`. `DEFAULT` = `development (debug)` | ||
| 2. `-e ARCH=[IA32|X64|AARCH64|LOCAL]`. `DEFAULT` = `X64` | ||
| 3. `-e TARGET_TRIPLE=[triple]`. | ||
|
|
||
| - `ARCH=LOCAL` is used to build any locally executable tools associated with a Rust library package (e.g., a | ||
| dual-purpose executable and library). | ||
|
|
||
| - `TARGET_TRIPLE=<triple>` is used to cross-compile locally executable tools associated with a Rust library package. | ||
|
|
||
| - Note: A Rust package must be specified. | ||
| - The output location is: | ||
| - `target/[x86_64-unknown-uefi|i686-unknown-uefi]/[debug|release]/module_name.[efi|rlib]` | ||
|
|
||
| ### Test an Individual Module | ||
|
|
||
| ```cmd | ||
| cargo make test <Optional: Module Name> | ||
| ``` | ||
|
|
||
| ```cmd | ||
| cargo make coverage <Optional: Module Name> | ||
| ``` | ||
|
|
||
| - Note: If a package is not specified, all packages will be tested. Multiple packages can be provided, comma separated. | ||
| - cargo make coverage to generate coverage results on top of testing. | ||
|
|
||
| ### Supported Build Combinations | ||
|
|
||
| 1. C source + Rust source mixed in INF (Library or Module) | ||
| - Rust source code is supported by build rule – `Rust-To-Lib-File` (`.rs` => `.lib`) | ||
|
|
||
| - Limitation: Rust code cannot have external dependencies. | ||
|
|
||
| 2. Pure Rust Module only. | ||
|
|
||
| - A `Cargo.toml` file is added to the INF file `[Sources]` section. | ||
|
|
||
| - Rust Module build is supported by build rule – `Toml-File.RUST_MODULE` (`Toml` => `.efi`) | ||
|
|
||
| - Limitation: Runtime might be a problem, such as virtual address translation for Rust code internal global | ||
| variables. | ||
|
|
||
| 3. Pure Rust Module + Pure Rust Library with Cargo Dependency. | ||
|
|
||
| - Cargo dependency means the Rust lib dependency declared in `Cargo.toml`. | ||
|
|
||
| 4. Pure Rust Module + C Library with EDK II Dependency. | ||
|
|
||
| - Rust Module build is supported by build rule – `Toml-File` (`Toml` => `.lib`) | ||
|
|
||
| - The EDK II dependency means the EDK II lib dependency declared in INF. | ||
|
|
||
| - If a Rust module is built with C, the cargo must use `staticlib`. Otherwise, `rlib` is used. | ||
| - A simple example that specifies `staticlib` in the package `Cargo.toml` file using `crate-type = ["staticlib"]` | ||
| in the `[lib]` section is shown below. | ||
|
|
||
| ```toml | ||
| [lib] | ||
| crate-type = ["staticlib"] | ||
| ``` | ||
|
|
||
| 5. C Module + Pure Rust Library with EDK II Dependency. | ||
|
|
||
| - Rust library build is supported by build rule – `Toml-File`. (`Toml` => `.lib`) | ||
|
|
||
| 6. Pure Rust Module + Pure Rust Library with EDK II Dependency. | ||
| - Same as (4) + (5). | ||
| Build details are specifically located in [Code Development/Rust Build](https://microsoft.github.io/mu/CodeDevelopment/rust_build/). |
Oops, something went wrong.