Feature: prefer tectonic-biber as the biber executable (#1166)

Author: CraftSpider

Cargo.lock

@@ -98,6 +98,7 @@ watchexec = "8.0"
 watchexec-filterer-globset = "8.0"
 watchexec-signals = "5.0"
 watchexec-supervisor = "5.0"
+which = "8.0"
 zip = { version = "4.0", default-features = false, features = ["deflate"] }
 clap_complete = "4.5.1"
 walkdir = "2"

Cargo.toml

@@ -72,8 +72,13 @@ nextonic show shell-completions --help
 
 The V2 interface also supports external commands. If you run `tectonic -X cmd`, where `cmd` is NOT built into Tectonic, Tectonic will search for a binary called `tectonic-cmd` and run it if it exists.
 
+In particular, if a `tectonic-biber` binary is found it will be preferred over
+the regular `biber` binary when generating bibliography with the `biblatex`
+package. This may help resolve [possible version mismatch][biber-mismatch]
+between `biber` and the bundled `biblatex` files when there are multiple TeX
+installations on a system.
 
-
+[biber-mismatch]: https://github.com/tectonic-typesetting/tectonic/issues/893
 
 ## Migration plan
 

docs/src/ref/v2cli.md

@@ -37,6 +37,7 @@ use tectonic_io_base::{
     stdstreams::{BufferedPrimaryIo, GenuineStdoutIo},
     InputHandle, IoProvider, OpenResult, OutputHandle,
 };
+use which::which;
 
 use crate::{
     ctry, errmsg,
@@ -1683,7 +1684,7 @@ impl ProcessingSession {
             Some(RerunReason::Bibtex)
         } else {
             warnings = self.tex_pass(None, status)?;
-            let maybe_biber = self.check_biber_requirement()?;
+            let maybe_biber = self.check_biber_requirement(status)?;
 
             if let Some(biber) = maybe_biber {
                 self.bs.external_tool_pass(&biber, status)?;
@@ -2034,7 +2035,10 @@ impl ProcessingSession {
     /// `loqreq` package to figure out what files `biber` needs. This
     /// functionality should probably become more generic, but I don't have a
     /// great sense as to how widely-used `logreq` is.
-    fn check_biber_requirement(&self) -> Result<Option<ExternalToolPass>> {
+    fn check_biber_requirement(
+        &self,
+        status: &mut dyn StatusBackend,
+    ) -> Result<Option<ExternalToolPass>> {
         // Is there a `.run.xml` file?
 
         let mut run_xml_path = PathBuf::from(&self.primary_input_tex_path);
@@ -2057,10 +2061,36 @@ impl ProcessingSession {
         );
 
         let mut argv = match s {
-            (true, Ok(text)) => text.split_whitespace().map(|x| x.to_owned()).collect(),
+            (true, Ok(text)) if !text.trim().is_empty() => {
+                text.split_whitespace().map(|x| x.to_owned()).collect()
+            }
+            // when `TECTONIC_TEST_FAKE_BIBER` is empty, proceed to discover
+            // the biber binary as follows.
             _ => vec!["biber".to_owned()],
         };
 
+        // Moreover, we allow an override of the biber executable, to cope with
+        // possible version mismatch of the bundled biblatex package, as filed
+        // in issue #893. Since PR #1103, the `tectonic-biber` override can
+        // also be invoked with `tectonic -X biber`.
+        let find_by = |binary_name: &str| -> Option<String> {
+            if let Ok(pathbuf) = which(binary_name) {
+                if let Some(biber_path) = pathbuf.to_str() {
+                    return Some(biber_path.to_owned());
+                }
+            }
+            None
+        };
+
+        let mut use_tectonic_biber_override = false;
+        for binary_name in ["./tectonic-biber", "tectonic-biber"] {
+            if let Some(biber_path) = find_by(binary_name) {
+                argv = vec![biber_path];
+                use_tectonic_biber_override = true;
+                break;
+            }
+        }
+
         let mut extra_requires = HashSet::new();
 
         // Do a sketchy XML parse to see if there's info about a biber
@@ -2227,6 +2257,9 @@ impl ProcessingSession {
             // No biber invocation, in the end.
             None
         } else {
+            if use_tectonic_biber_override {
+                tt_note!(status, "using `tectonic-biber`, found at {}", argv[0]);
+            }
             Some(ExternalToolPass {
                 argv,
                 extra_requires,

src/driver.rs

@@ -1,4 +1,3 @@
-// Copyright 2016-2022 the Tectonic Project
 // Licensed under the MIT License.
 
 use lazy_static::lazy_static;
@@ -265,11 +264,17 @@ fn bad_outfmt_1() {
 }
 
 fn run_with_biber(args: &str, stdin: &str) -> Output {
+    run_with_biber_exe(None, args, stdin, &["subdirectory/empty.bib"])
+}
+
+fn run_with_biber_exe(executable: Option<&str>, args: &str, stdin: &str, files: &[&str]) -> Output {
     let fmt_arg = get_plain_format_arg();
-    let tempdir = setup_and_copy_files(&["subdirectory/empty.bib"]);
+    let tempdir = setup_and_copy_files(files);
     let mut command = prep_tectonic(tempdir.path(), &[&fmt_arg, "-"]);
 
-    let test_cmd = if cfg!(windows) {
+    let test_cmd = if let Some(exe) = executable {
+        format!("{exe} {args}")
+    } else if cfg!(windows) {
         format!(
             "cmd /c {} {}",
             util::test_path(&["fake-biber.bat"]).display(),
@@ -355,28 +360,9 @@ fn biber_failure() {
 
 #[test]
 fn biber_no_such_tool() {
-    let fmt_arg = get_plain_format_arg();
-    let tempdir = setup_and_copy_files(&[]);
-    let mut command = prep_tectonic(tempdir.path(), &[&fmt_arg, "-"]);
-
-    command.env("TECTONIC_TEST_FAKE_BIBER", "ohnothereisnobiberprogram");
-
     const REST: &str = r"\bye";
     let tex = format!("{BIBER_TRIGGER_TEX}{REST}");
-
-    command
-        .stdin(Stdio::piped())
-        .stdout(Stdio::piped())
-        .stderr(Stdio::piped());
-    println!("running {command:?}");
-    let mut child = command.spawn().expect("tectonic failed to start");
-
-    write!(child.stdin.as_mut().unwrap(), "{tex}")
-        .expect("failed to send data to tectonic subprocess");
-
-    let output = child
-        .wait_with_output()
-        .expect("failed to wait on tectonic subprocess");
+    let output = run_with_biber_exe(Some("ohnothereisnobiberprogram"), "", &tex, &[]);
     error_or_panic(&output);
 }
 
@@ -387,9 +373,7 @@ fn biber_signal() {
     error_or_panic(&output);
 }
 
-#[test]
-fn biber_success() {
-    const REST: &str = r"
+const BIBER_VALIDATE_TEX: &str = r"
 \ifsecond
 \ifnum\input{biberout.qqq}=456\relax
 a
@@ -398,11 +382,30 @@ a
 \fi
 \fi
 \bye";
-    let tex = format!("{BIBER_TRIGGER_TEX}{REST}");
+
+#[test]
+fn biber_success() {
+    let tex = format!("{BIBER_TRIGGER_TEX}{BIBER_VALIDATE_TEX}");
     let output = run_with_biber("success", &tex);
     success_or_panic(&output);
 }
 
+/// Test `tectonic-biber` override: when no args passed, fall back to $PATH
+/// lookup for `tectonic-biber` first, and then `biber`. Currently defined in:
+/// [`tectonic::driver::ProcessingSession::check_biber_requirement`]
+#[cfg(unix)]
+#[test]
+fn biber_tectonic_override() {
+    let tex = format!("{BIBER_TRIGGER_TEX}{BIBER_VALIDATE_TEX}");
+    let output = run_with_biber_exe(
+        Some(""),
+        "", // no args passed
+        &tex,
+        &["subdirectory/empty.bib", "tectonic-biber"],
+    );
+    success_or_panic(&output);
+}
+
 /// #844: biber input with absolute path blows away the file
 ///
 /// We need to create a separate temporary directory to see if the abspath input

tests/executable.rs

@@ -0,0 +1,8 @@
+#! /bin/sh
+# Copyright 2021 the Tetonic Project
+# Licensed under the MIT License.
+
+# A stand-in for biber for our testing framework.
+
+echo "tectonic-biber says success and makes a file"
+echo 456 >biberout.qqq