Rename ..WEB_BUNDLE.. to ..BUNDLE.. & document

crates/bundles/build.rs

@@ -1,35 +1,36 @@
-// Copyright 2016-2021 the Tectonic Project
+// Copyright 2016-2025 the Tectonic Project
 // Licensed under the MIT License.
 
 use std::env;
 
-/// The current hardcoded default prefix for tectonic's web bundle.
-const TECTONIC_WEB_BUNDLE_PREFIX_DEFAULT: &str = "https://relay.fullyjustified.net";
+/// 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: &str = "TECTONIC_WEB_BUNDLE_LOCKED";
-const PREFIX_VAR: &str = "TECTONIC_WEB_BUNDLE_PREFIX";
+const LOCKED_VAR_NAME: &str = "TECTONIC_BUNDLE_LOCKED";
+const PREFIX_VAR_NAME: &str = "TECTONIC_BUNDLE_PREFIX";
 
-/// Sets the environment variables for the default web bundle.
+/// Sets the environment variables for the default bundle.
 ///
-/// `${TECTONIC_WEB_BUNDLE_PREFIX}` would lead to a url in the form of
-/// `${TECTONIC_WEB_BUNDLE_PREFIX}/default_bundle.tar`, while the optional
-/// "locked" url, `${TECTONIC_WEB_BUNDLE_LOCKED}`, can be used to pin the
+/// `${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 web_bundle_presets() {
+///
+fn bundle_presets() {
     // load from env
-    let web_bundle_locked = env::var(LOCKED_VAR).unwrap_or("".into());
-    let web_bundle_prefix = match env::var(PREFIX_VAR) {
+    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_WEB_BUNDLE_PREFIX_DEFAULT.into(),
+        _ => TECTONIC_BUNDLE_PREFIX_DEFAULT.into(),
     };
 
     // export to rustc
-    println!("cargo:rustc-env={LOCKED_VAR}={web_bundle_locked}");
-    println!("cargo:rustc-env={PREFIX_VAR}={web_bundle_prefix}");
+    println!("cargo:rustc-env={LOCKED_VAR_NAME}={bundle_locked}");
+    println!("cargo:rustc-env={PREFIX_VAR_NAME}={bundle_prefix}");
 }
 
 fn main() {
-    web_bundle_presets();
+    bundle_presets();
 }

crates/bundles/src/lib.rs

@@ -268,22 +268,22 @@ pub fn detect_bundle(
 /// webservice.
 pub fn get_fallback_bundle_url(format_version: u32) -> String {
     // Build time environment variables declared in `bundles/build.rs`:
-    let web_bundle_locked = option_env!("TECTONIC_WEB_BUNDLE_LOCKED").unwrap_or("");
-    let web_bundle_prefix = option_env!("TECTONIC_WEB_BUNDLE_PREFIX")
+    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_WEB_BUNDLE_PREFIX must be defined at compile time");
+        .expect("TECTONIC_BUNDLE_PREFIX must be defined at compile time");
 
     // Simply return the locked url when it is specified:
-    if !web_bundle_locked.is_empty() {
-        return web_bundle_locked.to_owned();
+    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 {
-        format!("{web_bundle_prefix}/default_bundle.tar")
+        format!("{bundle_prefix}/default_bundle.tar")
     } else {
-        format!("{web_bundle_prefix}/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.