xxx

book/src/SUMMARY.md

@@ -3,6 +3,7 @@
 - [Introduction](introduction.md)
 - [Tutorial](tutorial/introduction.md)
  - [Creating a UEFI Application](tutorial/app.md)
+ - [Combining Rust `std` with `uefi`](tutorial/rust-std.md)
  - [Building](tutorial/building.md)
  - [Running in a VM](tutorial/vm.md)
  - [Running on Hardware](tutorial/hardware.md)

book/src/tutorial/rust-std.md

@@ -0,0 +1,18 @@
+# Combining Rust `std` with `uefi`
+
+In the `uefi` crate, we provide tooling to create a `#[no_std]` + `#[no_main]`
+binary, i.e., an UEFI image, in a convenient way. However, there is also the
+option to create a "standard" binary with Rust. The result is the same, but the
+build process and the overall programming is much more similar to regular
+Rust binaries written for Operating Systems, such as Linux, Windows, or macOS.
+
+## About `std` for `uefi`
+
+The Rust implementation of the standard library (_`std` implementation_) is
+ongoing and will evolve over the coming months and years. Over time, you will
+need less and less specific features of `uefi` and can utilize standard and
+well-known OS-independent APIs for that, as in the typical Linux application,
+for example.
+
+The `uefi` crate is suited to extend the functionality of these "standard
+binaries".

shell.nix

@@ -21,6 +21,7 @@ pkgs.mkShell {
  rustToolchain
 
  # Other
+ mdbook
  yamlfmt
  which # used by "cargo xtask fmt"
  ];

uefi-std-example/Cargo.toml

@@ -1,14 +1,11 @@
 [package]
 name = "uefi-std-example"
-description = """
-
-"""
 version = "0.1.0"
 authors = ["The Rust OSDev team"]
 publish = false
 edition = "2021"
 
 [dependencies]
-uefi = { path = "../uefi", features = [], default-features = false }
-
-log.workspace = true
+# Attention: Don't activate the panic_handler feature, as it will clash with
+# the one coming from `std`.
+uefi = { path = "../uefi", features = ["alloc"], default-features = false }

uefi-std-example/README.md

@@ -1,5 +1,18 @@
 # Minimal Rust App using `std` and `uefi`
 
+Minimal example of a "standard Rust application" that showcases how `uefi` can
+be utilized and enhance the developers experience, when `std` is available.
+
+For simplicity, this example is minimal and the documentation is focused on
+`x86_64-unknown-uefi`. However, it works similar for other supported UEFI
+platforms.
+
 ## Build
 
-Build using `cargo +nightly build` to build an `x86_64-unknown-uefi` app.
+Build the app using
+`$ cargo +nightly build --target x86_64-unknown-uefi`. To build it from the root
+directory (the Cargo workspace), append `-p uefi-std-example`.
+
+## Run
+
+The resulting `.efi` file can be found in `target/x86_64-unknown-uefi/<debug|release>/uefi-std-example.efi`.

uefi-std-example/src/main.rs

@@ -1,3 +1,6 @@
+// Note: In Rust 1.82.0-nightly and before, the `uefi_std` feature is 
+// required for accessing `std::os::uefi::env::*`. The default functionality
+// doesn't need a nightly toolchain.
 #![feature(uefi_std)]
 
 use std::os::uefi as uefi_std;