Rename whitelist -> allowlist

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

Author: hlopko

CHANGELOG.md

@@ -127,6 +127,24 @@
 
 ## 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][]
+
 ## Removed
 
 ## Fixed

book/src/SUMMARY.md

@@ -12,7 +12,7 @@
         - [Publish Your Crate!](./tutorial-6.md)
 - [Command Line Usage](./command-line-usage.md)
 - [Customizing the Generated Bindings](./customizing-generated-bindings.md)
-    - [Whitelisting](./whitelisting.md)
+    - [Allowlisting](./allowlisting.md)
     - [Blacklisting](./blacklisting.md)
     - [Treating a Type as an Opaque Blob of Bytes](./opaque.md)
     - [Replacing One Type with Another](./replacing-types.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/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/whitelisting.md

@@ -122,7 +122,7 @@ impl<'a> ImplDebug<'a> for Item {
 
         // We don't know if blacklisted 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

@@ -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) => {

src/codegen/mod.rs

@@ -138,7 +138,7 @@ 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",
                 self.derive_trait
@@ -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
+        // The transitive closure of all allowlisted items, including explicitly
         // blacklisted 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 {