Crate tectonic_bridge_core

Core APIs for bridging the C and Rust portions of Tectonic’s processing backends.

This crate is used by the Tectonic “engines”, which are predominantly C/C++ code derived from the original TeX codebase. It provides a framework so that the C/C++ code can invoke the support services provided by Tectonic, such as its pluggable I/O backends. The interfaces exposed to the C/C++ layers are created by cbindgen.

In order to provide access to a C/C++ engine in Rust, you should create some kind of interface that expects to be given a reference to a CoreBridgeLauncher struct. You should use that struct’s with_global_lock method to obtain a CoreBridgeState reference, and then pass that reference across the FFI layer. On the other side of the FFI divide, your code must call the functions ttbc_global_engine_enter() and ttbc_global_engine_exit() according to the pattern described in tectonic_bridge_core.h. If an abort is detected, the callback function must return Err(EngineAbortedError::new_abort_indicator().into()). Unfortunately, this is the cleanest and most reliable API that we can provide because our abort handling uses setjmp/longjmp and those can’t cross FFI boundaries.

In order to use a C/C++ engine, you need to provide something that implements the DriverHooks trait. The MinimalDriver struct provides a minimal implementation that only requires you to provide an IoProvider implementation.

Structs

CoreBridgeLauncher	A mechanism for launching bridged FFI code.
CoreBridgeState	The CoreBridgeState structure is a handle to Rust state that can be used by C/C++ engine code to perform basic I/O functions.
Diagnostic	A buffer for diagnostic messages. Rust code does not need to use this type.
EngineAbortedError	An error type indicating the the FFI code aborted.
MinimalDriver	This type provides a minimal DriverHooks implementation.
SecuritySettings	A type for storing settings about potentially insecure engine features.

Enums

FileFormat	Different types of files that can be opened by TeX engines
SecurityStance	Different high-level security stances that can be adopted when creating SecuritySettings.
SystemRequestError	Possible failures for “system request” calls to the driver.

Traits

DriverHooks

The DriverHooks trait allows engines to interact with the higher-level code that is driving the TeX processing.

Functions

ttbc_diag_append⚠	Append text to a diagnostic.
ttbc_diag_begin_error	Create a new diagnostic that will be reported as an error.
ttbc_diag_begin_warning	Create a new diagnostic that will be reported as a warning.
ttbc_diag_finish	“Finish” a diagnostic: report it to the driver and free the diagnostic object.
ttbc_get_data_md5⚠	Calculate the MD5 digest of a block of binary data.
ttbc_get_file_md5⚠	Calculate the MD5 digest of a Tectonic file.
ttbc_get_last_input_abspath⚠	Get the filesystem path of the most-recently-opened input file.
ttbc_input_close	Close a Tectonic input file.
ttbc_input_get_mtime	Get the modification time of a Tectonic input file.
ttbc_input_get_size	Get the size of a Tectonic input file.
ttbc_input_getc	Get a single character from a Tectonic input file.
ttbc_input_open⚠	Open a Tectonic file for input.
ttbc_input_open_primary	Open the “primary input” file.
ttbc_input_read⚠	Read data from a Tectonic input handle
ttbc_input_seek⚠	Seek in a Tectonic input stream.
ttbc_input_ungetc	Put back a character that was obtained from a getc call.
ttbc_issue_error⚠	Issue an error.
ttbc_issue_warning⚠	Issue a warning.
ttbc_output_close	Close a Tectonic output file.
ttbc_output_flush	Flush pending writes to a Tectonic output file.
ttbc_output_open⚠	Open a Tectonic file for output.
ttbc_output_open_stdout	Open the general user output stream as a Tectonic output file.
ttbc_output_putc	Write a single character to a Tectonic output file.
ttbc_output_write⚠	Write data to a Tectonic output file.
ttbc_shell_escape⚠	Run a shell command