mantra-rust-macros

This crate provides procedural macros to trace requirements using mantra. It also offers features to get requirement coverage via logs.

Traces

Requirement traces may be created using either the attribute macro req, or the function-like macro reqcov. See mantra-lang-tracing on how to specify requirement IDs using req or reqcov.

The attribute macro may be set anywhere attribute macros are allowed. At the moment, coverage logs are only generated if the macro is set on a function.

Examples:

use mantra_rust_macros::{req, reqcov};

/// Coverage log is generated
#[req(fn_trace)]
fn some_fn() {
    // coverage log is generated
    reqcov!(function_like_trace);
}

#[req(const_trace)]
const SOME_CONST: usize = 1;

#[req(type_trace)]
type SomeType = bool;

#[req(struct_trace)]
struct SomeStruct {
    /// Attribute macros cannot be set for fields.
    some_field: bool,
}

#[req(mod_trace)]
mod some_mod {}

#[req(trait_trace)]
trait SomeTrait {
    #[req(trait_type_trace)]
    type A;

    /// Coverage log is generated
    #[req(trait_fn_default_trace)]
    fn some_trait_fn() {}
}

Automatic documentation

Requirements set using the #[req()] attribute will generate a Requirements section in the documentation. The requirement IDs are represented as bullet list entries. If the environmental variable MANTRA_REQUIREMENT_BASE_URL is set, all IDs will be transformed to links with the content of the variable as prefix.

/// Documentation for IDs is automatically generated.
#[req(req_1, req_2)]
fn some_fn() {}

Generated documentation with MANTRA_REQUIREMENT_BASE_URL set to https://github.com/mhatzl/mantra/wiki/5-Requirements/:

Documentation for IDs is automatically generated.

# Requirements

- [req_1](https://github.com/mhatzl/mantra/wiki/5-Requirements/req_1)
- [req_2](https://github.com/mhatzl/mantra/wiki/5-Requirements/req_2)

Coverage log

• Feature log

  Enabling this feature will create coverage TRACE logs using the log crate.

• Feature stdout

  Enabling this feature will print coverage logs to stdout.

• Feature defmt

  Enabling this feature will print coverage logs using the defmt crate. This is intended for embedded devices.

Examples:

#[req(fn_trace)]
fn some_fn() {}

The generated coverage log for the code above has the form:

mantra: req-id=`fn_trace`; file='<resolved by file!()>'; line='<resolved by line!()>';

Trace extraction

The extract feature may be enabled to extract coverage data from logs. With the feature enabled, the functions extract_first_coverage() or extract_covered_reqs() may be used.