Merge pull request #1047 from nicholasbishop/bishop-build-opts

book: Add a page on building drivers

Author: phip1611

book/src/SUMMARY.md

@@ -9,6 +9,7 @@
 - [How-to](how_to/introduction.md)
   - [Using Protocols](how_to/protocols.md)
   - [Drawing to the Screen](how_to/drawing.md)
+  - [Building drivers](how_to/building_drivers.md)
 - [Concepts](concepts/introduction.md)
   - [Boot Stages](concepts/boot_stages.md)
   - [Tables](concepts/tables.md)

book/src/how_to/building_drivers.md

@@ -0,0 +1,22 @@
+# Building drivers
+
+There are [three types][spec-images] of UEFI images:
+* Application
+* Boot service driver
+* Runtime driver
+
+[By default][target-flag], Rust's UEFI targets produce applications. This can be
+changed by passing a [`subsystem`] linker flag in `rustflags` and setting the
+value to `efi_boot_service_driver` or `efi_runtime_driver`.
+
+Example:
+
+```toml
+# In .cargo/config.toml:
+[build]
+rustflags = ["-C", "link-args=/subsystem:efi_runtime_driver"]
+```
+
+[spec-images]: https://uefi.org/specs/UEFI/2.10/02_Overview.html#uefi-images
+[target-flag]: https://github.com/rust-lang/rust/blob/f4d794ea0b845413344621d89f6c945062748485/compiler/rustc_target/src/spec/base/uefi_msvc.rs#L33
+[`subsystem`]: https://learn.microsoft.com/en-us/cpp/build/reference/subsystem?view=msvc-170