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