Allow overriding web bundle at _build time_

crates/bundles/build.rs

@@ -0,0 +1,37 @@
+// Copyright 2016-2025 the Tectonic Project
+// Licensed under the MIT License.
+
+use std::env;
+
+/// The current hardcoded default prefix for tectonic's bundle.
+const TECTONIC_BUNDLE_PREFIX_DEFAULT: &str = "https://relay.fullyjustified.net";
+
+/// Environment variable names to look for the bundle URLs.
+const LOCKED_VAR_NAME: &str = "TECTONIC_BUNDLE_LOCKED";
+const PREFIX_VAR_NAME: &str = "TECTONIC_BUNDLE_PREFIX";
+
+/// Sets the environment variables for the default bundle.
+///
+/// `${TECTONIC_BUNDLE_PREFIX}` would lead to a url in the form of
+/// `${TECTONIC_BUNDLE_PREFIX}/default_bundle.tar`, while the optional
+/// "locked" url, `${TECTONIC_BUNDLE_LOCKED}`, can be used to pin the
+/// default bundle to a specific version if specified. This would be useful
+/// for reproducible builds.
+///
+fn bundle_presets() {
+    // load from env
+    let bundle_locked = env::var(LOCKED_VAR_NAME).unwrap_or("".into());
+    let bundle_prefix = match env::var(PREFIX_VAR_NAME) {
+        Ok(x) if !x.is_empty() => x,
+        _ => TECTONIC_BUNDLE_PREFIX_DEFAULT.into(),
+    };
+
+    // export to rustc
+    println!("cargo::rustc-env={LOCKED_VAR_NAME}={bundle_locked}");
+    println!("cargo::rustc-env={PREFIX_VAR_NAME}={bundle_prefix}");
+    println!("cargo::warning=setting\n {LOCKED_VAR_NAME}={bundle_locked}\n {PREFIX_VAR_NAME}={bundle_prefix}");
+}
+
+fn main() {
+    bundle_presets();
+}

crates/bundles/src/lib.rs

@@ -267,12 +267,23 @@
 /// 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 {
+    // Build time environment variables declared in `bundles/build.rs`:
+    let bundle_locked = option_env!("TECTONIC_BUNDLE_LOCKED").unwrap_or("");
+    let bundle_prefix = option_env!("TECTONIC_BUNDLE_PREFIX")
+        .filter(|x| !x.is_empty())
+        .expect("TECTONIC_BUNDLE_PREFIX must be defined at compile time");
+
+    // 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")
     }
 }
 

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

@@ -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$_vFORMAT_VERSION.tar
+```
+where `$_vFORMAT_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.