rename reproducible mode to deterministic mode and move to unstable opts

Author: Mrmaxmeier

crates/bridge_core/src/lib.rs

@@ -254,7 +254,7 @@ impl<'a> CoreBridgeLauncher<'a> {
         self
     }
 
-    /// Ditto for file modification timestamps. In reproducible mode, we return
+    /// Ditto for file modification timestamps. In deterministic mode, we return
     /// the configured build time (i.e. `SOURCE_DATE_EPOCH`) instead of the
     /// modification timestamp reported by the IO subsystem.
     pub fn with_mtime_override(&mut self, mtime_override: Option<i64>) -> &mut Self {
@@ -815,7 +815,7 @@ struct FsEmulationSettings {
     /// resolve paths to TeX sources), we can disable them for reproducibility.
     expose_absolute_paths: bool,
 
-    /// Ditto for file modification timestamps. In reproducible mode, we return
+    /// Ditto for file modification timestamps. In deterministic mode, we return
     /// the configured build time (i.e. `SOURCE_DATE_EPOCH`) instead of the
     /// modification timestamp reported by the IO subsystem.
     mtime_override: Option<i64>,

docs/src/ref/v1cli.md

@@ -58,7 +58,6 @@ The following are the available flags.
 |       | `--outfmt <FORMAT>`       | The kind of output to generate [default: pdf]  [possible values: pdf, html, xdv, aux, format]  |
 |       | `--pass <PASS>`           | Which engines to run [default: default]  [possible values: default, tex, bibtex_first]         |
 | `-p`  | `--print`                 | Print the engine's chatter during processing                                                   |
-|       | `--reproducible`          | Ensure deterministic builds                                                                    |
 | `-r`  | `--reruns <COUNT>`        | Rerun the TeX engine exactly this many times after the first                                   |
 |       | `--synctex`               | Generate SyncTeX data                                                                          |
 |       | `--untrusted`             | Input is untrusted: disable all known-insecure features                                        |

docs/src/v2cli/build.md

@@ -64,10 +64,4 @@ be easy to forget to use this option; in cases where untrusted inputs are a
 genuine concern, we recommend setting the environment variable
 `TECTONIC_UNTRUSTED_MODE` to a non-empty value. This has the same effect as the
 `--untrusted` option. Note, however, that a hostile shell user can trivially
-clear this variable.
-
-The `--reproducible` option ensures a fully deterministic build environment.
-The most notable difference is a static document build time (`\today`), which can
-be configured explicitly by setting the `SOURCE_DATE_EPOCH` environment variable.
-There's a few ways to break determinism (shell escape, reading from `/dev/urandom`),
-but anything else (especially behaviour in TeXLive packages) is considered a bug.
+clear this variable.

docs/src/v2cli/compile.md

@@ -111,7 +111,6 @@ The following are the available flags.
 |       | `--outfmt <FORMAT>`       | The kind of output to generate. Possible values: `pdf` (the default), `html`, `xdv`, `aux`, `format` |
 |       | `--pass <PASS>`           | Which engines to run. Possible values: `default`, `tex`, `bibtex_first` |
 | `-p`  | `--print`                 | Print the engine's chatter during processing |
-|       | `--reproducible`          | Ensure deterministic builds |
 | `-r`  | `--reruns <COUNT>`        | Rerun the TeX engine exactly this many times after the first |
 |       | `--synctex`               | Generate SyncTeX data |
 |       | `--untrusted`             | Input is untrusted: disable all known-insecure features |
@@ -135,3 +134,4 @@ the set of unstable options is subject to change at any time.
 | `-Z search-path=<path>`  | Also look in `<path>` for files (unless `--untrusted` has been specified), like TEXINPUTS. Can be specified multiple times. |
 | `-Z shell-escape`        | Enable `\write18` (unless `--untrusted` has been specified) |
 | `-Z shell-escape-cwd=<path>` | Working directory to use for \write18. Use $(pwd) for same behaviour as most other engines (e.g. for relative paths in \inputminted). Implies -Z shell-escape |
+| `-Z deterministic-mode`  | Force a deterministic build environment. Note that setting `SOURCE_DATE_EPOCH` is usually sufficient for reproducible builds, and this option makes some extra functionality trade-offs. Specifically, deterministic mode breaks SyncTeX's auxiliary files as they include and rely on absolute file paths |

src/bin/tectonic/compile.rs

@@ -89,10 +89,6 @@ pub struct CompileOptions {
     #[structopt(long)]
     untrusted: bool,
 
-    /// Ensure deterministic build environment
-    #[structopt(long = "reproducible")]
-    reproducible_mode: bool,
-
     /// Unstable options. Pass -Zhelp to show a list
     #[structopt(name = "option", short = "Z", number_of_values = 1)]
     unstable: Vec<UnstableArg>,
@@ -115,14 +111,14 @@ impl CompileOptions {
         let mut sess_builder =
             ProcessingSessionBuilder::new_with_security(SecuritySettings::new(stance));
         let format_path = self.format;
+        let deterministic_mode = unstable.deterministic_mode;
         sess_builder
             .unstables(unstable)
             .format_name(&format_path)
             .keep_logs(self.keep_logs)
             .keep_intermediates(self.keep_intermediates)
             .format_cache_path(config.format_cache_path()?)
-            .synctex(self.synctex)
-            .reproducible_mode(self.reproducible_mode);
+            .synctex(self.synctex);
 
         sess_builder.output_format(OutputFormat::from_str(&self.outfmt).unwrap());
 
@@ -202,7 +198,7 @@ impl CompileOptions {
         } else {
             sess_builder.bundle(config.default_bundle(only_cached, status)?);
         }
-        sess_builder.build_date_from_env(self.reproducible_mode);
+        sess_builder.build_date_from_env(deterministic_mode);
         run_and_report(sess_builder, status).map(|_| 0)
     }
 }

src/bin/tectonic/v2cli.rs

@@ -238,10 +238,6 @@ pub struct BuildCommand {
     /// Open built document using system handler
     #[structopt(long)]
     open: bool,
-
-    /// Ensure deterministic build environment
-    #[structopt(long = "reproducible")]
-    reproducible_mode: bool,
 }
 
 impl BuildCommand {
@@ -264,7 +260,6 @@ impl BuildCommand {
         let mut setup_options =
             DocumentSetupOptions::new_with_security(SecuritySettings::new(stance));
         setup_options.only_cached(self.only_cached);
-        setup_options.reproducible_mode(self.reproducible_mode);
 
         for output_name in doc.output_names() {
             let mut builder = doc.setup_session(output_name, &setup_options, status)?;

src/docmodel.rs

@@ -29,6 +29,7 @@ use crate::{
     errors::{ErrorKind, Result},
     status::StatusBackend,
     test_util, tt_note,
+    unstable_opts::UnstableOptions,
 };
 
 /// Options for setting up [`Document`] instances with the driver
@@ -42,7 +43,7 @@ pub struct DocumentSetupOptions {
     security: SecuritySettings,
 
     /// Ensure a deterministic build environment.
-    reproducible_mode: bool,
+    deterministic_mode: bool,
 }
 
 impl DocumentSetupOptions {
@@ -51,7 +52,7 @@ impl DocumentSetupOptions {
     pub fn new_with_security(security: SecuritySettings) -> Self {
         DocumentSetupOptions {
             only_cached: false,
-            reproducible_mode: false,
+            deterministic_mode: false,
             security,
         }
     }
@@ -67,8 +68,8 @@ impl DocumentSetupOptions {
     }
 
     /// Specify whether we want to ensure a deterministic build environment.
-    pub fn reproducible_mode(&mut self, s: bool) -> &mut Self {
-        self.reproducible_mode = s;
+    pub fn deterministic_mode(&mut self, s: bool) -> &mut Self {
+        self.deterministic_mode = s;
         self
     }
 }
@@ -167,8 +168,11 @@ impl DocumentExt for Document {
         sess_builder
             .output_format(output_format)
             .format_name(&profile.tex_format)
-            .build_date_from_env(setup_options.reproducible_mode)
-            .reproducible_mode(setup_options.reproducible_mode)
+            .build_date_from_env(setup_options.deterministic_mode)
+            .unstables(UnstableOptions {
+                deterministic_mode: setup_options.deterministic_mode,
+                ..Default::default()
+            })
             .pass(PassSetting::Default)
             .primary_input_buffer(input_buffer.as_bytes())
             .tex_input_name(output_profile);

src/driver.rs

@@ -817,7 +817,6 @@ pub struct ProcessingSessionBuilder {
     build_date: Option<SystemTime>,
     unstables: UnstableOptions,
     shell_escape_mode: ShellEscapeMode,
-    reproducible_mode: bool,
     html_assets_spec_path: Option<String>,
     html_precomputed_assets: Option<AssetSpecification>,
     html_do_not_emit_files: bool,
@@ -988,11 +987,11 @@ impl ProcessingSessionBuilder {
 
     /// Configures the date and time of the processing session from the environment:
     /// If `SOURCE_DATE_EPOCH` is set, it's used as the build date.
-    /// If `force_reproducible` is set, we fall back to UNIX_EPOCH.
+    /// If `force_deterministic` is set, we fall back to UNIX_EPOCH.
     /// Otherwise, we use the current system time.
-    pub fn build_date_from_env(&mut self, force_reproducible: bool) -> &mut Self {
+    pub fn build_date_from_env(&mut self, force_deterministic: bool) -> &mut Self {
         let build_date_str = std::env::var("SOURCE_DATE_EPOCH").ok();
-        let build_date = match (force_reproducible, build_date_str) {
+        let build_date = match (force_deterministic, build_date_str) {
             (_, Some(s)) => {
                 let epoch = s
                     .parse::<u64>()
@@ -1047,21 +1046,6 @@ impl ProcessingSessionBuilder {
         self
     }
 
-    /// Ensure a deterministic build environment.
-    ///
-    /// The most significant user-facing difference is a static document build
-    /// date, but this is already covered by [`build_date_from_env`], which
-    /// accepts a `reproducible` flag. Additionally, reproducible mode spoofs
-    /// file modification times and hides absolute paths from the engine.
-    ///
-    /// There's a few ways to break determinism (shell escape, reading from
-    /// `/dev/urandom`), but anything else (especially behaviour in TeXLive
-    /// packages) is considered a bug.
-    pub fn reproducible_mode(&mut self, reproducible: bool) -> &mut Self {
-        self.reproducible_mode = reproducible;
-        self
-    }
-
     /// When using HTML mode, emit an asset specification file instead of actual
     /// asset files.
     ///
@@ -1277,7 +1261,6 @@ impl ProcessingSessionBuilder {
             build_date: self.build_date.unwrap_or(SystemTime::UNIX_EPOCH),
             unstables: self.unstables,
             shell_escape_mode,
-            reproducible_mode: self.reproducible_mode,
             html_assets_spec_path: self.html_assets_spec_path,
             html_precomputed_assets: self.html_precomputed_assets,
             html_emit_files: !self.html_do_not_emit_files,
@@ -1345,8 +1328,6 @@ pub struct ProcessingSession {
 
     unstables: UnstableOptions,
 
-    reproducible_mode: bool,
-
     /// How to handle shell-escape. The `Defaulted` option will never
     /// be used here.
     shell_escape_mode: ShellEscapeMode,
@@ -1871,15 +1852,15 @@ impl ProcessingSession {
             let mut launcher =
                 CoreBridgeLauncher::new_with_security(&mut self.bs, status, self.security.clone());
 
-            // In reproducible mode, we stub a few aspects of the environment.
+            // In deterministic mode, we stub a few aspects of the environment.
             // They default to a "realistic" view, but we override them with static values:
-            if self.reproducible_mode {
+            if self.unstables.deterministic_mode {
                 launcher.with_expose_absolute_paths(false);
                 launcher.with_mtime_override(Some(
                     self.build_date
                         .duration_since(SystemTime::UNIX_EPOCH)
                         .map(|x| x.as_secs() as i64)
-                        .expect("invalid build date in reproducible mode"),
+                        .expect("invalid build date in deterministic mode"),
                 ));
             }
 

src/unstable_opts.rs

@@ -29,6 +29,11 @@ const HELPMSG: &str = r#"Available unstable options:
     -Z shell-escape-cwd         Working directory to use for \write18. Use $(pwd) for same behaviour as
                                     most other engines (e.g. for relative paths in \inputminted).
                                     Implies -Z shell-escape
+    -Z deterministic-mode       Force a deterministic build environment. Note that setting
+                                    `SOURCE_DATE_EPOCH` is usually sufficient for reproducible builds,
+                                    and this option makes some extra functionality trade-offs.
+                                    Specifically, deterministic mode breaks SyncTeX's auxiliary files
+                                    as they include and rely on absolute file paths
 "#;
 
 // Each entry of this should correspond to a field of UnstableOptions.
@@ -41,6 +46,7 @@ pub enum UnstableArg {
     SearchPath(PathBuf),
     ShellEscapeEnabled,
     ShellEscapeCwd(String),
+    DeterministicModeEnabled,
 }
 
 impl FromStr for UnstableArg {
@@ -97,6 +103,8 @@ impl FromStr for UnstableArg {
                 require_value("path").map(|s| UnstableArg::ShellEscapeCwd(s.to_string()))
             }
 
+            "deterministic-mode" => require_no_value(value, UnstableArg::DeterministicModeEnabled),
+
             _ => Err(format!("Unknown unstable option '{arg}'").into()),
         }
     }
@@ -110,6 +118,18 @@ pub struct UnstableOptions {
     pub min_crossrefs: Option<i32>,
     pub extra_search_paths: Vec<PathBuf>,
     pub shell_escape_cwd: Option<String>,
+
+    /// Ensure a deterministic build environment.
+    ///
+    /// The most significant user-facing difference is a static document build
+    /// date, but this is already covered by [`crate::driver::ProcessingSessionBuilder::build_date_from_env`],
+    /// which accepts a `deterministic` flag. Additionally, deterministic mode
+    /// spoofs file modification times and hides absolute paths from the engine.
+    ///
+    /// There's a few ways to break determinism (shell escape, reading from
+    /// `/dev/urandom`), but anything else (especially behaviour in TeXLive
+    /// packages) is considered a bug.
+    pub deterministic_mode: bool,
 }
 
 impl UnstableOptions {
@@ -132,6 +152,7 @@ impl UnstableOptions {
                     opts.shell_escape_cwd = Some(p);
                     opts.shell_escape = true;
                 }
+                DeterministicModeEnabled => opts.deterministic_mode = true,
             }
         }