refactor(log)!: extract the debug::log module as a crate

This keeps the `defmt` macros in the `log` module, instead of being exported into `debug` as well.
ROMemories · Dec 13, 2024 · 0f6249e · 0f6249e
1 parent 6141b3b
commit 0f6249e
Show file tree

Hide file tree

Showing 7 changed files with 128 additions and 71 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -45,6 +45,7 @@ jobs:
                 -p ariel-os-embassy \
                 -p ariel-os-embassy-common \
                 -p ariel-os-identity \
+                -p ariel-os-log \
                 -p ariel-os-macros \
                 -p ariel-os-runqueue \
                 -p ariel-os-threads \
@@ -163,6 +164,7 @@ jobs:
             -p ariel-os-embassy-common
             -p ariel-os-hal
             -p ariel-os-identity
+            -p ariel-os-log
             -p ariel-os-macros
             -p ariel-os-random
             -p ariel-os-rt

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -18,6 +18,7 @@ members = [
   "src/ariel-os-esp",
   "src/ariel-os-hal",
   "src/ariel-os-identity",
+  "src/ariel-os-log",
   "src/ariel-os-macros",
   "src/ariel-os-nrf",
   "src/ariel-os-random",
@@ -62,6 +63,7 @@ critical-section = { version = "1.1.2" }
 portable-atomic = { version = "1.8.0", default-features = false, features = [
   "require-cas",
 ] }
+semihosting = { version = "0.1.17", default-features = false }
 
 embassy-embedded-hal = { version = "0.2.0", default-features = false }
 embassy-executor = { version = "0.6.3", default-features = false }
@@ -102,6 +104,7 @@ ariel-os-embassy-common = { path = "src/ariel-os-embassy-common" }
 ariel-os-esp = { path = "src/ariel-os-esp" }
 ariel-os-hal = { path = "src/ariel-os-hal", default-features = false }
 ariel-os-identity = { path = "src/ariel-os-identity" }
+ariel-os-log = { path = "src/ariel-os-log", default-features = false }
 ariel-os-nrf = { path = "src/ariel-os-nrf" }
 ariel-os-random = { path = "src/ariel-os-random" }
 ariel-os-rp = { path = "src/ariel-os-rp" }

diff --git a/src/ariel-os-debug/Cargo.toml b/src/ariel-os-debug/Cargo.toml
@@ -11,9 +11,8 @@ repository.workspace = true
 workspace = true
 
 [dependencies]
-defmt = { workspace = true, optional = true }
+ariel-os-log = { workspace = true }
 rtt-target = { workspace = true, optional = true }
-
 semihosting = { version = "0.1.16", optional = true }
 
 [target.'cfg(context = "xtensa")'.dependencies]
@@ -39,4 +38,12 @@ esp-println = { workspace = true, optional = true, features = ["esp32s3"] }
 
 [features]
 debug-console = []
-defmt = ["dep:defmt", "esp-println?/defmt-espflash", "rtt-target?/defmt"]
+
+defmt = [
+  "ariel-os-log/defmt",
+  "esp-println?/defmt-espflash",
+  "rtt-target?/defmt",
+]
+
+rtt-target = ["dep:rtt-target"]
+semihosting = ["dep:semihosting"]
diff --git a/src/ariel-os-debug/src/lib.rs b/src/ariel-os-debug/src/lib.rs
@@ -14,6 +14,9 @@ compile_error!(
     r#"feature "debug-console" enabled but no backend. Select feature "rtt-target" or feature "esp-println"."#
 );
 
+#[doc(inline)]
+pub use ariel_os_log as log;
+
 pub const EXIT_SUCCESS: Result<(), ()> = Ok(());
 pub const EXIT_FAILURE: Result<(), ()> = Err(());
 pub fn exit(code: Result<(), ()>) {
@@ -106,70 +109,3 @@ mod backend {
 }
 
 pub use backend::*;
-
-#[cfg(feature = "defmt")]
-pub mod log {
-    pub use defmt;
-
-    #[macro_export]
-    macro_rules! __trace {
-        ($($arg:tt)*) => {{
-            use $crate::log::defmt;
-            defmt::trace!($($arg)*);
-        }};
-    }
-
-    #[macro_export]
-    macro_rules! __debug {
-        ($($arg:tt)*) => {{
-            use $crate::log::defmt;
-            defmt::debug!($($arg)*);
-        }};
-    }
-
-    #[macro_export]
-    macro_rules! __info {
-        ($($arg:tt)*) => {{
-            use $crate::log::defmt;
-            defmt::info!($($arg)*);
-        }};
-    }
-
-    #[macro_export]
-    macro_rules! __warn {
-        ($($arg:tt)*) => {{
-            use $crate::log::defmt;
-            defmt::warn!($($arg)*);
-        }};
-    }
-
-    #[macro_export]
-    macro_rules! __error {
-        ($($arg:tt)*) => {{
-            use $crate::log::defmt;
-            defmt::error!($($arg)*);
-        }};
-    }
-
-    pub use __debug as debug;
-    pub use __error as error;
-    pub use __info as info;
-    pub use __trace as trace;
-    pub use __warn as warn;
-}
-
-#[cfg(not(feature = "defmt"))]
-pub mod log {
-    #[macro_export]
-    macro_rules! __stub {
-        ($($arg:tt)*) => {{
-            let _ = ($($arg)*); // Do nothing
-        }};
-    }
-
-    pub use __stub as debug;
-    pub use __stub as error;
-    pub use __stub as info;
-    pub use __stub as trace;
-    pub use __stub as warn;
-}
diff --git a/src/ariel-os-log/Cargo.toml b/src/ariel-os-log/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "ariel-os-log"
+version.workspace = true
+license.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+defmt = { workspace = true, optional = true }
+
+[features]
+defmt = ["dep:defmt"]
diff --git a/src/ariel-os-log/src/lib.rs b/src/ariel-os-log/src/lib.rs
@@ -0,0 +1,87 @@
+//! Provides logging facilities, powered by [`defmt`].
+
+#![cfg_attr(not(test), no_std)]
+#![deny(missing_docs)]
+#![deny(clippy::pedantic)]
+
+#[doc(hidden)]
+#[cfg(feature = "defmt")]
+pub mod log {
+    //! Provides debug logging, powered by [`defmt`].
+
+    pub use defmt::{Debug2Format, Display2Format};
+
+    // Required so the macros can access it.
+    #[doc(hidden)]
+    pub use defmt;
+
+    // The declarative macros are required because the defmt macros expect defmt to be in scope.
+
+    /// Logs a message at the trace level.
+    #[macro_export]
+    macro_rules! trace {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::trace!($($arg)*);
+        }};
+    }
+
+    /// Logs a message at the debug level.
+    #[macro_export]
+    macro_rules! debug {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::debug!($($arg)*);
+        }};
+    }
+
+    /// Logs a message at the info level.
+    #[macro_export]
+    macro_rules! info {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::info!($($arg)*);
+        }};
+    }
+
+    /// Logs a message at the warn level.
+    #[macro_export]
+    macro_rules! warn {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::warn!($($arg)*);
+        }};
+    }
+
+    /// Logs a message at the error level.
+    #[macro_export]
+    macro_rules! error {
+        ($($arg:tt)*) => {{
+            use $crate::log::defmt;
+            defmt::error!($($arg)*);
+        }};
+    }
+}
+
+#[doc(hidden)]
+#[cfg(not(feature = "defmt"))]
+pub mod log {
+    //! Stub module for when the `defmt` Cargo feature is not enabled.
+
+    #[doc(hidden)]
+    #[macro_export]
+    macro_rules! __stub {
+        ($($arg:tt)*) => {{
+            let _ = ($($arg)*); // Do nothing
+        }};
+    }
+
+    pub use __stub as debug;
+    pub use __stub as error;
+    pub use __stub as info;
+    pub use __stub as trace;
+    pub use __stub as warn;
+}
+
+#[doc(inline)]
+pub use log::*;