Struct tectonic_engine_xetex::TexEngine

pub struct TexEngine { /* private fields */ }

A struct for invoking the (Xe)TeX engine.

This struct has a fairly straightforward “builder” interface: you create it, apply any settings that you wish, and eventually run the process() method.

Due to constraints of the gnarly C/C++ code underlying the engine implementation, only one engine may run at once in one process. The engine execution framework uses a global mutex to ensure that this is the case. This restriction applies not only to the TexEngine type but to all Tectonic engines. I.e., you can’t run this engine and the BibTeX engine at the same time.

Implementations

impl TexEngine

pub fn halt_on_error_mode(&mut self, halt_on_error: bool) -> &mut Self

Configure whether the engine will halt on errors.

The default setting is true. If false, the engine will plunge on ahead in the face of all but the most catastrophic problems. It’s really quite impressive!

pub fn initex_mode(&mut self, initex: bool) -> &mut Self

Configure the engine to run in “initex” mode, in which it generates a “format” file that serializes the engine state rather than a PDF document. The default is false.

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

Configure the engine to produce SyncTeX data.

The default is false.

pub fn semantic_pagination(&mut self, enabled: bool) -> &mut Self

Configure the engine to use “semantic pagination”.

Important: this mode is essentially unimplemented.

The goal of this mode is to set up the engine to create HTML-friendly output by altering how paragraphs and pages are constructed. When this mode is activated, the engine output type changes from XDV to SPX (although the two formats are quite similar).

The default is false.

pub fn shell_escape(&mut self, shell_escape_enabled: bool) -> &mut Self

Configure whether the “shell escape” TeX feature is enabled.

The default is false.

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

Sets the date and time used by the TeX engine. This affects things like LaTeX’s \today command.

The default vaue is the Unix epoch, so you should almost always override this setting. If you are aiming to achieve reproducible builds, you will need a way to fix this parameter from one engine invocation to the next.

pub fn process( &mut self, launcher: &mut CoreBridgeLauncher<'_>, format_file_name: &str, input_file_name: &str ) -> Result<TexOutcome>

Process a document using the current engine configuration.

The launcher parameter gives overarching environmental context in which the engine will be run.

The format_file_name is the name for the TeX “format file” giving preloaded engine state. It must be findable in the I/O stack, using the special hooks that are provided for handing format files, which allow updates to the file format to be handed (see FORMAT_SERIAL). If in “initex” mode, this parameter will be ignored.

The input_file_name is used to name the “primary input file”. The I/O system has special hooks for opening this primary input, so be aware that this filename is not opened using the usual mechanisms. This setting affects some of the names used by the engine internally, including the name it uses to create its main output files. The traditional default value is "texput".

Trait Implementations

impl Debug for TexEngine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TexEngine

fn default() -> Self

Returns the “default value” for a type.