Add xtask command check-unused-deps and remove unused deps/features (#3967)

* Add xtask command check-unused-deps and remove unused deps/features

* fix changelog

* reviews, move check into nightly-ci

* reviews

* readd document-features to esp-preemt

* Just cargo machete

.github/workflows/ci_nightly.yml

@@ -56,3 +56,9 @@ jobs:
               --body "Nightly CI Workflow Failed! [View the failed job](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})." \
               --label "ci-nightly"
           fi
+
+      # Check for unused dependencies through esp-hal packages
+      - name: Install and run cargo machete
+        run: |
+          cargo install cargo-machete
+          cargo machete

esp-bootloader-esp-idf/Cargo.toml

@@ -52,19 +52,21 @@ std = ["dep:crc", "dep:md-5"]
 #! ### Chip selection
 #! One of the following features must be enabled to select the target chip:
 
-# The following trailing spaces ("## ") are important to display the feature names.
-
-## 
+##
 esp32c2   = ["esp-rom-sys/esp32c2"]
-## 
+##
 esp32c3   = ["esp-rom-sys/esp32c3"]
-## 
+##
 esp32c6   = ["esp-rom-sys/esp32c6"]
-## 
+##
 esp32h2   = ["esp-rom-sys/esp32h2"]
-## 
+##
 esp32     = ["esp-rom-sys/esp32"]
-## 
+##
 esp32s2   = ["esp-rom-sys/esp32s2"]
-## 
+##
 esp32s3   = ["esp-rom-sys/esp32s3"]
+
+# "md-5" is hidden behind `std` feature and `cargo machete` incorrectly marks it as unused.
+[package.metadata.cargo-machete]
+ignored = ["md-5"]

esp-hal-embassy/Cargo.toml

@@ -28,7 +28,6 @@ static_cell               = "2.1.0"
 # Unstable dependencies that are not (strictly) part of the public API
 document-features         = "0.2.11"
 embassy-sync              = { version = "0.6.2" }
-embassy-time              = { version = "0.4.0" }
 embassy-time-driver       = { version = "0.2.0", features = [ "tick-hz-1_000_000" ] }
 embassy-time-queue-utils  = { version = "0.1.0", features = ["_generic-queue"] }
 esp-config                = { version = "0.5.0", path = "../esp-config" }

esp-preempt/Cargo.toml

@@ -46,13 +46,26 @@ esp-hal = { version = "1.0.0-rc.0", path = "../esp-hal", features = ["unstable"]
 
 [features]
 default = ["esp-alloc"]
+
+## Enable the use of the `esp-alloc` crate for dynamic memory allocation.
 esp-alloc = ["dep:esp-alloc"]
+
+#! ### Chip selection
+#! One of the following features must be enabled to select the target chip:
+
+##
 esp32 = ["esp-hal/esp32", "esp-metadata-generated/esp32"]
+##
 esp32c2 = ["esp-hal/esp32c2", "esp-metadata-generated/esp32c2"]
+##
 esp32c3 = ["esp-hal/esp32c3", "esp-metadata-generated/esp32c3"]
+##
 esp32c6 = ["esp-hal/esp32c6", "esp-metadata-generated/esp32c6"]
+##
 esp32h2 = ["esp-hal/esp32h2", "esp-metadata-generated/esp32h2"]
+##
 esp32s2 = ["esp-hal/esp32s2", "esp-metadata-generated/esp32s2"]
+##
 esp32s3 = ["esp-hal/esp32s3", "esp-metadata-generated/esp32s3"]
 
 #! ### Logging Feature Flags

esp-preempt/src/lib.rs

@@ -13,7 +13,8 @@
 //! // let esp_radio_controller = esp_radio::init().unwrap();
 //! # }
 //! ```
-
+//! ## Feature Flags
+#![doc = document_features::document_features!()]
 #![no_std]
 #![cfg_attr(xtensa, feature(asm_experimental_arch))]
 

esp-radio/Cargo.toml

@@ -28,7 +28,6 @@ esp-radio-preempt-driver = { version = "0.0.1", path = "../esp-radio-preempt-dri
 instability = "0.3.9"
 
 # Unstable dependencies that are not (strictly) part of the public API
-allocator-api2 = { version = "0.3.0", default-features = false, features = ["alloc"] }
 document-features  = "0.2.11"
 esp-alloc = { version = "0.8.0", path = "../esp-alloc", optional = true }
 esp-config = { version = "0.5.0", path = "../esp-config" }
@@ -186,3 +185,7 @@ features = [
   "esp-hal/default",
 ]
 default-target = "riscv32imc-unknown-none-elf"
+
+# `esp-alloc` and `xtensa-lx-rt` are hidden behind features so `cargo machete` incorrectly marks it as unused.
+[package.metadata.cargo-machete]
+ignored = ["esp-alloc", "xtensa-lx-rt"]

esp-rom-sys/Cargo.toml

@@ -22,9 +22,7 @@ test  = false
 
 [dependencies]
 cfg-if              = "1.0.1"
-defmt               = { version = "1.0.1", optional = true }
 document-features   = "0.2.11"
-log-04              = { package = "log", version = "0.4.26", optional = true }
 
 [build-dependencies]
 esp-metadata-generated = { version = "0.1.0", path = "../esp-metadata-generated", features = ["build-script"] }
@@ -33,25 +31,17 @@ esp-metadata-generated = { version = "0.1.0", path = "../esp-metadata-generated"
 #! ### Chip selection
 #! One of the following features must be enabled to select the target chip:
 
-# The following trailing spaces ("## ") are important to display the feature names.
-
-## 
+##
 esp32   = []
-## 
+##
 esp32c2 = []
-## 
+##
 esp32c3 = []
-## 
+##
 esp32c6 = []
-## 
+##
 esp32h2 = []
-## 
+##
 esp32s2 = []
-## 
+##
 esp32s3 = []
-
-## Enable support for version 0.4 of the `log` crate
-log-04 = ["dep:log-04"]
-
-## Enable support for `defmt`
-defmt = ["dep:defmt"]

esp-rom-sys/build.rs

@@ -20,11 +20,6 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     let chip = esp_metadata_generated::Chip::from_cargo_feature()?;
 
-    // Log and defmt are mutually exclusive features. The main technical reason is
-    // that allowing both would make the exact panicking behaviour a fragile
-    // implementation detail.
-    assert_unique_features!("log-04", "defmt");
-
     // Define all necessary configuration symbols for the configured device:
     chip.define_cfgs();
 

esp-storage/Cargo.toml

@@ -40,21 +40,19 @@ bytewise-read = []
 #! ### Chip selection
 #! One of the following features must be enabled to select the target chip:
 
-# The following trailing spaces ("## ") are important to display the feature names.
-
-## 
+##
 esp32c2   = ["esp-rom-sys/esp32c2"]
-## 
+##
 esp32c3   = ["esp-rom-sys/esp32c3"]
-## 
+##
 esp32c6   = ["esp-rom-sys/esp32c6"]
-## 
+##
 esp32h2   = ["esp-rom-sys/esp32h2"]
-## 
+##
 esp32     = ["esp-rom-sys/esp32"]
-## 
+##
 esp32s2   = ["esp-rom-sys/esp32s2"]
-## 
+##
 esp32s3   = ["esp-rom-sys/esp32s3"]
 ## Used for testing on a host.
 emulation = []

examples/ieee802154/ieee802154_send_broadcast_frame/Cargo.toml

@@ -17,7 +17,6 @@ esp-radio = { path = "../../../esp-radio", features = [
     "ieee802154",
     "unstable",
 ] }
-heapless = "0.8.0"
 ieee802154 = "0.6.1"
 
 [features]

examples/ieee802154/ieee802154_send_frame/Cargo.toml

@@ -17,7 +17,6 @@ esp-radio = { path = "../../../esp-radio", features = [
     "ieee802154",
     "unstable",
 ] }
-heapless = "0.8.0"
 ieee802154 = "0.6.1"
 
 [features]

hil-test/Cargo.toml

@@ -239,7 +239,6 @@ embedded-io        = "0.6.1"
 embedded-io-async  = "0.6.1"
 embedded-can       = "0.4.1"
 embedded-hal-async = "1.0.0"
-embedded-hal-nb    = "1.0.0"
 esp-alloc          = { path = "../esp-alloc", optional = true }
 esp-backtrace      = { path = "../esp-backtrace", default-features = false, features = ["defmt", "semihosting"] }
 esp-bootloader-esp-idf = { path = "../esp-bootloader-esp-idf" }
@@ -251,7 +250,6 @@ esp-radio           = { path = "../esp-radio", optional = true }
 portable-atomic    = "1.11.0"
 static_cell        = { version = "2.1.0" }
 semihosting        = { version = "0.1", features= ["stdio", "panic-handler"] }
-xtensa-lx-rt       = { path = "../xtensa-lx-rt", optional = true }
 
 [dev-dependencies]
 crypto-bigint       = { version = "0.5.5", default-features = false }
@@ -375,3 +373,7 @@ incremental      = false
 opt-level        = 3
 lto              = false # LTO (thin or fat) miscompiles some tests on RISC-V
 overflow-checks  = true
+
+# `cargo machete` incorrectly marks it as unused.
+[package.metadata.cargo-machete]
+ignored = ["semihosting"]

xtask/src/lib.rs

@@ -41,6 +41,7 @@ pub mod semver_check;
 )]
 #[serde(rename_all = "kebab-case")]
 #[strum(serialize_all = "kebab-case")]
+/// Represents the packages in the `esp-hal` workspace.
 pub enum Package {
     EspAlloc,
     EspBacktrace,
@@ -110,6 +111,7 @@ impl Package {
             .any(|line| line.contains("asm_experimental_arch"))
     }
 
+    /// Does the package have a migration guide?
     pub fn has_migration_guide(&self, workspace: &Path) -> bool {
         let package_path = workspace.join(self.to_string());
 
@@ -130,6 +132,7 @@ impl Package {
         false
     }
 
+    /// Does the package need to be built with the standard library?
     pub fn needs_build_std(&self) -> bool {
         use Package::*;
 
@@ -337,6 +340,7 @@ impl Package {
         }
     }
 
+    /// Creates a tag string for this [`Package`] combined with a semantic version.
     pub fn tag(&self, version: &semver::Version) -> String {
         format!("{self}-v{version}")
     }
@@ -349,6 +353,7 @@ impl Package {
 
 #[derive(Debug, Clone, Copy, strum::Display, clap::ValueEnum, Serialize, Deserialize)]
 #[strum(serialize_all = "lowercase")]
+/// Represents the versioning scheme for a package.
 pub enum Version {
     Major,
     Minor,
@@ -533,6 +538,7 @@ pub fn windows_safe_path(path: &Path) -> PathBuf {
     PathBuf::from(path.to_str().unwrap().to_string().replace("\\\\?\\", ""))
 }
 
+/// Format the specified package in the workspace using `cargo fmt`.
 pub fn format_package(workspace: &Path, package: Package, check: bool) -> Result<()> {
     log::info!("Formatting package: {}", package);
     let package_path = workspace.join(package.as_ref());
@@ -584,6 +590,7 @@ fn format_package_path(workspace: &Path, package_path: &Path, check: bool) -> Re
     cargo::run(&cargo_args, &package_path)
 }
 
+/// Update the metadata and chip support table in the esp-hal README.
 pub fn update_metadata(workspace: &Path, check: bool) -> Result<()> {
     update_chip_support_table(workspace)?;
     generate_metadata(workspace, save)?;
@@ -677,6 +684,7 @@ fn update_chip_support_table(workspace: &Path) -> Result<()> {
     Ok(())
 }
 
+/// Recursively find all packages in the given path that contain a `Cargo.toml` file.
 pub fn find_packages(path: &Path) -> Result<Vec<PathBuf>> {
     let mut packages = Vec::new();
 

xtask/src/main.rs

@@ -12,6 +12,7 @@ use xtask::{
     Package,
     cargo::{CargoAction, CargoArgsBuilder},
     commands::*,
+    update_metadata,
 };
 
 // ----------------------------------------------------------------------------
@@ -171,7 +172,7 @@ fn main() -> Result<()> {
         Cli::LintPackages(args) => lint_packages(&workspace, args),
         Cli::SemverCheck(args) => semver_checks(&workspace, args),
         Cli::CheckChangelog(args) => check_changelog(&workspace, &args.packages, args.normalize),
-        Cli::UpdateMetadata(args) => xtask::update_metadata(&workspace, args.check),
+        Cli::UpdateMetadata(args) => update_metadata(&workspace, args.check),
     }
 }