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 {

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

src/ir/analysis/sizedness.rs

@@ -138,11 +138,11 @@ use crate::{HashMap, HashSet};
 /// template parameter is always used.
 ///
 /// The final wrinkle is handling of blacklisted types. Normally, we say that
-/// the set of whitelisted items is the transitive closure of items explicitly
-/// called out for whitelisting, *without* any items explicitly called out as
+/// the set of allowlisted items is the transitive closure of items explicitly
+/// called out for allowlisting, *without* any items explicitly called out as
 /// blacklisted. However, for the purposes of this analysis's correctness, we
 /// simplify and consider run the analysis on the full transitive closure of
-/// whitelisted items. We do, however, treat instantiations of blacklisted items
+/// allowlisted items. We do, however, treat instantiations of blacklisted items
 /// specially; see `constrain_instantiation_of_blacklisted_template` and its
 /// documentation for details.
 #[derive(Debug, Clone)]
@@ -155,10 +155,10 @@ pub struct UsedTemplateParameters<'ctx> {
 
     dependencies: HashMap<ItemId, Vec<ItemId>>,
 
-    // The set of whitelisted items, without any blacklisted items reachable
-    // from the whitelisted items which would otherwise be considered
-    // whitelisted as well.
-    whitelisted_items: HashSet<ItemId>,
+    // The set of allowlisted items, without any blacklisted items reachable
+    // from the allowlisted items which would otherwise be considered
+    // allowlisted as well.
+    allowlisted_items: HashSet<ItemId>,
 }
 
 impl<'ctx> UsedTemplateParameters<'ctx> {
@@ -379,10 +379,10 @@ impl<'ctx> MonotoneFramework for UsedTemplateParameters<'ctx> {
     fn new(ctx: &'ctx BindgenContext) -> UsedTemplateParameters<'ctx> {
         let mut used = HashMap::default();
         let mut dependencies = HashMap::default();
-        let whitelisted_items: HashSet<_> =
-            ctx.whitelisted_items().iter().cloned().collect();
+        let allowlisted_items: HashSet<_> =
+            ctx.allowlisted_items().iter().cloned().collect();
 
-        let whitelisted_and_blacklisted_items: ItemSet = whitelisted_items
+        let allowlisted_and_blacklisted_items: ItemSet = allowlisted_items
             .iter()
             .cloned()
             .flat_map(|i| {
@@ -398,7 +398,7 @@ impl<'ctx> MonotoneFramework for UsedTemplateParameters<'ctx> {
             })
             .collect();
 
-        for item in whitelisted_and_blacklisted_items {
+        for item in allowlisted_and_blacklisted_items {
             dependencies.entry(item).or_insert(vec![]);
             used.entry(item).or_insert(Some(ItemSet::new()));
 
@@ -457,17 +457,17 @@ impl<'ctx> MonotoneFramework for UsedTemplateParameters<'ctx> {
         }
 
         if cfg!(feature = "testing_only_extra_assertions") {
-            // Invariant: The `used` map has an entry for every whitelisted
+            // Invariant: The `used` map has an entry for every allowlisted
             // item, as well as all explicitly blacklisted items that are
-            // reachable from whitelisted items.
+            // reachable from allowlisted items.
             //
             // Invariant: the `dependencies` map has an entry for every
-            // whitelisted item.
+            // allowlisted item.
             //
             // (This is so that every item we call `constrain` on is guaranteed
             // to have a set of template parameters, and we can allow
             // blacklisted templates to use all of their parameters).
-            for item in whitelisted_items.iter() {
+            for item in allowlisted_items.iter() {
                 extra_assert!(used.contains_key(item));
                 extra_assert!(dependencies.contains_key(item));
                 item.trace(
@@ -485,15 +485,15 @@ impl<'ctx> MonotoneFramework for UsedTemplateParameters<'ctx> {
             ctx: ctx,
             used: used,
             dependencies: dependencies,
-            whitelisted_items: whitelisted_items,
+            allowlisted_items: allowlisted_items,
         }
     }
 
     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| {
@@ -538,7 +538,7 @@ impl<'ctx> MonotoneFramework for UsedTemplateParameters<'ctx> {
             // template definition uses the corresponding template parameter.
             Some(&TypeKind::TemplateInstantiation(ref inst)) => {
                 if self
-                    .whitelisted_items
+                    .allowlisted_items
                     .contains(&inst.template_definition().into())
                 {
                     self.constrain_instantiation(