feat: move debug logging behind a debug flag that is disabled by default

src/command_helpers.rs

@@ -9,7 +9,10 @@ use std::{
     io::{self, Read, Write},
     path::Path,
     process::{Child, ChildStderr, Command, Stdio},
-    sync::Arc,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
 };
 
 use crate::{Error, ErrorKind, Object};
@@ -18,13 +21,17 @@ use crate::{Error, ErrorKind, Object};
 pub(crate) struct CargoOutput {
     pub(crate) metadata: bool,
     pub(crate) warnings: bool,
+    pub(crate) debug: bool,
+    checked_dbg_var: Arc<AtomicBool>,
 }
 
 impl CargoOutput {
-    pub(crate) const fn new() -> Self {
+    pub(crate) fn new() -> Self {
         Self {
             metadata: true,
             warnings: true,
+            debug: std::env::var_os("CC_ENABLE_DEBUG_OUTPUT").is_some(),
+            checked_dbg_var: Arc::new(AtomicBool::new(false)),
         }
     }
 
@@ -40,6 +47,16 @@ impl CargoOutput {
         }
     }
 
+    pub(crate) fn print_debug(&self, arg: &dyn Display) {
+        if self.metadata && !self.checked_dbg_var.load(Ordering::Relaxed) {
+            self.checked_dbg_var.store(true, Ordering::Relaxed);
+            println!("cargo:rerun-if-env-changed=CC_ENABLE_DEBUG_OUTPUT");
+        }
+        if self.debug {
+            println!("{}", arg);
+        }
+    }
+
     fn stdio_for_warnings(&self) -> Stdio {
         if self.warnings {
             Stdio::piped()
@@ -217,7 +234,7 @@ fn wait_on_child(
         }
     };
 
-    cargo_output.print_warning(&status);
+    cargo_output.print_debug(&status);
 
     if status.success() {
         Ok(())
@@ -326,7 +343,7 @@ pub(crate) fn spawn(
         }
     }
 
-    cargo_output.print_warning(&format_args!("running: {:?}", cmd));
+    cargo_output.print_debug(&format_args!("running: {:?}", cmd));
 
     let cmd = ResetStderr(cmd);
     let child = cmd.0.stderr(cargo_output.stdio_for_warnings()).spawn();

src/lib.rs

@@ -84,6 +84,9 @@
 //! some cross compiling scenarios. Setting this variable
 //! will disable the generation of default compiler
 //! flags.
+//! * `CC_ENABLE_DEBUG_OUTPUT` - if set, compiler command invocations and exit codes will
+//! be logged to stdout. This is useful for debugging build script issues, but can be
+//! overly verbose for normal use.
 //! * `CXX...` - see [C++ Support](#c-support).
 //!
 //! Furthermore, projects using this crate may specify custom environment variables
@@ -1119,6 +1122,16 @@ impl Build {
         self
     }
 
+    /// Define whether debug information should be emitted for cargo. Defaults to whether
+    /// or not the environment variable `CC_ENABLE_DEBUG_OUTPUT` is set.
+    ///
+    /// If enabled, the compiler will emit debug information when generating object files,
+    /// such as the command invoked and the exit status.
+    pub fn cargo_debug(&mut self, cargo_debug: bool) -> &mut Build {
+        self.cargo_output.debug = cargo_debug;
+        self
+    }
+
     /// Adds a native library modifier that will be added to the
     /// `rustc-link-lib=static:MODIFIERS=LIBRARY_NAME` metadata line
     /// emitted for cargo if `cargo_metadata` is enabled.