Crate mavspec::rust::gen

source ·
Expand description

§Rust bindings generator for MAVSpec

🇺🇦 repository crates.io docs.rs issues

This module contains Rust bindings for MAVSpec, a code generation toolchain for MAVLink protocol.

§Usage

We provide a BuildHelper that can be integrated into your build pipeline.

use mavspec::rust::gen::BuildHelper;

// Paths to XML definitions directories.
let sources = vec![
    "./message_definitions/standard",
    "./message_definitions/extra",
];
// Output path
let destination = "../tmp/mavlink";

// Generate rust bindings
BuildHelper::builder(destination)
    .set_sources(&sources)
    .generate()
    .unwrap();

For better control over included dialects you may directly pass Protocol from MAVInspect’s Inspector.

use std::path::Path;
use mavspec::rust::gen::BuildHelper;
use mavinspect::Inspector;

// Paths to XML definitions directories.
let sources = vec![
    "./message_definitions/standard",
    "./message_definitions/extra",
];

// Parse XML definitions
let protocol = Inspector::builder()
    // Define paths to XML definitions directories
    .set_sources(&sources)
    // Build configuration and parse dialects
    .build().unwrap()
    .parse().unwrap();

// Output path
let destination = "../tmp/mavlink";

// Generate rust bindings
BuildHelper::builder(destination)
    .set_protocol(protocol)
    .generate()
    .unwrap();

§Naming Conventions

In MAVSpec we are trying to keep balance between names as they appear in MAVLink XML definitions and Rust naming conventions. In most situation we favor the Rust way unless it introduces confusions. In case we failed, and you are confused, all entities are supplemented with descriptions where canonical MAVlink names are mentioned. Here is the list of the naming rules:

  • For structs and enums MAVSpec uses UpperCamelCase.
  • For message fields we use snake_case.
  • For enum entries (enum entries) we use UpperCamelCase with MAVLink enum name prefix stripped (whenever applicable). For example, if bitmask enum has name IMPORTANCE_LEVEL and flag name is IMPORTANCE_LEVEL_THE_MATTER_OF_LIFE_AND_DEATH, then flag name will be TheMatterOfLifeAndDeath.
  • For bitmask flags (enum entries for enums which are bitmasks) we use SCREAMING_SNAKE_CASE with MAVLink enum name prefix stripped (whenever applicable). For example, if bitmask enum has name VERY_IMPORTANT_FLAGS and flag name is VERY_IMPORTANT_FLAGS_THE_MATTER_OF_LIFE_AND_DEATH_FLAG, then flag name will be THE_MATTER_OF_LIFE_AND_DEATH_FLAG.
  • In the case of collision with rust keywords, we add underscore suffix. For example, type field of HEARTBEAT message will be encoded as type_.
  • In the rare cases when symbolic name starts with numeric character, it will be prefixed with _.

The last two cases of handling inconvenient names are not something of high aesthetic value but in our defence we must say that all approaches we’ve considered looked equally ugly.

§Fingerprints

MAVInspect may skip code re-generation if dialects haven’t changed. It uses 64-bit CRC fingerprint to monitor changes. Set fingerprints feature flag to enable this behavior.

This feature is useful for reducing build time during development and CI runs. Make sure that your releases are clean and do not depend on fingerprints.

§Unstable Features

Unstable features are enabled by unstable feature flag. Such features are experimental and can be changed or excluded in future releases.

Modules§

  • error
    MAVSpec errors related to generating Rust code
  • utils
    Utility functions exposed as library API.

Structs§