doc: help with feature selection

Author: phip1611

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
 

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]

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