Rename whitelist -> allowlist and blacklist -> blocklist

For the commandline arguments I added undocumented aliases to old flags,
to stay backwards compatible.

Author: hlopko

CHANGELOG.md

@@ -127,6 +127,42 @@
 
 ## Deprecated
 
+* `bindgen::Builder::whitelist_type` is deprecated in favor of
+  `bindgen::Builder::allowlist_type`. [#1812][]
+
+* `bindgen::Builder::whitelist_function` is deprecated in favor of
+  `bindgen::Builder::allowlist_function`. [#1812][]
+
+* `bindgen::Builder::whitelist_var` is deprecated in favor of
+  `bindgen::Builder::allowlist_var`. [#1812][]
+
+* `--whitelist-type` is deprecated in favor of
+  `--allowlist-type`. [#1812][]
+
+* `--whitelist-function` is deprecated in favor of
+  `--allowlist-function`. [#1812][]
+
+* `--whitelist-var` is deprecated in favor of
+  `--allowlist-var`. [#1812][]
+
+* `bindgen::Builder::blacklist_type` is deprecated in favor of
+  `bindgen::Builder::blocklist_type`. [#1812][]
+
+* `bindgen::Builder::blacklist_function` is deprecated in favor of
+  `bindgen::Builder::blocklist_function`. [#1812][]
+
+* `bindgen::Builder::blacklist_item` is deprecated in favor of
+  `bindgen::Builder::blocklist_item`. [#1812][]
+
+* `--blacklist-type` is deprecated in favor of
+  `--blocklist-type`. [#1812][]
+
+* `--blacklist-function` is deprecated in favor of
+  `--blocklist-function`. [#1812][]
+
+* `--blacklist-item` is deprecated in favor of
+  `--blocklist-item`. [#1812][]
+
 ## Removed
 
 ## Fixed

bindgen-integration/build.rs

@@ -160,7 +160,7 @@ fn main() {
             seen_hellos: Mutex::new(0),
             seen_funcs: Mutex::new(0),
         }))
-        .blacklist_function("my_prefixed_function_to_remove")
+        .blocklist_function("my_prefixed_function_to_remove")
         .constified_enum("my_prefixed_enum_to_be_constified")
         .opaque_type("my_prefixed_templated_foo<my_prefixed_baz>")
         .generate()

book/src/SUMMARY.md

@@ -12,8 +12,8 @@
         - [Publish Your Crate!](./tutorial-6.md)
 - [Command Line Usage](./command-line-usage.md)
 - [Customizing the Generated Bindings](./customizing-generated-bindings.md)
-    - [Whitelisting](./whitelisting.md)
-    - [Blacklisting](./blacklisting.md)
+    - [Allowlisting](./allowlisting.md)
+    - [Blocklisting](./blocklisting.md)
     - [Treating a Type as an Opaque Blob of Bytes](./opaque.md)
     - [Replacing One Type with Another](./replacing-types.md)
     - [Preventing the Derivation of `Copy` and `Clone`](./nocopy.md)

book/src/allowlisting.md

@@ -0,0 +1,31 @@
+# Allowlisting
+
+Allowlisting allows us to be precise about which type, function, and global
+variable definitions `bindgen` generates bindings for. By default, if we don't
+specify any allowlisting rules, everything is considered allowlisted. This may
+not be desirable because of either
+
+* the generated bindings contain a lot of extra definitions we don't plan on using, or
+* the header file contains C++ features for which Rust does not have a
+  corresponding form (such as partial template specialization), and we would
+  like to avoid these definitions
+
+If we specify allowlisting rules, then `bindgen` will only generate bindings to
+types, functions, and global variables that match the allowlisting rules, or are
+transitively used by a definition that matches them.
+
+### Library
+
+* [`bindgen::Builder::allowlist_type`](https://docs.rs/bindgen/0.23.1/bindgen/struct.Builder.html#method.allowlist_type)
+* [`bindgen::Builder::allowlist_function`](https://docs.rs/bindgen/0.23.1/bindgen/struct.Builder.html#method.allowlist_function)
+* [`bindgen::Builder::allowlist_var`](https://docs.rs/bindgen/0.23.1/bindgen/struct.Builder.html#method.allowlist_var)
+
+### Command Line
+
+* `--allowlist-type <type>`
+* `--allowlist-function <function>`
+* `--allowlist-var <var>`
+
+### Annotations
+
+None.

book/src/blacklisting.md renamed to book/src/blocklisting.md

@@ -1,24 +1,25 @@
-# Blacklisting
+# Blocklisting
 
 If you need to provide your own custom translation of some type (for example,
 because you need to wrap one of its fields in an `UnsafeCell`), you can
-explicitly blacklist generation of its definition. Uses of the blacklisted type
+explicitly blocklist
+ generation of its definition. Uses of the blocklisted type
 will still appear in other types' definitions. (If you don't want the type to
 appear in the bindings at
 all, [make it opaque](./opaque.md) instead of
-blacklisting it.)
+blocklisting it.)
 
-Blacklisted types are pessimistically assumed not to be able to `derive` any
+Blocklisted types are pessimistically assumed not to be able to `derive` any
 traits, which can transitively affect other types' ability to `derive` traits or
 not.
 
 ### Library
 
-* [`bindgen::Builder::blacklist_type`](https://docs.rs/bindgen/0.31.3/bindgen/struct.Builder.html#method.blacklist_type)
+* [`bindgen::Builder::blocklist_type`](https://docs.rs/bindgen/0.31.3/bindgen/struct.Builder.html#method.blocklist_type)
 
 ### Command Line
 
-* `--blacklist-type <type>`
+* `--blocklist-type <type>`
 
 ### Annotations
 

book/src/cpp.md

@@ -11,11 +11,11 @@ it ends in `.hpp`. If it doesn't, adding `-x c++` clang args can be used to
 force C++ mode. You probably also want to use `-std=c++14` or similar clang args
 as well.
 
-You pretty much **must** use [whitelisting](./whitelisting.md) when working
+You pretty much **must** use [allowlisting](./allowlisting.md) when working
 with C++ to avoid pulling in all of the `std::.*` types, many of which `bindgen`
 cannot handle. Additionally, you may want to mark other types as
 [opaque](./opaque.md) that `bindgen` stumbles on. It is recommended to mark
-all of `std::.*` opaque, and to whitelist only precisely the functions and types
+all of `std::.*` opaque, and to allowlist only precisely the functions and types
 you intend to use.
 
 You should read up on the [FAQs](./faq.md) as well.

book/src/faq.md

@@ -4,13 +4,13 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 
-- [Why isn't `bindgen` generating methods for this whitelisted class?](#why-isnt-bindgen-generating-methods-for-this-whitelisted-class)
+- [Why isn't `bindgen` generating methods for this allowlisted class?](#why-isnt-bindgen-generating-methods-for-this-allowlisted-class)
 - [Why isn't `bindgen` generating bindings to inline functions?](#why-isnt-bindgen-generating-bindings-to-inline-functions)
 - [Does `bindgen` support the C++ Standard Template Library (STL)?](#does-bindgen-support-the-c-standard-template-library-stl)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-### Why isn't `bindgen` generating methods for this whitelisted class?
+### Why isn't `bindgen` generating methods for this allowlisted class?
 
 Are the methods `inline` methods, or defined inline in the class? For example:
 
@@ -62,7 +62,7 @@ STL. That ties our hands when it comes to linking: ["Why isn't `bindgen` generat
 As far as generating opaque blobs of bytes with the correct size and alignment,
 `bindgen` can do pretty well. This is typically enough to let you use types that
 transitively contain STL things. We generally recommend marking `std::.*` as
-opaque, and then whitelisting only the specific things you need from the library
+opaque, and then allowlisting only the specific things you need from the library
 you're binding to that is pulling in STL headers.
 
 ### How to deal with bindgen generated padding fields?

book/src/objc.md

@@ -1,7 +1,7 @@
 # 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 blacklisting.
+for a lot 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
@@ -49,7 +49,7 @@ name and `id` is a pointer to the objective-c Object.
 `--target=arm64-apple-ios` as mentioned
 [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 blacklist a few things. There are a few cases of the parameters being
+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
 Core Foundation, you'll find that `time.h` as has a variable called timezone that
 conflicts with some of the things in `NSCalendar.h`.

book/src/replacing-types.md

@@ -24,4 +24,4 @@ That way, after code generation, the bindings for the `nsTArray` type are
 the ones that would be generated for `nsTArray_Simple`.
 
 Replacing is only available as an annotation. To replace a C or C++ definition
-with a Rust definition, use [blacklisting](./blacklisting.md).
+with a Rust definition, use [blocklisting](./blocklisting.md).