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).

book/src/whitelisting.md

@@ -120,9 +120,9 @@ impl<'a> ImplDebug<'a> for Item {
     ) -> Option<(String, Vec<proc_macro2::TokenStream>)> {
         let name_ident = ctx.rust_ident(name);
 
-        // We don't know if blacklisted items `impl Debug` or not, so we can't
+        // We don't know if blocklisted items `impl Debug` or not, so we can't
         // add them to the format string we're building up.
-        if !ctx.whitelisted_items().contains(&self.id()) {
+        if !ctx.allowlisted_items().contains(&self.id()) {
             return None;
         }
 

src/codegen/impl_debug.rs

@@ -443,7 +443,7 @@ impl CodeGenerator for Item {
             return;
         }
 
-        if self.is_blacklisted(ctx) || result.seen(self.id()) {
+        if self.is_blocklisted(ctx) || result.seen(self.id()) {
             debug!(
                 "<Item as CodeGenerator>::codegen: Ignoring hidden or seen: \
                  self = {:?}",
@@ -457,7 +457,7 @@ impl CodeGenerator for Item {
             // TODO(emilio, #453): Figure out what to do when this happens
             // legitimately, we could track the opaque stuff and disable the
             // assertion there I guess.
-            warn!("Found non-whitelisted item in code generation: {:?}", self);
+            warn!("Found non-allowlisted item in code generation: {:?}", self);
         }
 
         result.set_seen(self.id());
@@ -725,7 +725,7 @@ impl CodeGenerator for Type {
                 // These items don't need code generation, they only need to be
                 // converted to rust types in fields, arguments, and such.
                 // NOTE(emilio): If you add to this list, make sure to also add
-                // it to BindgenContext::compute_whitelisted_and_codegen_items.
+                // it to BindgenContext::compute_allowlisted_and_codegen_items.
                 return;
             }
             TypeKind::TemplateInstantiation(ref inst) => {
@@ -2261,8 +2261,8 @@ impl MethodCodegen for Method {
 
         // First of all, output the actual function.
         let function_item = ctx.resolve_item(self.signature());
-        if function_item.is_blacklisted(ctx) {
-            // We shouldn't emit a method declaration if the function is blacklisted
+        if function_item.is_blocklisted(ctx) {
+            // We shouldn't emit a method declaration if the function is blocklisted
             return;
         }
         function_item.codegen(ctx, result, &());

src/codegen/mod.rs

@@ -138,9 +138,9 @@ impl<'ctx> CannotDerive<'ctx> {
     }
 
     fn constrain_type(&mut self, item: &Item, ty: &Type) -> CanDerive {
-        if !self.ctx.whitelisted_items().contains(&item.id()) {
+        if !self.ctx.allowlisted_items().contains(&item.id()) {
             trace!(
-                "    cannot derive {} for blacklisted type",
+                "    cannot derive {} for blocklisted type",
                 self.derive_trait
             );
             return CanDerive::No;
@@ -640,10 +640,10 @@ impl<'ctx> MonotoneFramework for CannotDerive<'ctx> {
     }
 
     fn initial_worklist(&self) -> Vec<ItemId> {
-        // The transitive closure of all whitelisted items, including explicitly
-        // blacklisted items.
+        // The transitive closure of all allowlisted items, including explicitly
+        // blocklisted items.
         self.ctx
-            .whitelisted_items()
+            .allowlisted_items()
             .iter()
             .cloned()
             .flat_map(|i| {

src/ir/analysis/derive.rs

@@ -83,7 +83,7 @@ impl<'ctx> MonotoneFramework for HasDestructorAnalysis<'ctx> {
     }
 
     fn initial_worklist(&self) -> Vec<ItemId> {
-        self.ctx.whitelisted_items().iter().cloned().collect()
+        self.ctx.allowlisted_items().iter().cloned().collect()
     }
 
     fn constrain(&mut self, id: ItemId) -> ConstrainResult {

src/ir/analysis/has_destructor.rs

@@ -94,7 +94,7 @@ impl<'ctx> MonotoneFramework for HasFloat<'ctx> {
     }
 
     fn initial_worklist(&self) -> Vec<ItemId> {
-        self.ctx.whitelisted_items().iter().cloned().collect()
+        self.ctx.allowlisted_items().iter().cloned().collect()
     }
 
     fn constrain(&mut self, id: ItemId) -> ConstrainResult {

src/ir/analysis/has_float.rs

@@ -100,7 +100,7 @@ impl<'ctx> MonotoneFramework for HasTypeParameterInArray<'ctx> {
     }
 
     fn initial_worklist(&self) -> Vec<ItemId> {
-        self.ctx.whitelisted_items().iter().cloned().collect()
+        self.ctx.allowlisted_items().iter().cloned().collect()
     }
 
     fn constrain(&mut self, id: ItemId) -> ConstrainResult {

src/ir/analysis/has_type_param_in_array.rs

@@ -147,7 +147,7 @@ impl<'ctx> MonotoneFramework for HasVtableAnalysis<'ctx> {
     }
 
     fn initial_worklist(&self) -> Vec<ItemId> {
-        self.ctx.whitelisted_items().iter().cloned().collect()
+        self.ctx.allowlisted_items().iter().cloned().collect()
     }
 
     fn constrain(&mut self, id: ItemId) -> ConstrainResult {

src/ir/analysis/has_vtable.rs

@@ -183,7 +183,7 @@ where
 {
     let mut dependencies = HashMap::default();
 
-    for &item in ctx.whitelisted_items() {
+    for &item in ctx.allowlisted_items() {
         dependencies.entry(item).or_insert(vec![]);
 
         {
@@ -192,7 +192,7 @@ where
             item.trace(
                 ctx,
                 &mut |sub_item: ItemId, edge_kind| {
-                    if ctx.whitelisted_items().contains(&sub_item) &&
+                    if ctx.allowlisted_items().contains(&sub_item) &&
                         consider_edge(edge_kind)
                     {
                         dependencies

src/ir/analysis/mod.rs

@@ -194,7 +194,7 @@ impl<'ctx> MonotoneFramework for SizednessAnalysis<'ctx> {
 
     fn initial_worklist(&self) -> Vec<TypeId> {
         self.ctx
-            .whitelisted_items()
+            .allowlisted_items()
             .iter()
             .cloned()
             .filter_map(|id| id.as_type_id(self.ctx))