From dcdadea0ca62a7359ae99bc55cf14bff234edd44 Mon Sep 17 00:00:00 2001 From: Bryan Lai Date: Sat, 1 Mar 2025 14:43:31 +0800 Subject: [PATCH] Rename ..WEB_BUNDLE.. to ..BUNDLE.. & document --- crates/bundles/build.rs | 33 +++++------ crates/bundles/src/lib.rs | 14 ++--- .../build-tectonic/bundle-default-config.md | 56 +++++++++++++++++++ 3 files changed, 80 insertions(+), 23 deletions(-) create mode 100644 docs/src/howto/build-tectonic/bundle-default-config.md diff --git a/crates/bundles/build.rs b/crates/bundles/build.rs index af469b68c..be06b4ec6 100644 --- a/crates/bundles/build.rs +++ b/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(); } diff --git a/crates/bundles/src/lib.rs b/crates/bundles/src/lib.rs index 0b1fce361..88a921b8b 100644 --- a/crates/bundles/src/lib.rs +++ b/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") } } diff --git a/docs/src/howto/build-tectonic/bundle-default-config.md b/docs/src/howto/build-tectonic/bundle-default-config.md new file mode 100644 index 000000000..e1353056f --- /dev/null +++ b/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.