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

fa7a40d contrib: Print deterministic-coverage runs (MarcoFalke)
fa75163 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 bitcoin/bitcoin#31901 (comment).

  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 fa7a40d
  janb84:
    ACK [fa7a40d](bitcoin/bitcoin@fa7a40d)

Tree-SHA512: 6c97861306e2fececa14b2d12deafb78995fc2bcf75e4e22773cb0ab4231de78834db9f1f89b30c49d77499433b1c16c1d90b97eb4069c81855bd2a7944b554f

Author: fanquake

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,113 +4,115 @@
 
 use std::env;
 use std::fs::{read_dir, File};
-use std::path::Path;
-use std::process::{exit, Command};
+use std::path::{Path, PathBuf};
+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) -> ! {
-    eprintln!("Error: {}", err);
-    eprintln!();
-    eprintln!("Usage: program ./build_dir ./qa-assets/fuzz_corpora fuzz_target_name");
-    eprintln!();
-    eprintln!("Refer to the devtools/README.md for more details.");
-    exit(1)
+fn exit_help(err: &str) -> AppError {
+    format!(
+        r#"
+Error: {err}
+
+Usage: program ./build_dir ./qa-assets/fuzz_corpora fuzz_target_name
+
+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() => {}
-            _ => {
-                exit_help(&format!("The tool {} is not installed", tool));
-            }
+            _ => Err(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
-        .get(1)
-        .unwrap_or_else(|| exit_help("Must set build dir"));
+    let build_dir = args.get(1).ok_or(exit_help("Must set build dir"))?;
     if build_dir == "--help" {
-        exit_help("--help requested")
+        Err(exit_help("--help requested"))?;
     }
-    let corpora_dir = args
-        .get(2)
-        .unwrap_or_else(|| exit_help("Must set fuzz corpora dir"));
+    let corpora_dir = args.get(2).ok_or(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");
-    help_output.contains("libFuzzer")
+    let help_output = str::from_utf8(&stderr)
+        .map_err(|e| format!("The libFuzzer -help=1 output must be valid text ({e})"))?;
+    Ok(help_output.contains("libFuzzer"))
 }
 
 fn deterministic_coverage(
     build_dir: &Path,
     corpora_dir: &Path,
     fuzz_exe: &Path,
     fuzz_target: &str,
-) {
-    let using_libfuzzer = using_libfuzzer(fuzz_exe);
+) -> AppResult {
+    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")
-            .success());
-        let cov_file = File::create(&cov_txt_path).expect("Failed to create coverage txt file");
-        assert!(Command::new(LLVM_COV)
+            .map_err(|e| format!("{LLVM_PROFDATA} merge failed with {e}"))?
+            .success()
+        {
+            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")
-            .success());
-        cov_txt_path
+            .map_err(|e| format!("{LLVM_COV} show failed with {e}"))?
+            .success()
+        {
+            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!();
-            eprintln!("The coverage was not deterministic between runs.");
-            eprintln!("{}", err);
-            eprintln!("Exiting.");
-            exit(1);
+            Err(format!(
+                r#"
+The coverage was not deterministic between runs.
+{err}"#
+            ))?;
         }
+        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());
-        let cov_txt_base = run_single(0, &entry);
-        let cov_txt_repeat = run_single(1, &entry);
+        if !entry.is_file() {
+            Err(format!("{} should be a file", entry.display()))?;
+        }
+        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());
-        let cov_txt_base = run_single(0, &corpus_dir);
-        let cov_txt_repeat = run_single(1, &corpus_dir);
+        if !corpus_dir.is_dir() {
+            Err(format!("{} should be a folder", corpus_dir.display()))?;
+        }
+        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
+        }
+    }
 }