diff options
author | Christian Poveda Ruiz <31802960+pvdrz@users.noreply.github.com> | 2022-12-15 16:16:38 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-12-15 16:16:38 -0500 |
commit | 3f1b9ae995d344e936a8fe0d40a83f61942a7ba2 (patch) | |
tree | 18182a55700ba6d3600978baeda89a6f138e8b5e | |
parent | 87b535c3c1089a09632e4d3a1541bd53bb40f55e (diff) |
Document how to format code (#2375)
* Document how to format code
* Fix typo
* Fix formatting
* Ignore code snippet
-rw-r--r-- | book/src/SUMMARY.md | 1 | ||||
-rw-r--r-- | book/src/code-formatting.md | 69 | ||||
-rw-r--r-- | book/src/faq.md | 16 |
3 files changed, 86 insertions, 0 deletions
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 551ea0d5..dbdf3f70 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -22,6 +22,7 @@ - [Preventing the Derivation of `Default`](./nodefault.md) - [Annotating types with `#[must-use]`](./must-use-types.md) - [Field visibility](./visibility.md) + - [Code formatting](./code-formatting.md) - [Generating Bindings to C++](./cpp.md) - [Generating Bindings to Objective-c](./objc.md) - [Using Unions](./using-unions.md) diff --git a/book/src/code-formatting.md b/book/src/code-formatting.md new file mode 100644 index 00000000..9039984a --- /dev/null +++ b/book/src/code-formatting.md @@ -0,0 +1,69 @@ +# 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 the +[`Builder::rustfmt_configuration_file`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.rustfmt_configuration_file) +method. + +## Using a nightly release of `rustfmt` + +If the `rustfmt` command does not correspond to a nightly release of `rustfmt` +but 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`: + +```bash +$ rustup run nightly bindgen [ARGS] +``` + +### When using `bindgen` as a library + +Take the output of the following command: +```bash +$ rustup which rustfmt --toolchain=nightly +``` +and pass it to +[`Builder::with_rustfmt`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.with_rustfmt): + +```rust,ignore +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. diff --git a/book/src/faq.md b/book/src/faq.md index 767cd6e2..fcb8255f 100644 --- a/book/src/faq.md +++ b/book/src/faq.md @@ -108,3 +108,19 @@ $ bindgen <input_headers> -- --target=armv7a-none-eabi ``` If you are using `bindgen` as a library, you should call `builder.clang_arg("--target=armv7a-none-eabi")` on your `builder`. + +### 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 to create a +`rustfmt.toml` file with the following contents: + +```toml +normalize_doc_attributes = true +``` + +Then, you have set up bindgen so it passes this file to `rustfmt`. Given that +the `normalize_doc_attributes` option is +[unstable](https://github.com/rust-lang/rustfmt/issues/3351), you also have to +set up bindgen to use a `nightly` release of `rustfmt`. Please check the [code +formatting](./code-formatting.md) section for further information. |