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{