Struct tectonic::driver::ProcessingSessionBuilder

pub struct ProcessingSessionBuilder { /* private fields */ }

A builder-style interface for creating a ProcessingSession.

This uses standard builder patterns. The Default implementation defaults to restrictive security settings that disable all known-insecure features that could be abused by untrusted inputs. Use ProcessingSessionBuilder::new_with_security() in order to have the option to enable potentially-insecure features such as shell-escape.

Implementations

impl ProcessingSessionBuilder

pub fn new_with_security(security: SecuritySettings) -> Self

Create a new builder with customized security settings.

pub fn primary_input_path<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

Sets the path to the primary input file.

If a primary input path is not specified, we will default to reading it from stdin.

pub fn primary_input_buffer(&mut self, buf: &[u8]) -> &mut Self

Sets the primary input to be a caller-specified buffer.

If neither this nor a primary input path is specified, we will default to reading the primary input from stdin.

pub fn tex_input_name(&mut self, s: &str) -> &mut Self

Sets the name of the main input file.

This value will be used to infer the names of the output files; for example, if tex_input_name is set to "texput.tex" then the pdf output file will be "texput.pdf". As such, this parameter is mandatory, even if the real input is coming from stdin (if it is not provided, ProcessingSessionBuilder::create will panic).

pub fn filesystem_root<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

Set the directory that serves as the root for finding files on disk.

If unspecified, and there is a primary input file, the directory containing that file will serve as the filesystem root. Otherwise, it is set to the current directory.

pub fn output_dir<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

A path to the directory where output files should be created.

This will default to the directory containing primary_input_path, or the current working directory if the primary input is coming from stdin.

pub fn do_not_write_output_files(&mut self) -> &mut Self

Indicate that output files should not be written to disk.

By default, output files will be written to the directory containing primary_input_path, or the current working directory if the primary input is coming from stdin.

pub fn format_name(&mut self, p: &str) -> &mut Self

The name of the .fmt file used to initialize the TeX engine.

This file does not necessarily have to exist already; it will be created if it doesn’t. This parameter is mandatory (if it is not provided, ProcessingSessionBuilder::create will panic).

pub fn format_cache_path<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

Sets the path to the format file cache.

This is used to, well, cache format files, which are generated as needed from the backing bundle. Defaults to the same directory as the input file, or PWD if the input is a non-file (such as standard input).

pub fn output_format(&mut self, f: OutputFormat) -> &mut Self

The type of output to create.

pub fn makefile_output_path<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

If set, a makefile will be written out at the given path.

pub fn pass(&mut self, p: PassSetting) -> &mut Self

Which kind of pass should the ProcessingSession run? Defaults to PassSetting::Default (duh).

pub fn reruns(&mut self, r: usize) -> &mut Self

If set, and if the pass is set to PassSetting::Default, the TeX engine will be re-run exactly this many times.

If reruns is unset, we will auto-detect how many times the TeX engine needs to be re-run.

pub fn print_stdout(&mut self, p: bool) -> &mut Self

If set to true, stdout from the TeX engine will be forwarded to actual stdout. (By default, it will be suppressed.)

pub fn hide<P: AsRef<Path>>(&mut self, p: P) -> &mut Self

Marks a path as hidden, meaning that the TeX engine will pretend that it doesn’t exist in the filesystem.

pub fn bundle(&mut self, b: Box<dyn Bundle>) -> &mut Self

Sets the bundle, which the various engines will use for finding style files, font files, etc.

pub fn keep_intermediates(&mut self, k: bool) -> &mut Self

If set to true, various intermediate files will be written out to the filesystem.

pub fn keep_logs(&mut self, k: bool) -> &mut Self

If set to true, ‘.log’ and ‘.blg’ files will be written out to the filesystem.

pub fn synctex(&mut self, s: bool) -> &mut Self

If set to true, tex files will be compiled using synctex information.

pub fn build_date(&mut self, date: SystemTime) -> &mut Self

Sets the date and time of the processing session. See TexEngine::build_date for mor information.

pub fn build_date_from_env(&mut self, force_deterministic: bool) -> &mut Self

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_deterministic is set, we fall back to UNIX_EPOCH. Otherwise, we use the current system time.

pub fn unstables(&mut self, opts: UnstableOptions) -> &mut Self

Loads unstable options into the processing session

pub fn shell_escape_with_work_dir<P: AsRef<Path>>( &mut self, path: P ) -> &mut Self

Enable “shell escape” commands in the engines, and use the specified directory for shell-escape work. The caller is responsible for the creation and/or destruction of this directory. The default is to disable shell-escape unless the UnstableOptions say otherwise, in which case a driver-managed temporary directory will be used.

pub fn shell_escape_with_temp_dir(&mut self) -> &mut Self

Forcibly enable shell-escape mode with a temporary directory, overriding any UnstableOptions settings. The default is to disable shell-escape unless the UnstableOptions say otherwise, in which case a driver-managed temporary directory will be used.

pub fn shell_escape_disabled(&mut self) -> &mut Self

Forcibly disable shell-escape mode, overriding any UnstableOptions settings. The default is to disable shell-escape unless the UnstableOptions say otherwise, in which case a driver-managed temporary directory will be used.

pub fn html_assets_spec_path<S: ToString>(&mut self, path: S) -> &mut Self

When using HTML mode, emit an asset specification file instead of actual asset files.

“Assets” are files like fonts and images that accompany the HTML output generated during processing. By default, these are emitted during processing. If this method is called, the assets will not be created. Instead, an “asset specification” file will be emitted to the given output path. This specification file contains the information needed to generate the assets upon a later invocation. Asset specification files can be merged, allowing the results of multiple separate TeX compilations to be synthesized into one HTML output tree.

If the build does not use HTML mode, this setting has no effect.

pub fn html_precomputed_assets( &mut self, assets: AssetSpecification ) -> &mut Self

In HTML mode, use a precomputed asset specification.

“Assets” are files like fonts and images that accompany the HTML output generated during processing. By default, the engine gathers these during processing and emits them at the end. After this method is used, however, it will generate HTML outputs assuming the information given in the asset specification given here. If the input calls for new assets or different options inconsistent with the specification, processing will abort with an error.

The purpose of this mode is to allow for a unified set of assets to be created from multiple independent runs of the SPX-to-HTML stage. First, the different inputs should be processed independently, and their individual assets should saved. These should then be merged. Then the inputs should be reprocessed, all using the merged asset specification. In one — but only one — of these sessions, the assets should actually be emitted.

pub fn html_emit_files(&mut self, do_emit: bool) -> &mut Self

Set whether templated outputs should be created during HTML processing.

This mode can be useful if you want to analyze what would be created during HTML processing without actually creating the files.

pub fn html_emit_assets(&mut self, do_emit: bool) -> &mut Self

Set whether supporting asset files should be created during HTML processing.

This mode can be useful if you want to analyze what would be created during HTML processing without actually creating the files. If you call Self::html_assets_spec_path, this setting will ignored, and no assets will be emitted to disk.

pub fn create(self, status: &mut dyn StatusBackend) -> Result<ProcessingSession>

Creates a ProcessingSession.

Trait Implementations

impl Default for ProcessingSessionBuilder

fn default() -> ProcessingSessionBuilder

Returns the “default value” for a type.