Crate peakrdl_rust_build

Expand description

§peakrdl-rust-build

Build-script helper for generating Rust register-access code from SystemRDL files using PeakRDL-rust.

§Usage

In your crate’s Cargo.toml, add:

[dependencies]
peakrdl-rust = "0.2.1"

[build-dependencies]
peakrdl-rust-build = { version = "0.7.1", features = ["download-bin"] }

In your build.rs:

peakrdl_rust_build::Generator::new()
    .rdl_file("src/regs/my_block.rdl")
    .top("my_block")
    .generate()
    .unwrap();

The Generator is a builder type for configuring the generated code. For all the options see the documentation.

Then in your src/lib.rs (or whichever module you want to include the generated code):

mod my_block {
    include!(concat!(env!("OUT_DIR"), "/my_block/mod.rs"));
}

Check the project documentation on Read the Docs to find examples of the generated code and how it can be used.

§How it Works

The .generate() function calls the PeakRDL-rust python tool to perform the actual code generation. With the download-bin feature enabled, the generator will download a peakrdl-rust binary (built using PyInstaller) from GitHub, verify its checksum, cache it, then execute it.

This behavior can be overridden in two ways:

Setting the PEAKRDL_RUST_BINARY environment variable to a local copy of the peakrdl-rust binary.
Disabling the download-bin feature of this crate to completely remove all download logic and dependencies, requiring PEAKRDL_RUST_BINARY to be set.

Note that the PEAKRDL_RUST_BINARY environment variable could also point to a wrapper script such as this one that uses uv to run PeakRDL-rust.

§Versions

If using the PEAKRDL_RUST_BINARY environment variable, the version numbers of this crate and the peakrdl-rust binary must match.

The generated code relies on the peakrdl-rust crate on crates.io, which is versioned separately. The generated code has a compile-time check to ensure a compatible version of the peakrdl-rust dependency is used.

§License

This crate is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE)
MIT license (LICENSE-MIT)

at your option.

The python exporter is licensed under LGPL-2.1. See the docs for more information and FAQs.

Structs§

Generator: Builder for configuring and running the PeakRDL-rust code generator.

Enums§

Endian: Byte or word endianness
Error: Errors that can occur when generating code with PeakRDL-rust.

Type Aliases§

Result: Result type for this crate.