Crate tectonic_bridge_core[][src]

Expand description

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.


A mechanism for launching bridged FFI code.

The CoreBridgeState structure is a handle to Rust state that can be used by C/C++ engine code to perform basic I/O functions.

A buffer for diagnostic messages. Rust code does not need to use this type.

An error type indicating the the FFI code aborted.

This type provides a minimal DriverHooks implementation.

A type for storing settings about potentially insecure engine features.


Different types of files that can be opened by TeX engines

Different high-level security stances that can be adopted when creating SecuritySettings.

Possible failures for “system request” calls to the driver.


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


Append text to a diagnostic.

Create a new diagnostic that will be reported as an error.

Create a new diagnostic that will be reported as a warning.

“Finish” a diagnostic: report it to the driver and free the diagnostic object.

Calculate the MD5 digest of a block of binary data.

Calculate the MD5 digest of a Tectonic file.

Get the filesystem path of the most-recently-opened input file.

Close a Tectonic input file.

Get the modification time of a Tectonic input file.

Get the size of a Tectonic input file.

Get a single character from a Tectonic input file.

Open a Tectonic file for input.

Open the “primary input” file.

Read data from a Tectonic input handle

Seek in a Tectonic input stream.

Put back a character that was obtained from a getc call.

Issue an error.

Issue a warning.

Close a Tectonic output file.

Flush pending writes to a Tectonic output file.

Open a Tectonic file for output.

Open the general user output stream as a Tectonic output file.

Write a single character to a Tectonic output file.

Write data to a Tectonic output file.

Run a shell command