diff --git a/uefi-test-runner/Cargo.toml b/uefi-test-runner/Cargo.toml index d608362a4..3913de22a 100644 --- a/uefi-test-runner/Cargo.toml +++ b/uefi-test-runner/Cargo.toml @@ -7,7 +7,7 @@ edition = "2024" [dependencies] uefi-raw = { path = "../uefi-raw" } -uefi = { path = "../uefi", features = ["alloc", "global_allocator", "panic_handler", "logger", "qemu"] } +uefi = { path = "../uefi", features = ["alloc", "global_allocator", "panic_handler", "logger", "qemu", "log-debugcon"] } log.workspace = true diff --git a/uefi/CHANGELOG.md b/uefi/CHANGELOG.md index 3771af5e1..927f0fef2 100644 --- a/uefi/CHANGELOG.md +++ b/uefi/CHANGELOG.md @@ -9,6 +9,12 @@ - `system::with_config_table`, `system::with_stdin`, `system::with_stdout` and `system::with_stderr` now take mutably closure. - **Breaking:** The MSRV is now 1.85.1 and the crate uses the Rust 2024 edition. +- The documentation in `lib.rs` now provides guidance on how to select features + tailored to your use case. +- Feature `log-debugcon` is no longer a default feature. You only need to add + it in case you are also using the `logger` feature and if you run your UEFI + image in QEMU or Cloud Hypervisor, when the debugcon/debug-console device is + available. # uefi - 0.35.0 (2025-05-04) diff --git a/uefi/Cargo.toml b/uefi/Cargo.toml index 7afff17d0..1048c1ab4 100644 --- a/uefi/Cargo.toml +++ b/uefi/Cargo.toml @@ -15,12 +15,14 @@ license.workspace = true repository.workspace = true rust-version.workspace = true +# Feature documentation in uefi/lib.rs. [features] -# KEEP this feature list in sync with doc in lib.rs! -default = [ "log-debugcon" ] +# KEEP this feature list in sync with doc in uefi/lib.rs! +default = [ ] alloc = [] -# Generic gate to code that uses unstable features of Rust. You usually need a nightly toolchain. +# Generic gate to code that uses unstable features of Rust, needing a nightly +# toolchain. unstable = [] # Helper features: @@ -31,9 +33,6 @@ panic_handler = [] # - dependency log-debugcon: logical, not technical # - dependency panic_handler: logical, not technical qemu = ["dep:qemu-exit", "panic_handler", "log-debugcon"] -# Whether the internal logger from the helpers module should also log to -# the debugcon device (QEMU) and debug-console (cloud-hypervisor). Only works -# on x86. log-debugcon = [] [dependencies] diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 7ac51a8b1..f805cc9dc 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -120,6 +120,10 @@ //! //! ## Optional Cargo crate features //! +//! A list of recommended default features follows below. +//! +//! ### Feature List +//! //! - `alloc`: Enable functionality requiring the [`alloc`] crate from //! the Rust standard library. For example, methods that return a //! `Vec` rather than filling a statically-sized array. This requires @@ -130,10 +134,13 @@ //! allocator. This is a simple allocator that relies on the UEFI pool //! allocator. You can choose to provide your own allocator instead of //! using this feature, or no allocator at all if you don't need to -//! dynamically allocate any memory. +//! dynamically allocate any memory. Note that even without that feature, +//! some code might use the internal UEFI allocator. //! - `logger`: Logging implementation for the standard [`log`] crate //! that prints output to the UEFI console. No buffering is done; this //! is not a high-performance logger. +//! - `log-debugcon`: Whether the logger set up by `logger` should also log +//! to the debugcon device (available in QEMU or Cloud Hypervisor on x86). //! - `panic_handler`: Add a default panic handler that logs to `stdout`. //! - `unstable`: Enable functionality that depends on [unstable //! features] in the nightly compiler. @@ -147,6 +154,16 @@ //! only unfold their potential when you invoke `uefi::helpers::init` as soon //! as possible in your application. //! +//! ### Recommended Default Features +//! +//! In typical use-cases, the following features are useful for you: +//! - Building a UEFI image: +//! - Recommended: `alloc`, `global_allocator`, `logger`, `panic_handler` +//! - Optional: `log-debugcon`, `qemu`, `unstable` +//! - Building another application/library: +//! - Recommended: `alloc` +//! - Optional: `unstable` +//! //! # Discuss and Contribute //! //! For general discussions, feel free to join us in our [Zulip] and ask