From 02111c87ae6ec2496cb29e89cb0307198e1e8cab Mon Sep 17 00:00:00 2001 From: Miikka Salminen Date: Wed, 20 Aug 2025 12:34:17 +0300 Subject: [PATCH] Small fixes and clarifications to user guide Some letter casing, typing, formatting, and grammar errors are fixed. Links added to docs.rs in some text referring to documentation there, as well as to other external resources. For inclusivity, the tutorial's sanity test is renamed to a smoke test. --- book/src/SUMMARY.md | 12 ++++++------ book/src/command-line-usage.md | 2 +- book/src/faq.md | 18 +++++++++--------- book/src/must-use-types.md | 10 ++++++---- book/src/nocopy.md | 5 ++++- book/src/nodebug.md | 4 +++- book/src/nodefault.md | 10 +++++++--- book/src/objc.md | 28 ++++++++++++++-------------- book/src/tutorial-5.md | 6 +++--- book/src/using-bitfields.md | 6 ++++-- 10 files changed, 57 insertions(+), 44 deletions(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index daaed04081..ac57aaad64 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -8,9 +8,9 @@ - [Create a `wrapper.h` Header](./tutorial-2.md) - [Create a `build.rs` File](./tutorial-3.md) - [Include the Generated Bindings in `src/lib.rs`](./tutorial-4.md) - - [Write a Sanity Test](./tutorial-5.md) + - [Write a Smoke Test](./tutorial-5.md) - [Publish Your Crate!](./tutorial-6.md) - - [Bindings for non-system libraries](./non-system-libraries.md) + - [Bindings for Non-System Libraries](./non-system-libraries.md) - [Command Line Usage](./command-line-usage.md) - [Customizing the Generated Bindings](./customizing-generated-bindings.md) - [Allowlisting](./allowlisting.md) @@ -20,11 +20,11 @@ - [Preventing the Derivation of `Copy` and `Clone`](./nocopy.md) - [Preventing the Derivation of `Debug`](./nodebug.md) - [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) + - [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) +- [Generating Bindings to Objective-C](./objc.md) - [Using Unions](./using-unions.md) - [Using Bitfields](./using-bitfields.md) - [Using Flexible Array Members](./using-fam.md) diff --git a/book/src/command-line-usage.md b/book/src/command-line-usage.md index b3356d70c7..051a63efad 100644 --- a/book/src/command-line-usage.md +++ b/book/src/command-line-usage.md @@ -13,7 +13,7 @@ directory to your `$PATH` to use `bindgen`. output file path for the generated bindings. If the output file path is not supplied, the bindings are printed to `stdout`. -If we wanted to generated Rust FFI bindings from a C header named `input.h` and +If we wanted to generate Rust FFI bindings from a C header named `input.h` and put them in the `bindings.rs` file, we would invoke `bindgen` like this: ```bash diff --git a/book/src/faq.md b/book/src/faq.md index bbaaab6368..59699ac757 100644 --- a/book/src/faq.md +++ b/book/src/faq.md @@ -47,18 +47,18 @@ creates linking errors. However, if you are compiling the C/C++ yourself (rather than using a system shared library, for example), then you can pass `-fkeep-inline-functions` or `-fno-inline-functions` to `gcc` or `clang`, and invoke `bindgen` with either -the `bindgen::Builder::generate_inline_functions` method or the -`--generate-inline-functions` flag. +the [`bindgen::Builder::generate_inline_functions`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.generate_inline_functions) +method or the `--generate-inline-functions` flag. Note that these functions and methods are usually marked inline for a reason: they tend to be hot. The above workaround makes them an out-of-line call, which might not provide acceptable performance. As an alternative, you can invoke `bindgen` with either the -`bindgen::Builder::wrap_static_fns` method or the `--wrap-static-fns` flag. -Which generates a C source file that can be compiled against the input headers -to produce Rust headers for `static` and `static inline` functions. See [How to -handle `static inline` functions](https://github.com/rust-lang/rust-bindgen/discussions/2405) +[`bindgen::Builder::wrap_static_fns`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.wrap_static_fns) +method or the `--wrap-static-fns` flag. That generates a C source file that can +be compiled against the input headers to produce Rust bindings for `static` and +`static inline` functions. See [How to handle `static inline` functions](https://github.com/rust-lang/rust-bindgen/discussions/2405) for further information. ### Does `bindgen` support the C++ Standard Template Library (STL)? @@ -81,8 +81,8 @@ possible that bindgen will generate padding fields named `__bindgen_padding_N`. As these fields might be present when compiling for one architecture but not for an other, you should not initialize these fields manually when initializing the struct. Instead, use the `Default` trait. You can either enable this when -constructing the `Builder` using the `derive_default` method, or you can -implement this per struct using: +constructing the `Builder` using the [`derive_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_default) +method, or you can implement this per struct using: ```rust,ignore impl Default for SRC_DATA { @@ -107,7 +107,7 @@ be automatically initialized by `..Default::default()`. ### How to generate bindings for a custom target? -To generate bindings for a custom target you only need to pass the `--target` +To generate bindings for a custom target you only need to pass the [`--target`](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-target) argument to `libclang`. For example, if you want to generate bindings for the `armv7a-none-eabi` target using the command line, you need to invoke `bindgen` like so: diff --git a/book/src/must-use-types.md b/book/src/must-use-types.md index 490339c9d2..1792e5a485 100644 --- a/book/src/must-use-types.md +++ b/book/src/must-use-types.md @@ -1,11 +1,13 @@ -# Annotating types with `#[must-use]` +# Annotating Types with `#[must-use]` `bindgen` can be instructed to annotate certain types with [`#[must_use]`](https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute). -Some libraries have a common error type, returned by lots of their functions, -which needs to be checked after every call. In these cases it's useful to add `#[must_use]` to this type, so the Rust -compiler emits a warning when the check is missing. +Some libraries have a common error type, returned by many of their functions, +which needs to be checked after every call. In these cases it's useful to add +`#[must_use]` to this type, so the Rust compiler emits a warning when the check +is missing. + ### Library * [`bindgen::Builder::must_use_type`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.must_use_type) diff --git a/book/src/nocopy.md b/book/src/nocopy.md index 8a637a59c3..e0d17ed0cb 100644 --- a/book/src/nocopy.md +++ b/book/src/nocopy.md @@ -4,14 +4,17 @@ basis. Sometimes, it might not understand that although adding `#[derive(Copy, Clone)]` to a translated type definition will compile, it still shouldn't do that for reasons it can't know. In these cases, the `nocopy` annotation can be -used to prevent bindgen to autoderive the `Copy` and `Clone` traits for a type. +used to prevent bindgen from automatically deriving the `Copy` and `Clone` +traits for a type. ### Library +* [`bindgen::Builder::derive_copy`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_copy) * [`bindgen::Builder::no_copy`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.no_copy) ### Command Line +* `--no-derive-copy` * `--no-copy ` ### Annotations diff --git a/book/src/nodebug.md b/book/src/nodebug.md index c412a7dfca..4fa820134b 100644 --- a/book/src/nodebug.md +++ b/book/src/nodebug.md @@ -3,14 +3,16 @@ `bindgen` will attempt to derive the `Debug` traits on a best-effort basis. Sometimes, it might not understand that although adding `#[derive(Debug)]` to a translated type definition will compile, it still shouldn't do that for reasons it can't know. In these cases, the `nodebug` annotation can be -used to prevent bindgen to autoderive the `Debug` traits for a type. +used to prevent bindgen from automatically deriving the `Debug` trait for a type. ### Library +* [`bindgen::Builder::derive_debug`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_debug) * [`bindgen::Builder::no_debug`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.no_debug) ### Command Line +* `--no-derive-debug` * `--no-debug ` ### Annotations diff --git a/book/src/nodefault.md b/book/src/nodefault.md index 37896f6c5c..9561d7c17f 100644 --- a/book/src/nodefault.md +++ b/book/src/nodefault.md @@ -1,16 +1,20 @@ # Preventing the Derivation of `Default` +By default, `Default` is not derived. + `bindgen` will attempt to derive/impl the `Default` traits on a best-effort basis. -Sometimes, we need customize the implement of `Default` for certain types, -In these cases, the `nodefault` annotation can be used to prevent bindgen -to autoderive the `Default` traits for a type. +Sometimes, we need customize the implementation of `Default` for certain types. +In these cases, the `nodefault` annotation can be used to prevent bindgen from +automatically deriving the `Default` trait for a type. ### Library +* [`bindgen::Builder::derive_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_default) * [`bindgen::Builder::no_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.no_default) ### Command Line +* `--with-derive-default` * `--no-default ` ### Annotations diff --git a/book/src/objc.md b/book/src/objc.md index ed6f2cb881..3845ed5a2e 100644 --- a/book/src/objc.md +++ b/book/src/objc.md @@ -1,10 +1,10 @@ # Generating Bindings to Objective-C -`bindgen` does not (yet) have full objective-c support but it can generate bindings -for a lot of the apple frameworks without too much blocklisting. +`bindgen` does not (yet) have full Objective-C support, but it can generate +bindings for many of the Apple frameworks without too much blocklisting. -In order to generate bindings, you will need `-x objective-c` as the clang -args. If you'd like to use [block](https://crates.io/crates/block) you will need +In order to generate bindings, you will need `-x objective-c` as a clang arg. If +you'd like to use [block](https://crates.io/crates/block) you will need `-fblocks` as a clang arg as well. Depending on your setup, you may need `--generate-block` to generate the block @@ -12,14 +12,14 @@ function aliases and `--block-extern-crate` to insert a `extern crate block` at the beginning of the generated bindings. The same logic applies to the `--objc-extern-crate` parameter. -The objective-c classes will be represented as a `struct Foo(id)` and a trait -`IFoo` where `Foo` is the objective-c class and `id` is an alias for `*mut -objc::runtime::Object` (the pointer to the objective-c instance). The trait +The Objective-C classes will be represented as a `struct Foo(id)` and a trait +`IFoo` where `Foo` is the Objective-C class and `id` is an alias for `*mut +objc::runtime::Object` (the pointer to the Objective-C instance). The trait `IFoo` is needed to allow for the generated inheritance. -Functions that use or return objective-c pointers of instance `Foo` will return +Functions that use or return Objective-C pointers of instance `Foo` will return `Foo`. The reason this works is because `Foo` represented as `transparent`. -This will be helpful for a lot of objective-c frameworks however there are some +This will be helpful for many Objective-C frameworks. However, there are some cases where functions return `instancetype` which is a type alias for `id` so an occasional `foo.0` may be required. An example of this would in the UIKit framework should you want to add a `UILabel` to a @@ -42,7 +42,7 @@ stands for interface. * Protocols which match to rust traits with prefixes of `P` which stands for Protocol. * Classes will generate `struct Foo(id)` where `Foo` is the class -name and `id` is a pointer to the objective-c Object. +name and `id` is a pointer to the Objective-C Object. * Blocks ## Useful Notes @@ -52,16 +52,16 @@ name and `id` is a pointer to the objective-c Object. [here](https://github.com/rust-lang/rust-bindgen/issues/1211#issuecomment-569804287). * The generated bindings will almost certainly have some conflicts so you will have to blocklist a few things. There are a few cases of the parameters being -poorly named in the objective-c headers. But if you're using anything with +poorly named in the Objective-C headers. But if you're using anything with Core Foundation, you'll find that `time.h` as has a variable called timezone that conflicts with some of the things in `NSCalendar.h`. -* Some small subset of the function headers in the apple frameworks go against -apple's guidelines for parameter names and duplicate the names in the header +* Some small subset of the function headers in the Apple frameworks go against +Apple's guidelines for parameter names and duplicate the names in the header which won't compile as mentioned [here](https://github.com/rust-lang/rust-bindgen/issues/1705). * instancetype return methods does not return `Self` for you given class, it returns a `mut * objc::runtime::Objc` which is aliased as `id`. This is because -objective-c's inheritance doesn't perfectly match that of rusts. +Objective-C's inheritance doesn't perfectly match that of Rust's. * Depending on what you're trying `bindgen` against, you may end up including all of Core Foundation and any other frameworks. This will result in a very long compile time. diff --git a/book/src/tutorial-5.md b/book/src/tutorial-5.md index 8a71dac355..8e308f82d6 100644 --- a/book/src/tutorial-5.md +++ b/book/src/tutorial-5.md @@ -1,11 +1,11 @@ -# Write a Sanity Test +# Write a Smoke Test -Finally, to tie everything together, let's write a sanity test that round trips +Finally, to tie everything together, let's write a smoke test that round trips some text through compression and decompression, and then asserts that it came back out the same as it went in. This is a little wordy using the raw FFI bindings, but hopefully we wouldn't usually ask people to do this, we'd provide a nice Rust-y API on top of the raw FFI bindings for them. However, since this -is for testing the bindings directly, our sanity test will use the bindings +is for testing the bindings directly, our smoke test will use the bindings directly. The test data I'm round tripping are some Futurama quotes I got off the internet diff --git a/book/src/using-bitfields.md b/book/src/using-bitfields.md index 8929f73705..6aaab2203d 100644 --- a/book/src/using-bitfields.md +++ b/book/src/using-bitfields.md @@ -15,7 +15,7 @@ pre-existing definition for the bitfield unit type. ## Bitfield examples -For this discussion, we will use the following C type definitions and functions. +For this discussion, we will use the following C type definitions and functions: ```c typedef struct { unsigned int a: 1; @@ -76,7 +76,9 @@ StructWithBitfields: a:1, b:1, c:0 To create a new bitfield in Rust, use the bitfield allocation unit constructor. -Note: This requires the Builder's derive_default to be set to true, otherwise the necessary Default functions won't be generated. +Note: This requires the `Builder`'s [`derive_default`](https://docs.rs/bindgen/latest/bindgen/struct.Builder.html#method.derive_default) +to be set to `true`. Otherwise the necessary `Default` functions won't be +generated. ```rust,ignore let bfield = StructWithBitfields{