Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Compilation

Drivers written with device-driver need to be compiled.

There are multiple ways to compile a ddsl manifest:

  • CLI, using the ddc command
  • Rust proc-macro
  • Playground on the website

All of these share the same build options. Those are laid out below. Some ways of compiling have some options preselected. Check the tool specific chapters for that.

Build options

Build options are split in three:

  • General
  • Target specific
  • Tool specific

The options are parsed using clap. For detailed help, use --help as an argument and clap will show the help text that’s shown below.

Any argument that starts with unstable is exempt from semver and thus should not be relied upon unless the version of device-driver is pinned. Their behavior and names may change at any point or the option might be removed too.

General

The general build options are available everywhere and change how the compiler acts.

The Rust compile macro always uses the Rust target, and so there these options don’t have a rust subcommand and include the Rust target options.

Usage: [OPTIONS] <COMMAND>

Commands:
  rust  Generate Rust code
  help  Print this message or the help of the given subcommand(s)

Options:
      --unstable-ui-test-mode
          Improves reproducibility across versions

      --timings=<TIMINGS>
          When enabled, a diagnostic is printed with information about the compiler performance. Exact format of the diagnostic is unstable
          
          [default: off]
          [possible values: off, show, verbose]

      --unstable-mir-randomize-seed=<SEED>
          The seed to use for randomization. If not specified, a random seed is used

      --unstable-mir-randomize-passes
          Randomize the order of the mir passes

      --unstable-mir-check-assumptions
          Run assumption checks for the passes

  -h, --help
          Print help

Target - Rust

All Rust target specific features start with --rust.

Usage: [OPTIONS]

Options:
      --rust-defmt-feature=<FEATURE>
          When specified, defmt implementations will be generated using this cfg feature flag

  -h, --help
          Print help

Tool - CLI

The cli can be installed using:

cargo install device-driver-cli

This gives access to the build command. If you want be able to convert formats to ddsl, then add the appropriate converter feature, like --features converter-dd-v1. This is done to improve compile times. It’s possible to use --all-features, but right now that only compiles using nightly.

In the future more methods of distribution may become available. (If you have experience with this, help is very much wanted!)

Once installed, you can use the compiler using the ddc command (device-driver compiler):

ddc --help

Commands

The command line compiler for the device-driver toolkit

Usage: ddc <COMMAND>

Commands:
  build     Compile DDSL to the target output
  gen-docs  Generate docs about the compiler
  convert   The format to convert into DDSL
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

  -V, --version
          Print version
Build

The build command is the primary command for users and needs additional information about input and output. The rest of the options are those from the general section.

Usage: [OPTIONS] <COMMAND>

Commands:
  rust  Generate Rust code
  help  Print this message or the help of the given subcommand(s)

Options:
  -s, --source <FILE>
          Path to the input file

  -o, --output <FILE>
          Path to output location. Any existing file is overwritten. If not provided, the output is written to stdout

      --unstable-ui-test-mode
          Improves reproducibility across versions

      --timings=<TIMINGS>
          When enabled, a diagnostic is printed with information about the compiler performance. Exact format of the diagnostic is unstable
          
          [default: off]
          [possible values: off, show, verbose]

      --unstable-mir-randomize-seed=<SEED>
          The seed to use for randomization. If not specified, a random seed is used

      --unstable-mir-randomize-passes
          Randomize the order of the mir passes

      --unstable-mir-check-assumptions
          Run assumption checks for the passes

  -h, --help
          Print help
Gen-docs

Generates documentation that is used by this book about the compiler from the source. This command is only available when the CLI is compiled with the gen-docs feature flag.

It’s not quite intended for normal use. The output is unstable.

Usage: --output <DIR>

Options:
  -o, --output <DIR>
          Path to output folder location

  -h, --help
          Print help
Converter

Convert from one of the supported formats to DDSL. Don’t rely on this in your main process since the output is unstable.

The format to convert into DDSL

Usage: [OPTIONS] <COMMAND>

Commands:
  device-driver-v1  The v1 formats of device-driver (DSL, YAML, JSON & TOML)
  help              Print this message or the help of the given subcommand(s)

Options:
  -s, --source <FILE>
          Path to the input file

  -o, --output <FILE>
          Path to output location. Any existing file is overwritten. If not provided, the output is written to stdout

  -h, --help
          Print help

Tool - Rust proc-macro

To ease the compilation flow for Rust projects, a proc-macro is available. When the macros feature is activated on the rust runtime device-driver crate, the macro will be exported.

device_driver::compile!(
    options: "--rust-defmt-feature=defmt",
    manifest: "path/to/manifest.ddsl",
);

With the options field you can pass the options described above, with the exception that the rust command is already given. (It would not make sense to compile to something other than Rust in a proc-macro.) Use --help there to see all the specific details.

The generated code is then emitted by the proc-macro and so the driver will be in the place where the macro is called.

For better UX, it’s recommended to add the manifest file to the build.rs:

fn main() {
    println!("cargo:rebuild-if-changed=path/to/manifest.ddsl");
}

Important

Enabling the macro causes the crate to pull in the compiler as a dependency which increases compile times. It’s not huge, but it’s definitely present.

Tool - Playground

For the playground, go to https://device-driver.com/playground.

The playground supports all targets and there’s a text field where the options can be specified. Using --help there works and will cause the help text to be printed to the bottom diagnistics panel.