Blog coding article

Knurling-rs changelog #11

Lotte
Article

Knurling-rs changelog #11

Published on 4 min read
Open Source Project
Knurling icon
Knurling
A tool set to develop embedded applications faster.
Details ❤️ Sponsor

    This is the eleventh changelog (and the last in 2020) for Knurling-rs, our push to sustainably build better tooling for developing and debugging Rust software for embedded systems. Knurling-rs includes a suite of tools that make it easier to develop, log, debug, and test your embedded Rust libraries and applications!

    Knurling-rs is supported by our sponsors on GitHub. If you're interested in seeing more projects like this, consider becoming a sponsor today!

    Highlights

    defmt gets display hints

    ASCII and hexadecimal display hints

    ⚠️ Note that this update is currently git version only; it will land in the defmt v0.2 crates.io-release as it is a breaking change. If you're using the git version of defmt you will have to adjust your codebase after updating!

    We've added display hints as described in defmt RFC #270 in #313. With display hints, you can specify the format in which to display the data you're printing.

    This breaks the current defmt prining syntax (but is now aligned with std Rust formatting)– instead of : types are now prefixed with =, and the display hints start with :

    // OLD syntax: will be rejected
    info!("{:u8}", 42);
    
    // NEW syntax: types are prefixed by '='; display hints
    // are prefixed by ':'.
    info!("{=u8:x}", 42);
    // prints 'INFO 0x2a'
    
    // Of course, display hints can also be omitted
    info!("{=u8}", 42);
    
    // Note that this works too and is now in line with the
    // Rust std formatting syntax
    info!("{:x}", 42);
    
    // Display hints propagate inwards and apply to
    // struct / enum fields (recursively)
    struct S { x: u8, y: u8 }
    
    info!("{:x}", S { x: 32, y: 33 });
    // prints 'INFO S { x: 0x20, y: 0x21 }'
    

    The following display hints are currently supported:

    • x, lowercase hexadecimal
    • X, uppercase hexadecimal
    • ?, core::fmt::Debug-like
    • b, binary
    • a, ASCII

    You can also combine display hints with bitfields:

    defmt::info!("{0=0..2:x} {0=3..7:b}", 42u8);
    // prints 'INFO 0x2 0b101'
    

    And while we were at it, we made {} behave like v0.1.x's {:?} ({=?} in v0.2.0), so these are equivalent now:

    // this compiles
    defmt::info!("{=?}", 42);
    
    // this compiles too
    defmt::info!("{}", 42);
    

    The easiest way to try the git version of defmt is to use the next branch of our Cargo project template, app-template.

    versioned defmt docs

    With defmt v0.1.x published on crates.io only getting bugfix updates and the defmt git version v0.2 getting breaking API changes, we've decided to host to versions of the defmt docs:

    https://defmt.ferrous-systems.com continues to be the destination for defmt docs as published on crates.io

    https://defmt-next.ferrous-systems.com will host documentation for the git version of defmt with all of its breaking changes from now on

    defmt can now format single chars

    With #304, defmt now also supports formatting single chars:

    defmt::info!("x = {=char}", 'y');
    

    No new knurling-sessions content

    Due to illness, there will be no new knurling-sessions content until January 11, 2021. We've already re-structured our approach to the next sessions project to mitigate situations like these in the future. Thank you for your understanding.

    Improvements

    defmt

    The following changes are now available in the git version of defmt, and will be included in the upcoming 0.2 crates.io release:

    • #300 #[derive] now uses built-in primitive formatting for primitive references
    • #302 derive(Format)now supports more than 256 variants
    • #304 impls Format for chars
    • #305 Formatter is now passed by value, i.e. consumed during formatting
    • #312 str fields in structs are now treated as a native type by the encoder instead of going through the Format trait
    • #313 add display hints

    Thank you Sh3rm4n for contributing #300, #302 and #299!

    Fixes

    defmt

    • #310, #311 remove the runtime check (and matching tests) if the write! macro was called multiple times as this can no longer happen since write! now consumes the Formatter due to #305.

    Version Update Notification

    We've bumped no versions of our crates.io releases as a result of the changes listed above. Note that the defmt updates listed in this changelog are github-only; they will land in the v0.2 crates.io release.

    Internal Improvements

    defmt

    • #301 fixes the nightly builds after a linked_list_allocator feature change
    • #303 we've employed the help of bors

    probe-run

    • #121, #123 we've employed the help of bors
    • #122 git dependencies on defmt sub-crates were bumped

    Upcoming break

    Just a reminder: the knurling team will be taking a break during the last two weeks of 2020 so this is the last changelog post of 2020. We'll be back, fully recharged, on the week of January 4, 2021.

    Knurling is mainly funded through GitHub sponsors. Sponsors get early access to the tools we are building and help us to support and grow the knurling tools and courses. Thank you to all of the people already sponsoring our work through the Knurling project!