Merge bitcoin/bitcoin#32074: contrib: Make deterministic-coverage error messages more readable

fa7a40d952 contrib: Print deterministic-coverage runs (MarcoFalke)
fa751639fb contrib: Make deterministic-coverage error messages more readable (MarcoFalke)

Pull request description:

  This is almost a "refactor" to tidy up the error messages. Apart from the messages, the behavior of the tools is identical.

  This was requested in https://github.com/bitcoin/bitcoin/pull/31901#discussion_r1969502508.

  Previously, the tool would abort the program early on some errors. Now, the tool propagates an `std::result::Result::Err` up to `main` via an early return. Getting rid of the aborts also allows to drop the `RUST_BACKTRACE` env setting.

ACKs for top commit:
  hodlinator:
    re-ACK fa7a40d952
  janb84:
    ACK [fa7a40d](fa7a40d952)

Tree-SHA512: 6c97861306e2fececa14b2d12deafb78995fc2bcf75e4e22773cb0ab4231de78834db9f1f89b30c49d77499433b1c16c1d90b97eb4069c81855bd2a7944b554f

contrib/devtools/README.md

@@ -8,7 +8,7 @@ deterministic-fuzz-coverage
 A tool to check for non-determinism in fuzz coverage. To get the help, run:
 
 ```
-RUST_BACKTRACE=1 cargo run --manifest-path ./contrib/devtools/deterministic-fuzz-coverage/Cargo.toml -- --help
+cargo run --manifest-path ./contrib/devtools/deterministic-fuzz-coverage/Cargo.toml -- --help
 ```
 
 To execute the tool, compilation has to be done with the build options:
@@ -22,7 +22,7 @@ repository must have been cloned. Finally, a fuzz target has to be picked
 before running the tool:
 
 ```
-RUST_BACKTRACE=1 cargo run --manifest-path ./contrib/devtools/deterministic-fuzz-coverage/Cargo.toml -- $PWD/build_dir $PWD/qa-assets/fuzz_corpora fuzz_target_name
+cargo run --manifest-path ./contrib/devtools/deterministic-fuzz-coverage/Cargo.toml -- $PWD/build_dir $PWD/qa-assets/fuzz_corpora fuzz_target_name
 ```
 
 deterministic-unittest-coverage
@@ -31,7 +31,7 @@ deterministic-unittest-coverage
 A tool to check for non-determinism in unit-test coverage. To get the help, run:
 
 ```
-RUST_BACKTRACE=1 cargo run --manifest-path ./contrib/devtools/deterministic-unittest-coverage/Cargo.toml -- --help
+cargo run --manifest-path ./contrib/devtools/deterministic-unittest-coverage/Cargo.toml -- --help
 ```
 
 To execute the tool, compilation has to be done with the build options:
@@ -43,7 +43,7 @@ To execute the tool, compilation has to be done with the build options:
 Both llvm-profdata and llvm-cov must be installed.
 
 ```
-RUST_BACKTRACE=1 cargo run --manifest-path ./contrib/devtools/deterministic-unittest-coverage/Cargo.toml -- $PWD/build_dir <boost unittest filter>
+cargo run --manifest-path ./contrib/devtools/deterministic-unittest-coverage/Cargo.toml -- $PWD/build_dir <boost unittest filter>
 ```
 
 clang-format-diff.py

contrib/devtools/deterministic-fuzz-coverage/src/main.rs

@@ -4,87 +4,89 @@
 
 use std::env;
 use std::fs::{read_dir, File};
-use std::path::Path;
+use std::path::{Path, PathBuf};
-use std::process::{exit, Command};
+use std::process::{Command, ExitCode};
 use std::str;
 
+/// A type for a complete and readable error message.
+type AppError = String;
+type AppResult = Result<(), AppError>;
+
 const LLVM_PROFDATA: &str = "llvm-profdata";
 const LLVM_COV: &str = "llvm-cov";
 const GIT: &str = "git";
 
-fn exit_help(err: &str) -> ! {
+fn exit_help(err: &str) -> AppError {
-    eprintln!("Error: {}", err);
+    format!(
-    eprintln!();
+        r#"
-    eprintln!("Usage: program ./build_dir ./qa-assets/fuzz_corpora fuzz_target_name");
+Error: {err}
-    eprintln!();
+
-    eprintln!("Refer to the devtools/README.md for more details.");
+Usage: program ./build_dir ./qa-assets/fuzz_corpora fuzz_target_name
-    exit(1)
+
+Refer to the devtools/README.md for more details."#
+    )
 }
 
-fn sanity_check(corpora_dir: &Path, fuzz_exe: &Path) {
+fn sanity_check(corpora_dir: &Path, fuzz_exe: &Path) -> AppResult {
     for tool in [LLVM_PROFDATA, LLVM_COV, GIT] {
         let output = Command::new(tool).arg("--help").output();
         match output {
             Ok(output) if output.status.success() => {}
-            _ => {
+            _ => Err(exit_help(&format!("The tool {} is not installed", tool)))?,
-                exit_help(&format!("The tool {} is not installed", tool));
-            }
         }
     }
     if !corpora_dir.is_dir() {
-        exit_help(&format!(
+        Err(exit_help(&format!(
             "Fuzz corpora path ({}) must be a directory",
             corpora_dir.display()
-        ));
+        )))?;
     }
     if !fuzz_exe.exists() {
-        exit_help(&format!(
+        Err(exit_help(&format!(
             "Fuzz executable ({}) not found",
             fuzz_exe.display()
-        ));
+        )))?;
     }
+    Ok(())
 }
 
-fn main() {
+fn app() -> AppResult {
     // Parse args
     let args = env::args().collect::<Vec<_>>();
-    let build_dir = args
+    let build_dir = args.get(1).ok_or(exit_help("Must set build dir"))?;
-        .get(1)
-        .unwrap_or_else(|| exit_help("Must set build dir"));
     if build_dir == "--help" {
-        exit_help("--help requested")
+        Err(exit_help("--help requested"))?;
     }
-    let corpora_dir = args
+    let corpora_dir = args.get(2).ok_or(exit_help("Must set fuzz corpora dir"))?;
-        .get(2)
-        .unwrap_or_else(|| exit_help("Must set fuzz corpora dir"));
     let fuzz_target = args
         .get(3)
         // Require fuzz target for now. In the future it could be optional and the tool could
         // iterate over all compiled fuzz targets
-        .unwrap_or_else(|| exit_help("Must set fuzz target"));
+        .ok_or(exit_help("Must set fuzz target"))?;
     if args.get(4).is_some() {
-        exit_help("Too many args")
+        Err(exit_help("Too many args"))?;
     }
 
     let build_dir = Path::new(build_dir);
     let corpora_dir = Path::new(corpora_dir);
     let fuzz_exe = build_dir.join("bin/fuzz");
 
-    sanity_check(corpora_dir, &fuzz_exe);
+    sanity_check(corpora_dir, &fuzz_exe)?;
 
-    deterministic_coverage(build_dir, corpora_dir, &fuzz_exe, fuzz_target);
+    deterministic_coverage(build_dir, corpora_dir, &fuzz_exe, fuzz_target)
 }
 
-fn using_libfuzzer(fuzz_exe: &Path) -> bool {
+fn using_libfuzzer(fuzz_exe: &Path) -> Result<bool, AppError> {
     println!("Check if using libFuzzer ...");
     let stderr = Command::new(fuzz_exe)
         .arg("-help=1") // Will be interpreted as option (libfuzzer) or as input file
         .env("FUZZ", "addition_overflow") // Any valid target
         .output()
-        .expect("fuzz failed")
+        .map_err(|e| format!("fuzz failed with {e}"))?
         .stderr;
-    let help_output = str::from_utf8(&stderr).expect("The -help=1 output must be valid text");
+    let help_output = str::from_utf8(&stderr)
-    help_output.contains("libFuzzer")
+        .map_err(|e| format!("The libFuzzer -help=1 output must be valid text ({e})"))?;
+    Ok(help_output.contains("libFuzzer"))
 }
 
 fn deterministic_coverage(
@@ -92,25 +94,25 @@ fn deterministic_coverage(
     corpora_dir: &Path,
     fuzz_exe: &Path,
     fuzz_target: &str,
-) {
+) -> AppResult {
-    let using_libfuzzer = using_libfuzzer(fuzz_exe);
+    let using_libfuzzer = using_libfuzzer(fuzz_exe)?;
     let profraw_file = build_dir.join("fuzz_det_cov.profraw");
     let profdata_file = build_dir.join("fuzz_det_cov.profdata");
     let corpus_dir = corpora_dir.join(fuzz_target);
     let mut entries = read_dir(&corpus_dir)
-        .unwrap_or_else(|err| {
+        .map_err(|err| {
             exit_help(&format!(
                 "The fuzz target's input directory must exist! ({}; {})",
                 corpus_dir.display(),
                 err
             ))
-        })
+        })?
         .map(|entry| entry.expect("IO error"))
         .collect::<Vec<_>>();
     entries.sort_by_key(|entry| entry.file_name());
-    let run_single = |run_id: u8, entry: &Path| {
+    let run_single = |run_id: u8, entry: &Path| -> Result<PathBuf, AppError> {
         let cov_txt_path = build_dir.join(format!("fuzz_det_cov.show.{run_id}.txt"));
-        assert!({
+        if !{
             {
                 let mut cmd = Command::new(fuzz_exe);
                 if using_libfuzzer {
@@ -122,20 +124,26 @@ fn deterministic_coverage(
             .env("FUZZ", fuzz_target)
             .arg(entry)
             .status()
-            .expect("fuzz failed")
+            .map_err(|e| format!("fuzz failed with {e}"))?
             .success()
-        });
+        } {
-        assert!(Command::new(LLVM_PROFDATA)
+            Err("fuzz failed".to_string())?;
+        }
+        if !Command::new(LLVM_PROFDATA)
             .arg("merge")
             .arg("--sparse")
             .arg(&profraw_file)
             .arg("-o")
             .arg(&profdata_file)
             .status()
-            .expect("merge failed")
+            .map_err(|e| format!("{LLVM_PROFDATA} merge failed with {e}"))?
-            .success());
+            .success()
-        let cov_file = File::create(&cov_txt_path).expect("Failed to create coverage txt file");
+        {
-        assert!(Command::new(LLVM_COV)
+            Err(format!("{LLVM_PROFDATA} merge failed. This can be a sign of compiling without code coverage support."))?;
+        }
+        let cov_file = File::create(&cov_txt_path)
+            .map_err(|e| format!("Failed to create coverage txt file ({e})"))?;
+        if !Command::new(LLVM_COV)
             .args([
                 "show",
                 "--show-line-counts-or-regions",
@@ -146,27 +154,31 @@ fn deterministic_coverage(
             .arg(fuzz_exe)
             .stdout(cov_file)
             .spawn()
-            .expect("Failed to execute llvm-cov")
+            .map_err(|e| format!("{LLVM_COV} show failed with {e}"))?
             .wait()
-            .expect("Failed to execute llvm-cov")
+            .map_err(|e| format!("{LLVM_COV} show failed with {e}"))?
-            .success());
+            .success()
-        cov_txt_path
+        {
+            Err(format!("{LLVM_COV} show failed"))?;
+        };
+        Ok(cov_txt_path)
     };
-    let check_diff = |a: &Path, b: &Path, err: &str| {
+    let check_diff = |a: &Path, b: &Path, err: &str| -> AppResult {
         let same = Command::new(GIT)
             .args(["--no-pager", "diff", "--no-index"])
             .arg(a)
             .arg(b)
             .status()
-            .expect("Failed to execute git command")
+            .map_err(|e| format!("{GIT} diff failed with {e}"))?
             .success();
         if !same {
-            eprintln!();
+            Err(format!(
-            eprintln!("The coverage was not deterministic between runs.");
+                r#"
-            eprintln!("{}", err);
+The coverage was not deterministic between runs.
-            eprintln!("Exiting.");
+{err}"#
-            exit(1);
+            ))?;
         }
+        Ok(())
     };
     // First, check that each fuzz input is deterministic running by itself in a process.
     //
@@ -175,29 +187,46 @@ fn deterministic_coverage(
     //
     // Also, This can catch issues where several fuzz inputs are non-deterministic, but the sum of
     // their overall coverage trace remains the same across runs and thus remains undetected.
+    println!("Check each fuzz input individually ...");
     for entry in entries {
         let entry = entry.path();
-        assert!(entry.is_file());
+        if !entry.is_file() {
-        let cov_txt_base = run_single(0, &entry);
+            Err(format!("{} should be a file", entry.display()))?;
-        let cov_txt_repeat = run_single(1, &entry);
+        }
+        let cov_txt_base = run_single(0, &entry)?;
+        let cov_txt_repeat = run_single(1, &entry)?;
         check_diff(
             &cov_txt_base,
             &cov_txt_repeat,
             &format!("The fuzz target input was {}.", entry.display()),
-        );
+        )?;
     }
     // Finally, check that running over all fuzz inputs in one process is deterministic as well.
     // This can catch issues where mutable global state is leaked from one fuzz input execution to
     // the next.
+    println!("Check all fuzz inputs in one go ...");
     {
-        assert!(corpus_dir.is_dir());
+        if !corpus_dir.is_dir() {
-        let cov_txt_base = run_single(0, &corpus_dir);
+            Err(format!("{} should be a folder", corpus_dir.display()))?;
-        let cov_txt_repeat = run_single(1, &corpus_dir);
+        }
+        let cov_txt_base = run_single(0, &corpus_dir)?;
+        let cov_txt_repeat = run_single(1, &corpus_dir)?;
         check_diff(
             &cov_txt_base,
             &cov_txt_repeat,
             &format!("All fuzz inputs in {} were used.", corpus_dir.display()),
-        );
+        )?;
     }
     println!("Coverage test passed for {fuzz_target}.");
+    Ok(())
+}
+
+fn main() -> ExitCode {
+    match app() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(err) => {
+            eprintln!("{}", err);
+            ExitCode::FAILURE
+        }
+    }
 }

contrib/devtools/deterministic-unittest-coverage/src/main.rs

@@ -4,90 +4,101 @@
 
 use std::env;
 use std::fs::File;
-use std::path::Path;
+use std::path::{Path, PathBuf};
-use std::process::{exit, Command};
+use std::process::{Command, ExitCode};
 use std::str;
 
+/// A type for a complete and readable error message.
+type AppError = String;
+type AppResult = Result<(), AppError>;
+
 const LLVM_PROFDATA: &str = "llvm-profdata";
 const LLVM_COV: &str = "llvm-cov";
 const GIT: &str = "git";
 
-fn exit_help(err: &str) -> ! {
+fn exit_help(err: &str) -> AppError {
-    eprintln!("Error: {}", err);
+    format!(
-    eprintln!();
+        r#"
-    eprintln!("Usage: program ./build_dir boost_unittest_filter");
+Error: {err}
-    eprintln!();
+
-    eprintln!("Refer to the devtools/README.md for more details.");
+Usage: program ./build_dir boost_unittest_filter
-    exit(1)
+
+Refer to the devtools/README.md for more details."#
+    )
 }
 
-fn sanity_check(test_exe: &Path) {
+fn sanity_check(test_exe: &Path) -> AppResult {
     for tool in [LLVM_PROFDATA, LLVM_COV, GIT] {
         let output = Command::new(tool).arg("--help").output();
         match output {
             Ok(output) if output.status.success() => {}
-            _ => {
+            _ => Err(exit_help(&format!("The tool {} is not installed", tool)))?,
-                exit_help(&format!("The tool {} is not installed", tool));
-            }
         }
     }
     if !test_exe.exists() {
-        exit_help(&format!(
+        Err(exit_help(&format!(
             "Test executable ({}) not found",
             test_exe.display()
-        ));
+        )))?;
     }
+    Ok(())
 }
 
-fn main() {
+fn app() -> AppResult {
     // Parse args
     let args = env::args().collect::<Vec<_>>();
-    let build_dir = args
+    let build_dir = args.get(1).ok_or(exit_help("Must set build dir"))?;
-        .get(1)
-        .unwrap_or_else(|| exit_help("Must set build dir"));
     if build_dir == "--help" {
-        exit_help("--help requested")
+        Err(exit_help("--help requested"))?;
     }
     let filter = args
         .get(2)
         // Require filter for now. In the future it could be optional and the tool could provide a
         // default filter.
-        .unwrap_or_else(|| exit_help("Must set boost test filter"));
+        .ok_or(exit_help("Must set boost test filter"))?;
     if args.get(3).is_some() {
-        exit_help("Too many args")
+        Err(exit_help("Too many args"))?;
     }
 
     let build_dir = Path::new(build_dir);
     let test_exe = build_dir.join("bin/test_bitcoin");
 
-    sanity_check(&test_exe);
+    sanity_check(&test_exe)?;
 
-    deterministic_coverage(build_dir, &test_exe, filter);
+    deterministic_coverage(build_dir, &test_exe, filter)
 }
 
-fn deterministic_coverage(build_dir: &Path, test_exe: &Path, filter: &str) {
+fn deterministic_coverage(build_dir: &Path, test_exe: &Path, filter: &str) -> AppResult {
     let profraw_file = build_dir.join("test_det_cov.profraw");
     let profdata_file = build_dir.join("test_det_cov.profdata");
-    let run_single = |run_id: u8| {
+    let run_single = |run_id: u8| -> Result<PathBuf, AppError> {
+        println!("Run with id {run_id}");
         let cov_txt_path = build_dir.join(format!("test_det_cov.show.{run_id}.txt"));
-        assert!(Command::new(test_exe)
+        if !Command::new(test_exe)
             .env("LLVM_PROFILE_FILE", &profraw_file)
             .env("BOOST_TEST_RUN_FILTERS", filter)
             .env("RANDOM_CTX_SEED", "21")
             .status()
-            .expect("test failed")
+            .map_err(|e| format!("test failed with {e}"))?
-            .success());
+            .success()
-        assert!(Command::new(LLVM_PROFDATA)
+        {
+            Err("test failed".to_string())?;
+        }
+        if !Command::new(LLVM_PROFDATA)
             .arg("merge")
             .arg("--sparse")
             .arg(&profraw_file)
             .arg("-o")
             .arg(&profdata_file)
             .status()
-            .expect("merge failed")
+            .map_err(|e| format!("{LLVM_PROFDATA} merge failed with {e}"))?
-            .success());
+            .success()
-        let cov_file = File::create(&cov_txt_path).expect("Failed to create coverage txt file");
+        {
-        assert!(Command::new(LLVM_COV)
+            Err(format!("{LLVM_PROFDATA} merge failed. This can be a sign of compiling without code coverage support."))?;
+        }
+        let cov_file = File::create(&cov_txt_path)
+            .map_err(|e| format!("Failed to create coverage txt file ({e})"))?;
+        if !Command::new(LLVM_COV)
             .args([
                 "show",
                 "--show-line-counts-or-regions",
@@ -98,27 +109,39 @@ fn deterministic_coverage(build_dir: &Path, test_exe: &Path, filter: &str) {
             .arg(test_exe)
             .stdout(cov_file)
             .status()
-            .expect("llvm-cov failed")
+            .map_err(|e| format!("{LLVM_COV} show failed with {e}"))?
-            .success());
+            .success()
-        cov_txt_path
+        {
+            Err(format!("{LLVM_COV} show failed"))?;
+        }
+        Ok(cov_txt_path)
     };
-    let check_diff = |a: &Path, b: &Path| {
+    let check_diff = |a: &Path, b: &Path| -> AppResult {
         let same = Command::new(GIT)
             .args(["--no-pager", "diff", "--no-index"])
             .arg(a)
             .arg(b)
             .status()
-            .expect("Failed to execute git command")
+            .map_err(|e| format!("{GIT} diff failed with {e}"))?
             .success();
         if !same {
-            eprintln!();
+            Err("The coverage was not deterministic between runs.".to_string())?;
-            eprintln!("The coverage was not deterministic between runs.");
-            eprintln!("Exiting.");
-            exit(1);
         }
+        Ok(())
     };
-    let r0 = run_single(0);
+    let r0 = run_single(0)?;
-    let r1 = run_single(1);
+    let r1 = run_single(1)?;
-    check_diff(&r0, &r1);
+    check_diff(&r0, &r1)?;
     println!("The coverage was deterministic across two runs.");
+    Ok(())
+}
+
+fn main() -> ExitCode {
+    match app() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(err) => {
+            eprintln!("{}", err);
+            ExitCode::FAILURE
+        }
+    }
 }