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.

If you change the interfaces here, rerun cbindgen as described in the README!

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