Release commit created with Cranko.

+++ cranko-release-info-v1
[[projects]]
qnames = ["tectonic_xdv", "cargo"]
version = "0.1.10"
age = 0

[[projects]]
qnames = ["tectonic_cfg_support", "cargo"]
version = "0.1.1"
age = 0

[[projects]]
qnames = ["tectonic", "cargo"]
version = "0.2.0"
age = 0

+++

CHANGELOG.md

@@ -1,3 +1,19 @@
+# tectonic 0.2.0 (2020-10-21)
+
+The 0.2 series finally adds "unstable" `-Z` flags! These allow you to configure
+engine options that are relatively low-level. The hope is to eventually set
+these kinds of things in a `Tectonic.toml` file, so their use is mildly
+discouraged, and long-term availability is not guaranteed. But there are plenty
+of times when such flags can be helpful. The currently supported options are:
+
+- `-Z min-crossrefs=<num>` controls the `-min-crossrefs` option of standalone `bibtex`
+- `-Z paper-size=<spec>` lets you control the output paper size, rather than
+  hardcoding it to be US Letter.
+
+Enormous thanks to @ralismark for finally implementing this! (#657) Now that the
+infrastructure is in place, suggestions for additional flags are more than
+welcome.
+
 # tectonic 0.1.17 (2020-10-13)
 
 - Fix source-based installation by updating to cbindgen 0.15, after later

Cargo.toml

@@ -4,7 +4,7 @@
 
 [package]
 name = "tectonic"
-version = "0.1.17"
+version = "0.2.0"
 authors = ["Peter Williams <[email protected]>"]
 build = "build.rs"
 description = """

cfg_support/CHANGELOG.md

@@ -1,8 +1,4 @@
-# See elsewhere for changelog
+# tectonic_cfg_support 0.1.1 (2020-10-21)
 
-This project’s release notes are curated from the Git history of its main
-branch. You can find them by looking at [the version of this file on the
-`release` branch][branch] or the [GitHub release history][gh-releases].
-
-[branch]: https://github.com/tectonic-typesetting/tectonic/blob/release/cfg_support/CHANGELOG.md
-[gh-releases]: https://github.com/tectonic-typesetting/tectonic/releases
+- No code changes; just issuing a new release to update deps and silence
+  Cranko's change detection.

cfg_support/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "tectonic_cfg_support"
-version = "0.1.0"
+version = "0.1.1"
 authors = [
     "Matt Rice <[email protected]>",
     "Peter Williams <[email protected]>"

src/bin/tectonic.rs

@@ -16,6 +16,7 @@ use tectonic::errors::{ErrorKind, Result};
 use tectonic::status::plain::PlainStatusBackend;
 use tectonic::status::termcolor::TermcolorStatusBackend;
 use tectonic::status::{ChatterLevel, StatusBackend};
+use tectonic::unstable_opts::{UnstableArg, UnstableOptions};
 use tectonic::{errmsg, tt_error, tt_note};
 
 #[derive(Debug, StructOpt)]
@@ -73,11 +74,18 @@ struct CliOptions {
     /// The directory in which to place output files [default: the directory containing <input>]
     #[structopt(name = "outdir", short, long, parse(from_os_str))]
     outdir: Option<PathBuf>,
+    /// Unstable options. Pass -Zhelp to show a list
+    // TODO we can't pass -Zhelp without also passing <input>
+    #[structopt(name = "option", short = "Z", number_of_values = 1)]
+    unstable: Vec<UnstableArg>,
 }
 fn inner(args: CliOptions, config: PersistentConfig, status: &mut dyn StatusBackend) -> Result<()> {
+    let unstable = UnstableOptions::from_unstable_args(args.unstable.into_iter());
+
     let mut sess_builder = ProcessingSessionBuilder::default();
     let format_path = args.format;
     sess_builder
+        .unstables(unstable)
         .format_name(&format_path)
         .keep_logs(args.keep_logs)
         .keep_intermediates(args.keep_intermediates)

src/driver.rs

@@ -26,6 +26,7 @@ use crate::engines::IoEventBackend;
 use crate::errors::{ErrorKind, Result, ResultExt};
 use crate::io::{Bundle, InputOrigin, IoProvider, IoSetup, IoSetupBuilder, OpenResult};
 use crate::status::StatusBackend;
+use crate::unstable_opts::UnstableOptions;
 use crate::{ctry, errmsg, tt_error, tt_note, tt_warning};
 use crate::{BibtexEngine, Spx2HtmlEngine, TexEngine, TexResult, XdvipdfmxEngine};
 use std::result::Result as StdResult;
@@ -326,6 +327,7 @@ pub struct ProcessingSessionBuilder {
     keep_logs: bool,
     synctex: bool,
     build_date: Option<SystemTime>,
+    unstables: UnstableOptions,
 }
 
 impl ProcessingSessionBuilder {
@@ -471,6 +473,12 @@ impl ProcessingSessionBuilder {
         self
     }
 
+    /// Loads unstable options into the processing session
+    pub fn unstables(&mut self, opts: UnstableOptions) -> &mut Self {
+        self.unstables = opts;
+        self
+    }
+
     /// Creates a `ProcessingSession`.
     pub fn create(self, status: &mut dyn StatusBackend) -> Result<ProcessingSession> {
         let mut io = IoSetupBuilder::default();
@@ -558,6 +566,7 @@ impl ProcessingSessionBuilder {
             keep_logs: self.keep_logs,
             synctex_enabled: self.synctex,
             build_date: self.build_date.unwrap_or(SystemTime::UNIX_EPOCH),
+            unstables: self.unstables,
         })
     }
 }
@@ -622,6 +631,8 @@ pub struct ProcessingSession {
 
     /// See `TexEngine::with_date` and `XdvipdfmxEngine::with_date`.
     build_date: SystemTime,
+
+    unstables: UnstableOptions,
 }
 
 const DEFAULT_MAX_TEX_PASSES: usize = 6;
@@ -1040,7 +1051,14 @@ impl ProcessingSession {
             TexEngine::new()
                 .halt_on_error_mode(true)
                 .initex_mode(true)
-                .process(&mut stack, &mut self.events, status, "UNUSED.fmt", "texput")
+                .process(
+                    &mut stack,
+                    &mut self.events,
+                    status,
+                    "UNUSED.fmt",
+                    "texput",
+                    &self.unstables,
+                )
         };
 
         match result {
@@ -1110,6 +1128,7 @@ impl ProcessingSession {
                     status,
                     &self.format_name,
                     &self.primary_input_tex_path,
+                    &self.unstables,
                 )
         };
 
@@ -1137,6 +1156,7 @@ impl ProcessingSession {
                 &mut self.events,
                 status,
                 &self.tex_aux_path.to_str().unwrap(),
+                &self.unstables,
             )
         };
 
@@ -1174,6 +1194,7 @@ impl ProcessingSession {
                 status,
                 &self.tex_xdv_path.to_str().unwrap(),
                 &self.tex_pdf_path.to_str().unwrap(),
+                &self.unstables,
             )?;
         }
 

src/engines/bibtex.rs

@@ -9,6 +9,12 @@ use super::{ExecutionState, IoEventBackend, TectonicBridgeApi};
 use crate::errors::{ErrorKind, Result};
 use crate::io::IoStack;
 use crate::status::StatusBackend;
+use crate::unstable_opts::UnstableOptions;
+
+#[repr(C)]
+pub struct BibtexConfig {
+    min_crossrefs: i32,
+}
 
 #[derive(Default)]
 pub struct BibtexEngine {}
@@ -24,16 +30,20 @@ impl BibtexEngine {
         events: &mut dyn IoEventBackend,
         status: &mut dyn StatusBackend,
         aux: &str,
+        unstables: &UnstableOptions,
     ) -> Result<TexResult> {
         let _guard = super::ENGINE_LOCK.lock().unwrap(); // until we're thread-safe ...
 
         let caux = CString::new(aux)?;
 
         let mut state = ExecutionState::new(io, events, status);
         let bridge = TectonicBridgeApi::new(&mut state);
+        let config = BibtexConfig {
+            min_crossrefs: unstables.min_crossrefs.unwrap_or(2),
+        };
 
         unsafe {
-            match super::bibtex_simple_main(&bridge, caux.as_ptr()) {
+            match super::bibtex_simple_main(&bridge, &config, caux.as_ptr()) {
                 0 => Ok(TexResult::Spotless),
                 1 => Ok(TexResult::Warnings),
                 2 => Ok(TexResult::Errors),

src/engines/mod.rs

@@ -496,6 +496,7 @@ extern "C" {
 
     fn dvipdfmx_simple_main(
         api: &TectonicBridgeApi,
+        config: &xdvipdfmx::XdvipdfmxConfig,
         dviname: *const libc::c_char,
         pdfname: *const libc::c_char,
         enable_compression: bool,
@@ -505,6 +506,7 @@ extern "C" {
 
     fn bibtex_simple_main(
         api: &TectonicBridgeApi,
+        config: &bibtex::BibtexConfig,
         aux_file_name: *const libc::c_char,
     ) -> libc::c_int;
 

src/engines/tex.rs

@@ -9,6 +9,7 @@ use super::{ExecutionState, IoEventBackend, TectonicBridgeApi};
 use crate::errors::{DefinitelySame, ErrorKind, Result};
 use crate::io::IoStack;
 use crate::status::StatusBackend;
+use crate::unstable_opts::UnstableOptions;
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum TexResult {
@@ -109,6 +110,7 @@ impl TexEngine {
         status: &mut dyn StatusBackend,
         format_file_name: &str,
         input_file_name: &str,
+        unstables: &UnstableOptions,
     ) -> Result<TexResult> {
         let _guard = super::ENGINE_LOCK.lock().unwrap(); // until we're thread-safe ...
 
@@ -119,6 +121,11 @@ impl TexEngine {
         let bridge = TectonicBridgeApi::new(&mut state);
 
         // initialize globals
+
+        let v = if unstables.shell_escape { 1 } else { 0 };
+        unsafe {
+            super::tt_xetex_set_int_variable(b"shell_escape_enabled\0".as_ptr() as _, v);
+        }
         let v = if self.halt_on_error { 1 } else { 0 };
         unsafe {
             super::tt_xetex_set_int_variable(b"halt_on_error_p\0".as_ptr() as _, v);

src/engines/xdvipdfmx.rs

@@ -9,6 +9,12 @@ use super::{ExecutionState, IoEventBackend, TectonicBridgeApi};
 use crate::errors::{ErrorKind, Result};
 use crate::io::IoStack;
 use crate::status::StatusBackend;
+use crate::unstable_opts::UnstableOptions;
+
+#[repr(C)]
+pub struct XdvipdfmxConfig {
+    paperspec: *const libc::c_char,
+}
 
 pub struct XdvipdfmxEngine {
     enable_compression: bool,
@@ -51,9 +57,29 @@ impl XdvipdfmxEngine {
         status: &mut dyn StatusBackend,
         dvi: &str,
         pdf: &str,
+        unstables: &UnstableOptions,
     ) -> Result<i32> {
         let _guard = super::ENGINE_LOCK.lock().unwrap(); // until we're thread-safe ...
 
+        // This conversion is probably way too complex, because we need to convert String to
+        // something which holds a CStr (which needs to be a local so it doesn't disappear). And
+        // all of this happens in an Option.
+
+        // Keep a local reference so the string doesn't get dropped too early
+        let paperspec_str = unstables
+            .paper_size
+            .as_ref()
+            .and_then(|s| CString::new(s.clone()).ok());
+
+        // We default to "letter" paper size by default
+        let paperspec_default = CStr::from_bytes_with_nul(b"letter\0").unwrap();
+
+        let config = XdvipdfmxConfig {
+            paperspec: paperspec_str
+                .as_ref()
+                .map_or(paperspec_default.as_ptr(), |s| s.as_ptr()),
+        };
+
         let cdvi = CString::new(dvi)?;
         let cpdf = CString::new(pdf)?;
 
@@ -63,6 +89,7 @@ impl XdvipdfmxEngine {
         unsafe {
             match super::dvipdfmx_simple_main(
                 &bridge,
+                &config,
                 cdvi.as_ptr(),
                 cpdf.as_ptr(),
                 self.enable_compression,

src/io/mod.rs

@@ -312,11 +312,7 @@ impl<T> OpenResult<T> {
 
     /// Returns true if this result is of the NotAvailable variant.
     pub fn is_not_available(&self) -> bool {
-        if let OpenResult::NotAvailable = *self {
-            true
-        } else {
-            false
-        }
+        matches!(*self, OpenResult::NotAvailable)
     }
 
     /// Convert this object into a plain Result, erroring if the item was not available.
@@ -471,7 +467,7 @@ pub trait Bundle: IoProvider {
             OpenResult::NotAvailable => {
                 // Broken or un-cacheable backend.
                 return Err(ErrorKind::Msg(
-                    "itar-format bundle does not provide needed SHA256SUM file".to_owned(),
+                    "bundle does not provide needed SHA256SUM file".to_owned(),
                 )
                 .into());
             }