stlog

适用于资源受限设备的超轻量级日志框架

文档

许可证

许可证为以下之一

• Apache许可证2.0版本 (LICENSE-APACHE 或 http://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

除非您明确声明，否则根据Apache-2.0许可证定义的任何有意提交的工作贡献，将按照上述方式双重许可，不附加任何额外的条款或条件。

lib.rs:

适用于资源受限设备的超轻量级日志框架

查看stlog的实际应用！

特性

• O(1) 执行时间。记录任意大小的消息是在固定数量的指令中完成的。

• O(0) 内存使用。消息不会存储在目标设备内存中（.rodata）。

• 支持不同的日志级别：错误、警告、信息、调试和跟踪，严重程度递减。默认情况下，dev 配置文件记录调试和更严重的消息，而 release 配置文件记录信息和更严重的消息，但可以使用此crate的Cargo功能更改此设置。

• 提供全局日志模式

非特性

• printf 风格或其他任何类型的格式化

MSRV

此crate保证在稳定Rust 1.31及更高版本上编译。它可能在较旧版本上编译，但任何新的补丁版本都可能改变这一点。

已知限制

• 当前实现仅支持256种不同的日志字符串。此限制可能在将来被解除。

• 字符串不应包含字符 @。任何跟在此字符后面的文本都将被丢弃。

• 同一字符串不能在两个或更多宏调用中使用。启用 spanned Cargo 功能可以消除此限制。

use stlog::{error, info};

fn foo() {
    info!("Hello!");
}

fn good() {
    foo();
    foo();
}

fn bad() {
    info!("Hey!");
    info!("Hey!"); //~ ERROR symbol `Hey!` is already defined
}

fn also_bad() {
    info!("Bye!");
    error!("Bye!"); //~ ERROR symbol `Bye!` is already defined
}

要求

目标应用程序必须使用此 crate 提供的 stlog.x 链接器脚本进行链接。最简单的方法是在使用 Cargo 配置文件（.cargo/config）将 -C link-arg 添加到其他 rustc 标志中。

[target.thumbv7m-none-eabi]
rustflags = [
    "-C", "link-arg=-Tstlog.x",
    # ..
]

要解码主机上的日志，您需要 stcat 工具的 v0.2.x 版本。

示例

本地日志记录器

• 设备端

use stlog::{info, warn, Log};

struct Logger {
    // ..
}

impl Log for Logger {
    // ..
#
}

fn main() {
    let mut logger = Logger {
        // ..
    };

    info!(logger, "Hello, world!");
    warn!(logger, "The quick brown fox jumps over the lazy dog");
}

• 主机端

假设设备通过 log 通过 /dev/ttyUSB0 接口进行日志记录。

$ flash-and-run /path/to/device/binary

$ cat /dev/ttyUSB0 | stcat -e /path/to/device/binary
Sept 22 13:00:00.000 INFO Hello, world!
Sept 22 13:00:00.001 WARN The quick brown fox jumps over the lazy dog

全局日志记录器

如果省略了日志宏的第一个参数，则将通过全局日志记录器进行日志记录。必须使用 global_logger 属性 在顶层 crate 中 选择全局日志记录器。

use stlog::{info, GlobalLog};

struct Logger;

impl GlobalLog for Logger { .. }

#[global_logger]
static LOGGER: Logger = Logger;

fn main() {
    info!("Hello");
}

#[interrupt]
fn SomeInterrupt() {
    info!("World");
}

Cargo 功能

spanned

启用此功能将在 spanned 模块下添加宏的变体，这些变体包含范围信息。例如，spanned::info!("Hello") 将记录字符串 "Hello, loc: src/main.rs:12"，其中 src/main.rs:12 是宏调用的位置。

$ cargo build
error: linking with `rust-lld` failed: exit code: 1
  |
  = note: "rust-lld" (..)
  = note: rust-lld: error: no memory region specified for section '.stlog.info'
          rust-lld: error: no memory region specified for section '.stlog.error'

$ stcat -e /path/to/binary logfile
error: symbol `__stlog_error_start__` not found

$ cargo build
error: linking with `rust-lld` failed: exit code: 1
  |
  = note: "rust-lld" (..)
  = note: rust-lld: error: undefined symbol: stlog::GLOBAL_LOGGER