Crate tectonic[−][src]

Expand description

Tectonic is a complete TeX/LaTeX engine converted into a standalone library. It is derived from the XeTeX variant of TeX and uses the support files packages by the TeX Live project. Tectonic would not be possible without the hard work that has gone into these projects.

Because Tectonic is based on the XeTeX engine, it can take advantage of the features of modern fonts (TrueType, OpenType, etc.), outputs directly to the PDF file format, and supports Unicode inputs. Tectonic differs from other TeX engines in the following ways:

Dependencies on environment variables and configuration files have been eliminated.
All I/O is routed through pluggable backends. Support data can be fetched from a single “bundle” file, and the engine’s (copious) output can be hidden or postprocessed.
The command-line frontend, tectonic, has a modernized user interface that never asks for user input.
The frontend is just a thin shim over the Tectonic Rust crate, so that the full engine can be embedded anywhere you can run Rust code.

As of version 0.5, this crate is more and more a “façade” for a set of sub-crates that combine to provide the Tectonic user experience. Those crates generally have APIs that are more carefully structured and better documented than this crate, which grew somewhat organically. The foundational crates are:

tectonic_errors for core error handing types.
tectonic_status_base for a basic user-facing status-reporting framework.
tectonic_io_base for the I/O abstraction framework.
tectonic_bridge_core for a framework to launch unsafe (C/C++) “engines” through FFI.

Building on these and other support crates of less general interest are the following major pieces of Tectonic’s functionality:

tectonic_engine_xetex for the XeTeX engine.
tectonic_engine_xdvipdfmx for the xdvipdfmx engine.
tectonic_engine_bibtex for the BibTeX engine.

The main module of this crate provides an all-in-wonder function for compiling LaTeX code to a PDF:

use tectonic;

let latex = r#"
\documentclass{article}
\begin{document}
Hello, world!
\end{document}
"#;

let pdf_data: Vec<u8> = tectonic::latex_to_pdf(latex).expect("processing failed");
println!("Output PDF size is {} bytes", pdf_data.len());

The driver module provides a high-level interface for driving the engines in more realistic circumstances.

Re-exports

`pub use crate::engines::bibtex::BibtexEngine;`
`pub use crate::engines::spx2html::Spx2HtmlEngine;`
`pub use crate::errors::Error;`
`pub use crate::errors::ErrorKind;`
`pub use crate::errors::Result;`

Modules

config	User configuration settings for the Tectonic engine.
digest	Compatibility re-exports of `tectonic_io_base::digest` types.
docmodel	Connecting the Tectonic document model to the engines.
driver	This module contains the high-level interface that ties together the various engines. The main struct is `ProcessingSession`, which knows how to run (and re-run if necessary) the various engines in the right order. Such a session can be created with a `ProcessingSessionBuilder`, which you might obtain from a `tectonic_docmodel::document::Document` using the `crate::docmodel::DocumentExt::setup_session` extension method, if you’re using the Tectonic document model.
engines	Access to Tectonic’s processing backends.
errors	Tectonic error types and support code.
io	Extensions to Tectonic’s pluggable I/O backend.
status	Compatibility reexports of tectonic_status_base types
unstable_opts	Unstable options for the Tectonic engine.

Macros

ctry	“Chained try” — like `try!`, but with the ability to add context to the error message.
errmsg	Use string formatting to create an `Error` of kind `errors::ErrorKind::Msg`.
tt_error	Report a formatted error message to the user.
tt_error_styled	Show formatted text to the user, styled as an error message.
tt_note	Report a formatted informational message to the user.
tt_warning	Report a formatted warning message to the user.

Structs

TexEngine	A struct for invoking the (Xe)TeX engine.
XdvipdfmxEngine	A struct for invoking the `xdvipdfmx` engine.

Enums

TexOutcome

A possible outcome from a (Xe)TeX engine invocation.

Constants

FORMAT_SERIAL

A serial number describing the detailed binary layout of the TeX “format files” used by this crate. This number will occasionally increment, indicating that the format file structure has changed. There is no provision for partial forwards or backwards compatibility: if the number changes, you need to regenerate your format files. If you’re generating format files, you should munge this serial number in the filename, or something along those lines, to make sure that when the engine is updated you don’t attempt to reuse old files.

Functions

latex_to_pdf

Compile LaTeX text to a PDF.