Code formatting - The bindgen User Guide (original) (raw)

The bindgen User Guide

Code Formatting

bindgen uses rustfmt to format the emitted bindings. This section describes how to adjust the rustfmt behavior when being used from bindgen.

Passing a rustfmt.toml configuration file

rustfmt should automatically use any rustfmt.toml file that is present in the directory from where bindgen will be run. If you want to use a configuration file that has a different name or that is in a different directory you can use the --rustfmt-configuration-file flag or theBuilder::rustfmt_configuration_filemethod.

Using a nightly release of rustfmt

If the rustfmt command does not correspond to a nightly release of rustfmtbut you have rustup available, you can use nightly by following these steps:

When using bindgen as a CLI application

Use rustup run to run bindgen:

$ rustup run nightly bindgen [ARGS]

When using bindgen as a library

Take the output of the following command:

$ rustup which rustfmt --toolchain=nightly

and pass it toBuilder::with_rustfmt:

use bindgen::Builder;
use std::process::Command;

fn main() {
    let output = Command::new("rustup")
        .args(["which", "rustfmt", "--toolchain", "nightly"])
        .output()
        .expect("Could not spawn `rustup` command");

    assert!(
        output.status.success(),
        "Unsuccessful status code when running `rustup`: {output:?}",
    );

    let rustfmt_path =
        String::from_utf8(output.stdout).expect("The `rustfmt` path is not valid `utf-8`");

    let bindings = Builder::default()
        .header("path/to/input.h")
        .with_rustfmt(rustfmt_path)
        .generate()
        .expect("Could not generate bindings");

    bindings
        .write_to_file("path/to/output.rs")
        .expect("Could not write bindings");
}

These two methods also apply to any other toolchain available in your system.

Using prettyplease

The prettyplease crate is a minimal formatter for generated code. To format bindings using prettypleaseyou have to invoke bindgen with either the --formatter=prettyplease flag or the bindgen::Builder::formatter(bindgen::Formatter::Prettyplease). One of its advantages is that prettyplease can be used in minimal environments where the Rust toolchain is not installed.

How can I normalize #[doc] attributes?

bindgen emits all the documentation using #[doc] attributes by default. If you want to use the more user-friendly /// syntax, you have two options:

Use rustfmt

rustfmt can be configured to normalize documentation. To do so, you have to create a rustfmt.toml file with the following contents:

normalize_doc_attributes = true

Then, you have set up bindgen so it passes this file to rustfmt. Given that the normalize_doc_attributes option isunstable, you also have to set up bindgen to use a nightly release of rustfmt.

Use prettyplease

prettyplease normalizes documentation without any additional configuration. Then you just have to tell bindgen to use prettyplease as the code formatter.