From 6942b7e3f6e3d94e3c795d6efee1bd0acc0063bd Mon Sep 17 00:00:00 2001 From: pv42 Date: Tue, 6 Aug 2024 18:33:57 +0200 Subject: [PATCH 1/6] Feat: add cli argument documentation --- mavlink-bindgen/src/cli.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/mavlink-bindgen/src/cli.rs b/mavlink-bindgen/src/cli.rs index 30fee8a843..5ff37b26f1 100644 --- a/mavlink-bindgen/src/cli.rs +++ b/mavlink-bindgen/src/cli.rs @@ -4,11 +4,16 @@ use clap::Parser; use mavlink_bindgen::{emit_cargo_build_messages, format_generated_code, generate, BindGenError}; #[derive(Parser)] +/// Generate Rust bindings from MAVLink message dialect XML files. struct Cli { + /// Path to the directory containing the MAVLink dialect definitions. definitions_dir: PathBuf, + /// Path to the directory where the code is generated into, must already exist. destination_dir: PathBuf, + /// format code generated code #[arg(long)] format_generated_code: bool, + /// prints cargo build messages indicating when the code has to be rebuild #[arg(long)] emit_cargo_build_messages: bool, } From fda272cdf0f66588edaf3899dbdeeff69bdaed43 Mon Sep 17 00:00:00 2001 From: pv42 Date: Tue, 6 Aug 2024 18:34:27 +0200 Subject: [PATCH 2/6] Feat: add mavlink-bindgen readme --- mavlink-bindgen/README.md | 94 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 mavlink-bindgen/README.md diff --git a/mavlink-bindgen/README.md b/mavlink-bindgen/README.md new file mode 100644 index 0000000000..7e678a70cb --- /dev/null +++ b/mavlink-bindgen/README.md @@ -0,0 +1,94 @@ +# rust-mavlink + +[![Build status](https://github.com/mavlink/rust-mavlink/actions/workflows/test.yml/badge.svg)](https://github.com/mavlink/rust-mavlink/actions/workflows/test.yml) + +[![Crate info](https://img.shields.io/crates/v/mavlink-bindgen.svg)](https://crates.io/crates/mavlink-bindgen) +[![Documentation](https://docs.rs/mavlink-bindgen/badge.svg)](https://docs.rs/mavlink-bindgen) + +Library and CLI for code generator of the Rust implementation of the [MAVLink](https://mavlink.io/en) UAV messaging protocol. + +`mavlink-bindgen` can be used to create MAVLink bindings for Rust. This is used from `build.rs` in the [mavlink](https://crates.io/crates/mavlink) crate to create bindings from the standard MAVLink dialects in https://github.com/mavlink/mavlink. + +## Usage + +`mavlink-bindgen` can be used as a code generator from `build.rs` as done is the `mavlink` crate for a custom MAVLink dialect or as a CLI tool to generate rust binding from XML dialect definitions. The generated code will depend on the [mavlink-core](https://crates.io/crates/mavlink-core) crate in both use cases. + +### CLI + +Build using cargo with `cli` feature enabled: + +```shell +cargo build --features cli +``` + +Alternatively you can build and install `mavlink-bindgen` to you locally installed crates: + +```shell +cargo install mavlink-bindgen --features cli +``` + +Generate code using the resulting binary: + +```shell +mavlink-bindgen --format-generated-code message_definitions mavlink_dialects +``` + +The full options are shown below. + +```shell +Usage: mavlink-bindgen [OPTIONS] + +Arguments: + Path to the directory containing the MAVLink dialect definitions + Path to the directory where the code is generated into + +Options: + --format-generated-code format code generated code + --emit-cargo-build-messages prints cargo build message indicating when the code has to be rebuild + -h, --help Print help +``` + +### Library as build dependency + +Add to your Cargo.toml: + +```toml +mavlink-bindgen = "0.13.1" +``` + +Add a `build/main.rs` or `build.rs` to your project if it does not already exist. Then add the following to the `main` function to generate the code: + +```rs +let out_dir = env::var("OUT_DIR").unwrap(); +let result = match mavlink_bindgen::generate(definitions_dir, out_dir) { + Ok(r) => r, + Err(e) => { + eprintln!("{e}"); + return ExitCode::FAILURE; + } +}; +``` + +If the generated code should be formated use + +```rs + mavlink_bindgen::format_generated_code(&result); +``` + +To tell cargo when to regenerate code from the definitions use: + +```rs + mavlink_bindgen::emit_cargo_build_messages(&result); +``` + +Finally include the generated code into the `lib.rs` or `main.rs` : + +```rs +#![cfg_attr(not(feature = "std"), no_std)] +// include generate definitions +include!(concat!(env!("OUT_DIR"), "/mod.rs")); + +pub use mavlink_core::*; +``` + +This approach is used by the mavlink crate see its build script for an example. From f79fb90f2b320ad15e6b791bd4ce7a25ddcd2c6c Mon Sep 17 00:00:00 2001 From: pv42 Date: Wed, 7 Aug 2024 14:08:36 +0200 Subject: [PATCH 3/6] Fix: CouldNotReadDefinitionFile doc is copy pasted --- mavlink-bindgen/src/error.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mavlink-bindgen/src/error.rs b/mavlink-bindgen/src/error.rs index 957ec5506d..fe32023389 100644 --- a/mavlink-bindgen/src/error.rs +++ b/mavlink-bindgen/src/error.rs @@ -8,7 +8,7 @@ pub enum BindGenError { source: std::io::Error, path: std::path::PathBuf, }, - /// Represents a failure to read the MAVLink definitions directory. + /// Represents a failure to read a MAVLink definition file. #[error("Could not read definition file {path}: {source}")] CouldNotReadDefinitionFile { source: std::io::Error, From 5d658b6f2b33055fafe8d3d4c0b13deba85951cd Mon Sep 17 00:00:00 2001 From: pv42 Date: Wed, 7 Aug 2024 14:22:49 +0200 Subject: [PATCH 4/6] Feat: add doc to public functions in mavlink-bindgen's lib.rs --- mavlink-bindgen/src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/mavlink-bindgen/src/lib.rs b/mavlink-bindgen/src/lib.rs index 3448fe88da..22f1efa2ce 100644 --- a/mavlink-bindgen/src/lib.rs +++ b/mavlink-bindgen/src/lib.rs @@ -23,6 +23,9 @@ pub struct GeneratedBindings { pub mod_rs: PathBuf, } +/// Generate Rust MAVLink dialect binding for dialects present in `definitions_dir` into `destination_dir`. +/// +/// If successful returns paths of generated bindings linked to their dialect definitions files. pub fn generate, P2: AsRef>( definitions_dir: P1, destination_dir: P2, @@ -99,6 +102,7 @@ fn _generate( } } +/// Formats generated code using `rustfmt`. pub fn format_generated_code(result: &GeneratedBindings) { if let Err(error) = Command::new("rustfmt") .args( @@ -114,6 +118,7 @@ pub fn format_generated_code(result: &GeneratedBindings) { } } +/// Prints definitions for cargo that describe which files the generated code depends on, indicating when it has to be regenerated. pub fn emit_cargo_build_messages(result: &GeneratedBindings) { for binding in &result.bindings { // Re-run build if definition file changes From c82167dec15f4a6b68d5b49f4476e980e6b9b705 Mon Sep 17 00:00:00 2001 From: pv42 Date: Wed, 7 Aug 2024 14:25:42 +0200 Subject: [PATCH 5/6] Fix: improve mavlink-bindgen readme --- mavlink-bindgen/README.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/mavlink-bindgen/README.md b/mavlink-bindgen/README.md index 7e678a70cb..c813b5fc3a 100644 --- a/mavlink-bindgen/README.md +++ b/mavlink-bindgen/README.md @@ -1,46 +1,46 @@ -# rust-mavlink +# mavlink-bindgen [![Build status](https://github.com/mavlink/rust-mavlink/actions/workflows/test.yml/badge.svg)](https://github.com/mavlink/rust-mavlink/actions/workflows/test.yml) - [![Crate info](https://img.shields.io/crates/v/mavlink-bindgen.svg)](https://crates.io/crates/mavlink-bindgen) [![Documentation](https://docs.rs/mavlink-bindgen/badge.svg)](https://docs.rs/mavlink-bindgen) -Library and CLI for code generator of the Rust implementation of the [MAVLink](https://mavlink.io/en) UAV messaging protocol. +Library and CLI for generating code for the Rust implementation of the [MAVLink](https://mavlink.io/en) UAV messaging protocol. -`mavlink-bindgen` can be used to create MAVLink bindings for Rust. This is used from `build.rs` in the [mavlink](https://crates.io/crates/mavlink) crate to create bindings from the standard MAVLink dialects in https://github.com/mavlink/mavlink. +`mavlink-bindgen` can be used to create MAVLink bindings for Rust. This is used from `build.rs` in the [mavlink](https://crates.io/crates/mavlink) crate to create bindings from the standard MAVLink dialects in . ## Usage -`mavlink-bindgen` can be used as a code generator from `build.rs` as done is the `mavlink` crate for a custom MAVLink dialect or as a CLI tool to generate rust binding from XML dialect definitions. The generated code will depend on the [mavlink-core](https://crates.io/crates/mavlink-core) crate in both use cases. +`mavlink-bindgen` can be used as a code generator from `build.rs` as done is the `mavlink` crate for a custom MAVLink dialect or as a CLI tool to generate rust binding from XML dialect definitions. The generated code will depend on the [mavlink-core](https://crates.io/crates/mavlink-core) crate in both use cases. Each dialect generated will be locked behind a feature flag of the same name, that must be enabled when using the generated code. ### CLI -Build using cargo with `cli` feature enabled: +Build the binary using cargo with `cli` feature enabled: ```shell +cd mavlink-bindgen cargo build --features cli ``` -Alternatively you can build and install `mavlink-bindgen` to you locally installed crates: +Alternatively you can build and install `mavlink-bindgen` to your locally installed crates: ```shell cargo install mavlink-bindgen --features cli ``` -Generate code using the resulting binary: +To generate code using the resulting binary: ```shell mavlink-bindgen --format-generated-code message_definitions mavlink_dialects ``` -The full options are shown below. +The full command line options are shown below. ```shell Usage: mavlink-bindgen [OPTIONS] Arguments: Path to the directory containing the MAVLink dialect definitions - Path to the directory where the code is generated into + Path to the directory where the code is generated into, must already exist Options: --format-generated-code format code generated code @@ -48,6 +48,8 @@ Options: -h, --help Print help ``` +The output dir will contain a `mod.rs` file with each dialect in its own file locked behind a feature flag. + ### Library as build dependency Add to your Cargo.toml: @@ -91,4 +93,6 @@ include!(concat!(env!("OUT_DIR"), "/mod.rs")); pub use mavlink_core::*; ``` -This approach is used by the mavlink crate see its build script for an example. +Since each dialect is locked behind a feature flag these need to be enabled for the dialects to become available when using the generated code. + +This approach is used by the `mavlink` crate see its build script for an example. From 9afbb8b4af965aa29ee3aca65fc47a892dd6ff19 Mon Sep 17 00:00:00 2001 From: pv42 Date: Wed, 7 Aug 2024 14:39:29 +0200 Subject: [PATCH 6/6] Fix: set cargo toml link to readme in mavlink-bindgen, add missing repo link to mavlink-bindgen --- mavlink-bindgen/Cargo.toml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mavlink-bindgen/Cargo.toml b/mavlink-bindgen/Cargo.toml index 0a5ee88567..32403c9a2f 100644 --- a/mavlink-bindgen/Cargo.toml +++ b/mavlink-bindgen/Cargo.toml @@ -4,7 +4,8 @@ version = "0.13.1" edition = "2021" license = "MIT/Apache-2.0" description = "Library used by rust-mavlink." -readme = "../README.md" +readme = "README.md" +repository = "https://github.com/mavlink/rust-mavlink" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html