bindgen::ParseCallbacks: support tracking env variable usage for cargo

bindgen currently has a `bindgen/build.rs` which attempts to have cargo
rebuild bindgen when TARGET specific env variables change, specifically
`BINDGEN_EXTRA_CLANG_ARGS_<target>`. Unfortunately, this doesn't have
the desired effect in most cases.

Specifically, when a crate `A` has `bindgen` in `build-dependencies`,
and we're cross compiling `A` for target `T` on a host `H`, `bindgen`'s
`build.rs` will observe `TARGET` set to `H` (the host target name)
instead of `T` (because `bindgen` itself is being built for `H` and not
`T`). Then, within the build script of crate `A`, one would use
`bindgen` to generate bindings, and now `TARGET` is set to `T`, so
different env variables are used.

Allow crates using `bindgen` in build scripts to correctly handle env
variable changes by adding `ParseCallbacks::read_env_var()` to track
env var reads and adding a basic implementation to `CargoCallbacks` to
emit `cargo:rerun-if-env-changed` lines.

Author: codyps

bindgen/callbacks.rs

@@ -102,6 +102,10 @@ pub trait ParseCallbacks: fmt::Debug {
     /// This will be called on every file inclusion, with the full path of the included file.
     fn include_file(&self, _filename: &str) {}
 
+    /// This will be called every time an environment variable is read (whether or not it has any
+    /// content), with the name of the env variable.
+    fn read_env_var(&self, _key: &str) {}
+
     /// This will be called to determine whether a particular blocklisted type
     /// implements a trait or not. This will be used to implement traits on
     /// other types containing the blocklisted type.

bindgen/lib.rs

@@ -78,6 +78,7 @@ pub use crate::regex_set::RegexSet;
 
 use std::borrow::Cow;
 use std::env;
+use std::ffi::OsStr;
 use std::fs::{File, OpenOptions};
 use std::io::{self, Write};
 use std::path::{Path, PathBuf};
@@ -95,10 +96,10 @@ pub const DEFAULT_ANON_FIELDS_PREFIX: &str = "__bindgen_anon_";
 const DEFAULT_NON_EXTERN_FNS_SUFFIX: &str = "__extern";
 
 fn file_is_cpp(name_file: &str) -> bool {
-    name_file.ends_with(".hpp") ||
-        name_file.ends_with(".hxx") ||
-        name_file.ends_with(".hh") ||
-        name_file.ends_with(".h++")
+    name_file.ends_with(".hpp")
+        || name_file.ends_with(".hxx")
+        || name_file.ends_with(".hh")
+        || name_file.ends_with(".h++")
 }
 
 fn args_are_cpp(clang_args: &[String]) -> bool {
@@ -276,13 +277,18 @@ pub fn builder() -> Builder {
     Default::default()
 }
 
-fn get_extra_clang_args() -> Vec<String> {
+fn get_extra_clang_args(
+    parse_callbacks: &[Rc<dyn callbacks::ParseCallbacks>],
+) -> Vec<String> {
     // Add any extra arguments from the environment to the clang command line.
-    let extra_clang_args =
-        match get_target_dependent_env_var("BINDGEN_EXTRA_CLANG_ARGS") {
-            None => return vec![],
-            Some(s) => s,
-        };
+    let extra_clang_args = match get_target_dependent_env_var(
+        parse_callbacks,
+        "BINDGEN_EXTRA_CLANG_ARGS",
+    ) {
+        None => return vec![],
+        Some(s) => s,
+    };
+
     // Try to parse it with shell quoting. If we fail, make it one single big argument.
     if let Some(strings) = shlex::split(&extra_clang_args) {
         return strings;
@@ -421,8 +427,8 @@ impl Builder {
         // FIXME(emilio): This is a bit hacky, maybe we should stop re-using the
         // RustFeatures to store the "disable_untagged_union" call, and make it
         // a different flag that we check elsewhere / in generate().
-        if !rust_features.untagged_union &&
-            RustFeatures::from(*rust_target).untagged_union
+        if !rust_features.untagged_union
+            && RustFeatures::from(*rust_target).untagged_union
         {
             output_vector.push("--disable-untagged-union".into());
         }
@@ -1731,7 +1737,9 @@ impl Builder {
     /// Generate the Rust bindings using the options built up thus far.
     pub fn generate(mut self) -> Result<Bindings, BindgenError> {
         // Add any extra arguments from the environment to the clang command line.
-        self.options.clang_args.extend(get_extra_clang_args());
+        self.options
+            .clang_args
+            .extend(get_extra_clang_args(&self.options.parse_callbacks));
 
         // Transform input headers to arguments on the clang command line.
         self.options.clang_args.extend(
@@ -1814,7 +1822,7 @@ impl Builder {
             cmd.arg(a);
         }
 
-        for a in get_extra_clang_args() {
+        for a in get_extra_clang_args(&self.options.parse_callbacks) {
             cmd.arg(a);
         }
 
@@ -2646,8 +2654,8 @@ fn rust_to_clang_target(rust_target: &str) -> String {
             rust_target.strip_suffix("-espidf").unwrap().to_owned();
         clang_target.push_str("-elf");
         if clang_target.starts_with("riscv32imc-") {
-            clang_target = "riscv32-".to_owned() +
-                clang_target.strip_prefix("riscv32imc-").unwrap();
+            clang_target = "riscv32-".to_owned()
+                + clang_target.strip_prefix("riscv32imc-").unwrap();
         }
         return clang_target;
     }
@@ -2742,8 +2750,8 @@ impl Bindings {
                             return false;
                         }
 
-                        if arg.starts_with("-I") ||
-                            arg.starts_with("--include-directory=")
+                        if arg.starts_with("-I")
+                            || arg.starts_with("--include-directory=")
                         {
                             return false;
                         }
@@ -2770,8 +2778,8 @@ impl Bindings {
             debug!("Found clang: {:?}", clang);
 
             // Whether we are working with C or C++ inputs.
-            let is_cpp = args_are_cpp(&options.clang_args) ||
-                options.input_headers.iter().any(|h| file_is_cpp(h));
+            let is_cpp = args_are_cpp(&options.clang_args)
+                || options.input_headers.iter().any(|h| file_is_cpp(h));
 
             let search_paths = if is_cpp {
                 clang.cpp_search_paths
@@ -3140,22 +3148,38 @@ pub fn clang_version() -> ClangVersion {
     }
 }
 
+fn env_var<K: AsRef<str> + AsRef<OsStr>>(
+    parse_callbacks: &[Rc<dyn callbacks::ParseCallbacks>],
+    key: K,
+) -> Result<String, std::env::VarError> {
+    for callback in parse_callbacks {
+        callback.read_env_var(key.as_ref());
+    }
+    std::env::var(key)
+}
+
 /// Looks for the env var `var_${TARGET}`, and falls back to just `var` when it is not found.
-fn get_target_dependent_env_var(var: &str) -> Option<String> {
-    if let Ok(target) = env::var("TARGET") {
-        if let Ok(v) = env::var(format!("{}_{}", var, target)) {
+fn get_target_dependent_env_var(
+    parse_callbacks: &[Rc<dyn callbacks::ParseCallbacks>],
+    var: &str,
+) -> Option<String> {
+    if let Ok(target) = env_var(parse_callbacks, "TARGET") {
+        if let Ok(v) = env_var(parse_callbacks, format!("{}_{}", var, target)) {
             return Some(v);
         }
-        if let Ok(v) = env::var(format!("{}_{}", var, target.replace('-', "_")))
-        {
+        if let Ok(v) = env_var(
+            parse_callbacks,
+            format!("{}_{}", var, target.replace('-', "_")),
+        ) {
             return Some(v);
         }
     }
-    env::var(var).ok()
+
+    env_var(parse_callbacks, var).ok()
 }
 
 /// A ParseCallbacks implementation that will act on file includes by echoing a rerun-if-changed
-/// line
+/// line and on env variable usage by echoing a rerun-if-env-changed line
 ///
 /// When running inside a `build.rs` script, this can be used to make cargo invalidate the
 /// generated bindings whenever any of the files included from the header change:
@@ -3173,6 +3197,10 @@ impl callbacks::ParseCallbacks for CargoCallbacks {
     fn include_file(&self, filename: &str) {
         println!("cargo:rerun-if-changed={}", filename);
     }
+
+    fn read_env_var(&self, key: &str) {
+        println!("cargo:rerun-if-env-changed={}", key);
+    }
 }
 
 /// Test command_line_flag function.