Prepare for initial crates.io release

.github/workflows/ci.yml

@@ -7,7 +7,8 @@ on:
     branches: [main]
 
 env:
-  QEMU_TARGET: thumbv8m.main-none-eabi
+  # need atomic CAS, so Cortex-M0/1 are out
+  QEMU_TARGET: thumbv7m-none-eabi
 
 jobs:
   test:
@@ -27,14 +28,18 @@ jobs:
           profile: minimal
           toolchain: ${{ matrix.rust }}
           override: true
+
       - name: Check that all crates build without warning
         run: RUSTFLAGS='--deny warnings' cargo check --all
-      - name: Run doc and lib tests
-        run: |
-          cargo test --lib
-          cargo test --doc
-      - name: Run examples as test (needs `std` feature)
-        run: cargo test --features std
+        shell: bash
+
+      - name: Check clippy output (lenient mode)
+        # run: RUSTFLAGS='--deny warnings' cargo clippy --all
+        run: cargo clippy --all
+        shell: bash
+
+      - name: Run non-QEMU tests
+        run: make non-qemu-tests
 
   qemu-test:
     strategy:
@@ -43,6 +48,7 @@ jobs:
           - stable
     # ubuntu-latest still points to 18.04, which only has QEMU 2
     runs-on: ubuntu-20.04
+
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1
@@ -52,7 +58,7 @@ jobs:
           target: ${{ env.QEMU_TARGET }}
           override: true
 
-      - name: Install QEMU (need >= 4)
+      - name: Install QEMU (want >= 4)
         run: |
           sudo apt-get update -qq >/dev/null
           sudo apt-get install -qq qemu-system-arm >/dev/null

.gitignore

@@ -1,3 +1,3 @@
-/target
+**/target
 **/*.rs.bk
 Cargo.lock

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0-alpha.1] - 2020-11-28
+
+Test the release process, meditate on the `local_*!` issue.

Cargo.toml

@@ -11,6 +11,10 @@ categories = ["algorithms", "development-tools", "embedded", "no-std"]
 keywords = ["log", "logging", "formatting"]
 edition = "2018"
 
+[package.metadata.docs.rs]
+all-features = true
+targets = []
+
 [dependencies]
 cortex-m-semihosting = { version = "0.3.5", optional = true }
 hex_fmt = "0.3.0"
@@ -23,7 +27,8 @@ insta = "1.3.0"
 [features]
 default = ["fallible", "immediate"]
 std = []
-example = ["std"]
+example = ["std", "flushers"]
+flushers = []
 semihosting = ["cortex-m-semihosting"]
 fallible = []
 immediate = []

Makefile

@@ -0,0 +1,11 @@
+test: non-qemu-tests qemu-tests
+
+non-qemu-tests:
+	cargo test --lib
+	cargo test --doc
+	cargo test --examples --features flushers,std
+	$(MAKE) -C gate-tests
+
+qemu-tests:
+	$(MAKE) -C qemu-tests test
+

README.md

@@ -1,3 +1,22 @@
 # delog
 
+[<img alt="github" src="https://img.shields.io/badge/github-nickray/delog-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/nickray/delog)
+[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-delog-66c2a5?style=for-the-badge&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/delog)
+[<img alt="build status" src="https://img.shields.io/github/workflow/status/nickray/delog/CI/main?style=for-the-badge" height="20">](https://github.com/nickray/delog/actions?query=branch%3Amain)
+
+#### License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
+2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+
+<br>
+
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
+</sub>
+
 

examples/around.rs

@@ -1,6 +1,9 @@
 #[macro_use]
 extern crate delog;
 
+#[cfg(not(all(feature = "flushers", feature = "std")))]
+compile_error!("This example needs the `flushers` and `std` features");
+
 use delog::flushers::StdoutFlusher;
 
 delog!(Delogger, 25, StdoutFlusher);
@@ -12,7 +15,7 @@ fn main() {
 
     let msg = "1234567890";
 
-    (0..10).for_each(|i| {
+    (0..10).for_each(|_| {
         info!("{}", msg);
         Delogger::flush();
     });

examples/log.rs

@@ -1,6 +1,9 @@
 #[macro_use]
 extern crate delog;
 
+#[cfg(not(all(feature = "flushers", feature = "std")))]
+compile_error!("This example needs the `flushers` and `std` features");
+
 use delog::flushers::StdoutFlusher;
 
 delog!(Delogger, 256, StdoutFlusher);

examples/try_log.rs

@@ -1,5 +1,8 @@
 use delog::{try_info, try_warn};
 
+#[cfg(not(all(feature = "flushers", feature = "std")))]
+compile_error!("This example needs the `flushers` and `std` features");
+
 use delog::flushers::StdoutFlusher;
 
 delog::delog!(Delogger, 64, StdoutFlusher);

gate-tests/Cargo.toml

@@ -14,5 +14,5 @@ path = "lib-b"
 
 [dependencies.delog]
 path = ".."
-features = ["std"]
+features = ["std", "flushers"]
 

gate-tests/src/main.rs

@@ -11,11 +11,7 @@ fn main() {
     Delogger::init(delog::LevelFilter::Info, &FLUSHER).expect("all good");
     lib_a::f();
     lib_b::g();
-    println!("log attempts: {}", delog::trylogger().unwrap().attempts());
-    println!("log successes: {}", delog::trylogger().unwrap().attempts());
-    println!("log flushes: {}", delog::trylogger().unwrap().flushes());
+    println!("{:?}", delog::trylogger().unwrap().statistics());
     Delogger::flush();
-    println!("log attempts: {}", delog::trylogger().unwrap().attempts());
-    println!("log successes: {}", delog::trylogger().unwrap().attempts());
-    println!("log flushes: {}", delog::trylogger().unwrap().flushes());
+    println!("{:?}", delog::trylogger().unwrap().statistics());
 }

qemu-tests/.cargo/config

@@ -1,7 +1,7 @@
 [build]
-target = "thumbv8m.main-none-eabi"
+target = "thumbv7m-none-eabi"
 
-[target.thumbv8m.main-none-eabi]
+[target.thumbv7m-none-eabi]
 runner = "qemu-system-arm -cpu cortex-m33 -machine musca-b1 -nographic -semihosting-config enable=on,target=native -s -kernel"
 
 rustflags = [

qemu-tests/Cargo.toml

@@ -10,9 +10,7 @@ license = "Apache-2.0 OR MIT"
 cortex-m = "0.6.1"
 cortex-m-rt = "0.6.10"
 cortex-m-semihosting = "0.3.5"
-hex-literal = "0.2.1"
 panic-semihosting = { version = "0.5.3", features = ["exit"] }
-# subtle = { version = "2.2", default-features = false }
 
 [dependencies.delog]
 path = ".."

qemu-tests/src/main.rs

@@ -1,7 +1,7 @@
 #![no_std]
 #![no_main]
 
-use cortex_m_semihosting::{debug, hprintln};
+use cortex_m_semihosting::debug;
 extern crate panic_semihosting;
 use cortex_m_rt::entry;
 
@@ -22,12 +22,13 @@ delog!(Delogger, 256, SemihostingFlusher);
 static SEMIHOSTING_FLUSHER: SemihostingFlusher = SemihostingFlusher {};
 
 fn test_runs() {
-    // do some serious work
+    // do some serious™ work
     warn!("This is a warning");
-    info!(target: "!", "This is an IMMEDIATE information");
-    info!("jeez '{:02X}'", delog::hex_str!(&[0xa1u8, 0xfF, 0x03]));
-    info!("heeb '{:#02X?}'", [0xa1u8, 0xfF, 0x03].as_ref());
-    info!("heeg '{:02X?}'", [0xa1u8, 0xfF, 0x03].as_ref());
+    info!(target: "!", "This is IMMEDIATE information");
+    info_now!("This too");
+    info!("hex_str '{}'", delog::hex_str!(&[0xa1u8, 0xfF, 0x03]));
+    info!("alternate debug '{:#02X?}'", [0xa1u8, 0xff, 0x03].as_ref());
+    info!("regular debug '{:02X?}'", [0xA1u8, 0xFF, 0x03].as_ref());
 
     // flush the logs
     Delogger::flush();
@@ -36,11 +37,12 @@ fn test_runs() {
 #[entry]
 fn main() -> ! {
 
-    Delogger::init(delog::LevelFilter::Info, &SEMIHOSTING_FLUSHER).ok();
+    Delogger::init(delog::LevelFilter::Debug, &SEMIHOSTING_FLUSHER).ok();
 
     test_runs();
 
-    hprintln!("All tests passed").ok();
+    debug_now!("{:?}", delog::trylogger().unwrap().statistics());
+    info_now!("All tests passed");
 
     debug::exit(debug::EXIT_SUCCESS);
 

src/flushers.rs

@@ -1,7 +1,10 @@
 //! Typical flushers in various environments.
 //!
-//! Availability based on cargo flags, e.g. `std` gives stdout/stderr flushers,
-//! while `semihosting` gives flushers to host's stdout/stderr.
+//! An actual firmware will likely want to implement its own flusher.
+//!
+//! Availability based on cargo flags. The `flushers` feature must always be
+//! selected. Additionally setting `std` gives stdout/stderr flushers,
+//! while additionally setting `semihosting` gives flushers to host's stdout/stderr.
 
 #[cfg(any(feature = "std", test))]
 mod std;

src/hex.rs

@@ -39,8 +39,6 @@
 use core::marker::PhantomData;
 use core::fmt;
 
-use hex_fmt;
-
 /// re-export from `hex_fmt`
 ///
 pub use hex_fmt::HexFmt;
@@ -52,6 +50,7 @@ pub use typenum::{consts, Unsigned};
 
 /// A type that specifies a separator str.
 pub trait Separator {
+    /// The actual separator str.
     const SEPARATOR: &'static str;
 }
 
@@ -76,6 +75,7 @@ where
     S: Separator,
     BytesPerBlock: Unsigned,
 {
+    /// The value to be formatted.
     pub value: &'a T,
     _separator: PhantomData<S>,
     _block_size: PhantomData<BytesPerBlock>,
@@ -182,91 +182,91 @@ macro_rules! hexstr {
 /// let hex_str = HexStr::<_, Pipe, consts::U3>(four_bytes);
 /// assert_eq!(format!("{}", hex_str), "07A1FF|C7");
 /// ```
-pub fn HexStr<'a, T: ?Sized, S: Separator, B: Unsigned>(value: &'a T) -> HexStr<'a, T, S, B> {
+pub fn HexStr<T: ?Sized, S: Separator, B: Unsigned>(value: &T) -> HexStr<T, S, B> {
     HexStr { value, _separator: PhantomData, _block_size: PhantomData }
 }
 
 /// blocks of 1 byte / 8 bits in hex, no space in between (e.g., `4A121387`)
 ///
 /// For ease of use, prefer the `hexstr!(value)` macro.
-pub fn hexstr<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, NullSeparator, consts::U1> {
+pub fn hexstr<T: ?Sized>(value: &T) -> HexStr<T, NullSeparator, consts::U1> {
     HexStr(value)
 }
 
 /// synonym for `hex_str_1`, like ISO 7816 if enclosed in single quotes (`'8A 4F 12 AA'`).
 ///
 /// For ease of use, prefer the `hex_str!(value)` macro.
-pub fn hex_str<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T> {
+pub fn hex_str<T: ?Sized>(value: &T) -> HexStr<T> {
     HexStr(value)
 }
 
 /// blocks of 1 byte / 8 bits in hex, space in between (e.g., `4A 12 13 87`)
 ///
 /// For ease of use, prefer the `hex_str!(value)` macro.
-pub fn hex_str_1<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U1> {
+pub fn hex_str_1<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U1> {
     HexStr(value)
 }
 
 /// blocks of 2 bytes / 16 bits in hex, space in between (e.g., `4A12 1387`)
 ///
 /// For ease of use, prefer the `hex_str!(value, 2)` macro.
-pub fn hex_str_2<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U2> {
+pub fn hex_str_2<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U2> {
     HexStr(value)
 }
 
 /// blocks of 3 bytes / 24 bits in hex, space in between (e.g., `4A1213 871234 ABCD`)
 ///
 /// For ease of use, prefer the `hex_str!(value, 3)` macro.
-pub fn hex_str_3<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U3> {
+pub fn hex_str_3<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U3> {
     HexStr(value)
 }
 
 /// blocks of 4 bytes / 32 bits in hex, space in between (e.g., `4A121387 1234ABCD`)
 ///
 /// For ease of use, prefer the `hex_str!(value, 4)` macro.
-pub fn hex_str_4<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, typeint!(4)> {
+pub fn hex_str_4<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, typeint!(4)> {
     HexStr(value)
 }
 
 /// blocks of 5 bytes / 40 bits in hex, space in between (e.g., `4A12138712 34ABCD`)
 ///
 /// For ease of use, prefer the `hex_str!(value, 5)` macro.
-pub fn hex_str_5<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U5> {
+pub fn hex_str_5<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U5> {
     HexStr(value)
 }
 
 /// blocks of 8 bytes / 64 bits in hex, space in between
 ///
 /// For ease of use, prefer the `hex_str!(value, 8)` macro.
-pub fn hex_str_8<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U8> {
+pub fn hex_str_8<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U8> {
     HexStr(value)
 }
 
 /// blocks of 16 bytes / 128 bits in hex, space in between
 ///
 /// For ease of use, prefer the `hex_str!(value, 16)` macro.
-pub fn hex_str_16<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U16> {
+pub fn hex_str_16<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U16> {
     HexStr(value)
 }
 
 /// blocks of 20 bytes / 160 bits in hex, space in between
 ///
 /// For ease of use, prefer the `hex_str!(value, 20)` macro.
-pub fn hex_str_20<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U20> {
+pub fn hex_str_20<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U20> {
     HexStr(value)
 }
 
 /// blocks of 32 bytes / 256 bits in hex, space in between
 ///
 /// For ease of use, prefer the `hex_str!(value, 32)` macro.
-pub fn hex_str_32<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U32> {
+pub fn hex_str_32<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U32> {
     HexStr(value)
 }
 
 /// blocks of 64 bytes / 512 bits in hex, space in between
 ///
 /// For ease of use, prefer the `hex_str!(value, 64)` macro.
-pub fn hex_str_64<'a, T: ?Sized>(value: &'a T) -> HexStr<'a, T, SpaceSeparator, consts::U64> {
+pub fn hex_str_64<T: ?Sized>(value: &T) -> HexStr<T, SpaceSeparator, consts::U64> {
     HexStr(value)
 }