User-friendly build failure output

[kornelski]

The current presentation of build errors is difficult for users to understand. The real cause of the failure gets buried under an intimidating amount of irrelevant information printed before and after the actual error the script is trying to communicate.

This implements the API required for #167, making pkg_config's error output much more readable, avoiding most of the other output that obscures the root cause of the failure.

Before

↓ note that the output is so long that GitHub doesn't display it fully. Users have the same problem with terminals and output panels in IDEs that have a limited height.

error: failed to run custom build command for `example v0.1.0 (example)`
note: To improve backtraces for build dependencies, set the CARGO_PROFILE_DEV_BUILD_OVERRIDE_DEBUG=true environment variable to enable debug information generation.

Caused by:
  process didn't exit successfully: `example/target/debug/build/example-73fa92de6d113cf2/build-script-build` (exit status: 101)
  --- stdout
  cargo:rerun-if-env-changed=FOOBAR_NO_PKG_CONFIG
  cargo:rerun-if-env-changed=PKG_CONFIG_aarch64-apple-darwin
  cargo:rerun-if-env-changed=PKG_CONFIG_aarch64_apple_darwin
  cargo:rerun-if-env-changed=HOST_PKG_CONFIG
  cargo:rerun-if-env-changed=PKG_CONFIG
  cargo:rerun-if-env-changed=FOOBAR_STATIC
  cargo:rerun-if-env-changed=FOOBAR_DYNAMIC
  cargo:rerun-if-env-changed=PKG_CONFIG_ALL_STATIC
  cargo:rerun-if-env-changed=PKG_CONFIG_ALL_DYNAMIC
  cargo:rerun-if-env-changed=PKG_CONFIG_PATH_aarch64-apple-darwin
  cargo:rerun-if-env-changed=PKG_CONFIG_PATH_aarch64_apple_darwin
  cargo:rerun-if-env-changed=HOST_PKG_CONFIG_PATH
  cargo:rerun-if-env-changed=PKG_CONFIG_PATH
  cargo:rerun-if-env-changed=PKG_CONFIG_LIBDIR_aarch64-apple-darwin
  cargo:rerun-if-env-changed=PKG_CONFIG_LIBDIR_aarch64_apple_darwin
  cargo:rerun-if-env-changed=HOST_PKG_CONFIG_LIBDIR
  cargo:rerun-if-env-changed=PKG_CONFIG_LIBDIR
  cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR_aarch64-apple-darwin
  cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR_aarch64_apple_darwin
  cargo:rerun-if-env-changed=HOST_PKG_CONFIG_SYSROOT_DIR
  cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR

  --- stderr
  thread 'main' panicked at build.rs:4:41:
  called `Result::unwrap()` on an `Err` value:
  pkg-config exited with status code 1
  > PKG_CONFIG_ALLOW_SYSTEM_LIBS=1 PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1 pkg-config --libs --cflags foobar

  The system library `foobar` required by crate `example` was not found.
  The file `foobar.pc` needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory.
  The PKG_CONFIG_PATH environment variable is not set.

  HINT: if you have installed the library, try setting PKG_CONFIG_PATH to the directory containing `foobar.pc`.

  stack backtrace:
     0: rust_begin_unwind
               at /rustc/eeb90cda1969383f56a2637cbd3037bdf598841c/library/std/src/panicking.rs:665:5
     1: core::panicking::panic_fmt
               at /rustc/eeb90cda1969383f56a2637cbd3037bdf598841c/library/core/src/panicking.rs:74:14
     2: core::result::unwrap_failed
               at /rustc/eeb90cda1969383f56a2637cbd3037bdf598841c/library/core/src/result.rs:1679:5
     3: build_script_build::main
     4: core::ops::function::FnOnce::call_once
  note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

After

The following warnings were emitted during compilation:

warning: example@0.1.0: The system library `foobar` was not found, because command `pkg-config` failed with exit status: 1

error: failed to run custom build command for `example v0.1.0 (example)`
note: To improve backtraces for build dependencies, set the CARGO_PROFILE_DEV_BUILD_OVERRIDE_DEBUG=true environment variable to enable debug information generation.

Caused by:
  process didn't exit successfully: `example/target/debug/build/example-73fa92de6d113cf2/build-script-build` (exit status: 101)
  --- stdout
  cargo:warning=The system library `foobar` was not found, because command `pkg-config` failed with exit status: 1

  --- stderr

  pkg-config exited with status code 1
  > PKG_CONFIG_ALLOW_SYSTEM_LIBS=1 PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1 pkg-config --libs --cflags foobar

  The system library `foobar` required by crate `example` was not found.
  The file `foobar.pc` needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory.
  The PKG_CONFIG_PATH environment variable is not set.

  HINT: if you have installed the library, try setting PKG_CONFIG_PATH to the directory containing `foobar.pc`.

This requires crates to call pkg_config::probe_library_or_exit("foobar") instead of pkg_config::probe_library("foobar").unwrap().

This is because the general-purpose probe function returning Result can't know whether the build script will continue and use some fallback, and must print the cargo:rerun-if-env-changed directives just in case. *_or_exit version knows the build will fail. Failed builds don't get cached and will re-run anyway, so there's no need to print the noisy rerun-if-env-changed directives in that case.

[gdesmott]

It would be nice to be able to use this in https://github.com/gdesmott/system-deps

I suppose the only option would be to add system_deps::Config::new().probe_or_exist() re-implementing the same logic, right?

[kornelski]

Yes, you'd have to add a similar API.