Allow overriding web bundle at _build time_ (#1131)

Author: CraftSpider

Cargo.lock

@@ -60,6 +60,7 @@ members = [
     "crates/xdv",
     "crates/xetex_format",
     "crates/xetex_layout",
+    "tests/bundle_env_overrides_test",
 ]
 
 [lib]

Cargo.toml

@@ -37,6 +37,9 @@ use ttb_fs::TTBFsBundle;
 use ttb_net::TTBNetBundle;
 use zip::ZipBundle;
 
+/// The current hardcoded default prefix for tectonic's bundle.
+const TECTONIC_BUNDLE_PREFIX_DEFAULT: &str = "https://relay.fullyjustified.net";
+
 // How many times network bundles should retry
 // a download, and how long they should wait
 // between attempts.
@@ -261,18 +264,34 @@ pub fn detect_bundle(
 /// roughly corresponds to a TeXLive version, and the engine and TeXLive files
 /// are fairly closely coupled.
 ///
+/// The hardcoded default can be overridden at compile time by setting either:
+/// - `${TECTONIC_BUNDLE_PREFIX}`, which would lead to a URL in the form of
+///   `${TECTONIC_BUNDLE_PREFIX}/default_bundle_v${FORMAT_VERSION}.tar`, or
+/// - `${TECTONIC_BUNDLE_LOCKED}`, which can be used to pin the default bundle
+///   to a specific "snapshot" if specified. This would be useful for
+///   reproducible builds.
+///
 /// The URL template used in this function will be embedded in the binaries that
 /// you create, which may be used for years into the future, so it needs to be
 /// durable and reliable. We used `archive.org` for a while, but it had
 /// low-level reliability problems and was blocked in China. We now use a custom
 /// webservice.
 pub fn get_fallback_bundle_url(format_version: u32) -> String {
+    let bundle_locked = option_env!("TECTONIC_BUNDLE_LOCKED").unwrap_or("");
+    let bundle_prefix =
+        option_env!("TECTONIC_BUNDLE_PREFIX").unwrap_or(TECTONIC_BUNDLE_PREFIX_DEFAULT);
+
+    // Simply return the locked url when it is specified:
+    if !bundle_locked.is_empty() {
+        return bundle_locked.to_owned();
+    }
+
     // Format version 32 (TeXLive 2021) was when we introduced versioning to the
     // URL.
     if format_version < 32 {
-        "https://relay.fullyjustified.net/default_bundle.tar".to_owned()
+        format!("{bundle_prefix}/default_bundle.tar")
     } else {
-        format!("https://relay.fullyjustified.net/default_bundle_v{format_version}.tar")
+        format!("{bundle_prefix}/default_bundle_v{format_version}.tar")
     }
 }
 

crates/bundles/src/lib.rs

@@ -0,0 +1,56 @@
+# How To: Build Tectonic: Configure the Default Bundle
+
+Tectonic supports overriding the default bundle configuration at build time through environment variables. This feature is particularly useful for:
+
+- System packagers who need to specify bundle sources during compilation
+- Environments requiring reproducible builds
+- Users who want to use mirrored bundles for better reliability
+
+## Build-time Environment Variables for the Default Bundle
+
+Two environment variables control the bundle configuration:
+
+### `TECTONIC_BUNDLE_PREFIX`
+
+This variable is **required** at compile time and specifies the base URL prefix for bundles.
+A default value is provided in the build script `crates/bundles/build.rs` in the source repository.
+
+The variable is used to construct bundle URLs in the following pattern:
+```bash
+$TECTONIC_BUNDLE_PREFIX/default_bundle_v$FORMAT_VERSION.tar
+```
+where `$FORMAT_VERSION` is a suffix from an internal variable, used to distinguish different versions
+of the bundle's format for backward compatibility.
+
+For example, the current default is given by:
+```bash
+# as of January 2025
+TECTONIC_BUNDLE_PREFIX=https://relay.fullyjustified.net
+```
+so the full bundle URL is `https://relay.fullyjustified.net/default_bundle_v33.tar`,
+in which `_v33` indicates the version of the bundle format.
+Note that this hardcoded default may change, and the default value documented here may be outdated.
+Please refer to the source code of Tectonic for the latest default.
+
+### `TECTONIC_BUNDLE_LOCKED`
+
+This variable is **optional** and, when set, provides a fixed URL for the bundle. If this variable contains any non-empty value, it takes precedence over the format-version-specific URL construction using `TECTONIC_BUNDLE_PREFIX`.
+
+## Usage Examples
+
+To build Tectonic with a custom bundle prefix:
+
+```sh
+TECTONIC_BUNDLE_PREFIX="https://mirror.example.com/tectonic-bundles" cargo build
+```
+
+To build Tectonic with a locked bundle URL:
+
+```sh
+TECTONIC_BUNDLE_LOCKED="https://mirror.example.com/tectonic-bundles/my-fixed-bundle.tar" cargo build
+```
+
+### Notes
+
+- The bundle URL configuration happens at build time and may be overridden by appropriate `--bundle` flags at runtime.
+- If using `TECTONIC_BUNDLE_LOCKED`, ensure the URL points to a compatible bundle version.

docs/src/howto/build-tectonic/bundle-default-config.md

@@ -0,0 +1,103 @@
+//! Integration tests of the bundles crate.
+
+use std::env;
+use std::path::PathBuf;
+use std::process::Command;
+
+const PRE_FORMAT_VERSION: u32 = 31;
+const TEST_FORMAT_VERSION: u32 = 32;
+const TEST_BUNDLE_LOCKED: &str = "https://example.com/locked_bundle.tar";
+const TEST_BUNDLE_PREFIX: &str = "https://custom.example.com";
+
+/// Runs the test project and gets the output
+fn run_test_program(format_version: u32, env_vars: &[(&str, &str)]) -> String {
+    let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
+    let test_dir = PathBuf::from(&manifest_dir)
+        .join("tests")
+        .join("bundle_env_overrides_test");
+    let target_platform = env::var("TARGET").unwrap();
+
+    let mut cmd = Command::new("cargo");
+    cmd.arg("run")
+        .arg("--quiet")
+        .arg("--target")
+        .arg(target_platform)
+        .arg("--")
+        .arg(format_version.to_string())
+        .current_dir(&test_dir);
+
+    for (key, value) in env_vars {
+        cmd.env(key, value);
+    }
+
+    let output = cmd.output().expect("Failed to run test program");
+    assert!(
+        output.status.success(),
+        "Test program failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    String::from_utf8(output.stdout).unwrap().trim().to_string()
+}
+
+#[test]
+fn test_bundle_locked() {
+    let url_locked = run_test_program(
+        PRE_FORMAT_VERSION,
+        &[("TECTONIC_BUNDLE_LOCKED", TEST_BUNDLE_LOCKED)],
+    );
+    let url_locked_versioned = run_test_program(
+        TEST_FORMAT_VERSION,
+        &[("TECTONIC_BUNDLE_LOCKED", TEST_BUNDLE_LOCKED)],
+    );
+
+    assert_eq!(url_locked, TEST_BUNDLE_LOCKED);
+    assert_eq!(url_locked_versioned, TEST_BUNDLE_LOCKED);
+}
+
+#[test]
+fn test_bundle_prefix() {
+    let url_prefixed = run_test_program(
+        PRE_FORMAT_VERSION,
+        &[("TECTONIC_BUNDLE_PREFIX", TEST_BUNDLE_PREFIX)],
+    );
+    let url_prefixed_versioned = run_test_program(
+        TEST_FORMAT_VERSION,
+        &[("TECTONIC_BUNDLE_PREFIX", TEST_BUNDLE_PREFIX)],
+    );
+
+    assert_eq!(
+        url_prefixed,
+        format!("{TEST_BUNDLE_PREFIX}/default_bundle.tar")
+    );
+    assert_eq!(
+        url_prefixed_versioned,
+        format!("{TEST_BUNDLE_PREFIX}/default_bundle_v{TEST_FORMAT_VERSION}.tar")
+    );
+}
+
+#[test]
+fn test_precedence_locked_over_prefix() {
+    let url_both_env_set = run_test_program(
+        TEST_FORMAT_VERSION,
+        &[
+            ("TECTONIC_BUNDLE_LOCKED", TEST_BUNDLE_LOCKED),
+            ("TECTONIC_BUNDLE_PREFIX", TEST_BUNDLE_PREFIX),
+        ],
+    );
+    assert_eq!(url_both_env_set, TEST_BUNDLE_LOCKED);
+}
+
+#[test]
+fn test_empty_locked_bundle_ignored() {
+    let url_empty_locked = run_test_program(
+        TEST_FORMAT_VERSION,
+        &[
+            ("TECTONIC_BUNDLE_LOCKED", ""),
+            ("TECTONIC_BUNDLE_PREFIX", TEST_BUNDLE_PREFIX),
+        ],
+    );
+    assert_eq!(
+        url_empty_locked,
+        format!("{TEST_BUNDLE_PREFIX}/default_bundle_v{TEST_FORMAT_VERSION}.tar",)
+    );
+}

tests/bundle_env_overrides.rs

@@ -0,0 +1 @@
+target

tests/bundle_env_overrides_test/.gitignore

@@ -0,0 +1,11 @@
+[package]
+name = "bundle_env_overrides_test"
+description = "Mini project for testing compile time bundle URL overrides"
+version = "0.0.0-dev.0"
+edition = "2021"
+
+[dependencies]
+tectonic_bundles = { path = "../../crates/bundles", version = "0.0.0-dev.0" }
+
+[package.metadata.internal_dep_versions]
+tectonic_bundles = "thiscommit:2025-07-26:IKt5CJV"

tests/bundle_env_overrides_test/Cargo.toml

@@ -0,0 +1,47 @@
+# Bundle URL overrides Test
+
+This is a simple test program used by the integration tests in the `tectonic_bundles` crate to test the `get_fallback_bundle_url` function with different compile-time environment variable overrides.
+
+## Purpose
+
+The `get_fallback_bundle_url` function reads compile-time environment variables
+- `$TECTONIC_BUNDLE_LOCKED`, and
+- `$TECTONIC_BUNDLE_PREFIX`
+
+via Rust's `option_env!` macro. Since these values are baked in at compile time, the only way to properly test different override scenarios is to compile separate instances of a test program with different environment variables set.
+
+## Usage
+
+This test program is invoked by the integration tests with different environment variable overrides:
+
+```bash
+# Test default behavior with format version 32
+cargo run -- 32
+
+# Test with locked bundle
+TECTONIC_BUNDLE_LOCKED="https://example.com/bundle.tar" cargo run -- 32
+
+# Test with custom prefix
+TECTONIC_BUNDLE_PREFIX="https://custom.mirror.com" cargo run -- 31
+```
+
+## Arguments
+
+- First argument: Format version number (required)
+
+## Output
+
+The program outputs the URL returned by `get_fallback_bundle_url()` to stdout.
+
+## Environment Variables Tested
+
+- `TECTONIC_BUNDLE_LOCKED`: When set to a non-empty value, this URL is returned regardless of format version
+- `TECTONIC_BUNDLE_PREFIX`: hard codes a custom prefix for bundle URLs
+
+## Integration with Tests
+
+This test program is used by [`../bundle_env_overrides.rs`](../bundle_env_overrides.rs) to verify bundle override behavior:
+1. Locked bundle behavior (same URL for all format versions)
+2. Custom prefix behavior
+3. Format version transitions (v < 32 vs v >= 32)
+4. Environment variable precedence (locked takes priority over prefix)

tests/bundle_env_overrides_test/README.md

@@ -0,0 +1,14 @@
+#![doc = include_str!("../README.md")]
+
+use tectonic_bundles::get_fallback_bundle_url;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let format_version: u32 = args
+        .get(1)
+        .and_then(|s| s.parse().ok())
+        .expect("one must provide a valid format version to `get_fallback_bundle_url`");
+
+    let url = get_fallback_bundle_url(format_version);
+    println!("{url}");
+}