ralismark / tectonic

A modernized, complete, self-contained TeX/LaTeX engine, powered by XeTeX and TeXLive.

Tectonic

Tectonic is a modernized, complete, self-contained TeX/LaTeX engine, powered by XeTeX and TeXLive.

Read this first

If you just want to compile TeX documents, you should probably click through to the main Tectonic website. This page is primarily aimed at folks interested in how Tectonic works “under the hood.”

Developer dashboard

• User website.
• Community discussion forum.
• Installation.
• Developer documentation, including build instructions.
• API documentation.
• Issues.
• Changelog.

Technical ecosystem

If you’re interested in Tectonic as a software tool, you might also want to check out:

• One of the following GitHub Actions
  • setup-tectonic, which lets you use tectonic directly in your workflows (supports caching + optionally biber)
  • compile-latex contributed by Vinay Sharma, which is powered by Tectonic.
• tt.ente.ninja, which runs Tectonic against a subset of the arxiv.org corpus à la the Rust tool Crater — a project by @Mrmaxmeier

The “reference sources”

Much of the core code of Tectonic is derived from XeTeX, and we strive to track and maintain compatibility with upstream as much as possible. However, the nature of the Tectonic project is such that its source code is going to diverge from that of XeTeX over time. We can do our best to track the semantics of changes to XeTeX, but the expression of those changes in source form may well change greatly over time.

In this repository, the Git submodule reference_sources links to the “staging repository” that tracks the XeTeX source code that we use as a reference. In particular, the version of the reference code in the submodule is the most recent code whose semantics are guaranteed to be expressed in Tectonic, to the best of our efforts. You don’t need to clone reference_sources to build Tectonic (which is good because everyone is always super confused by how Git submodules work!). It just provides a convenient way for Git to track the exact reference code that we are using at any given time.

Please see the tectonic-staging README for more information. (Or at least, more words on the topic.)

Cargo Features

The Tectonic build can be customized with the following Cargo features:

external-harfbuzz

By default, the Tectonic crates will build and link to a “vendored” (static, internal) version of the Harfbuzz text shaping library. If you would like to link to an externally-supplied version instead, enable this feature. The external library can be detected with either pkg-config or vcpkg. See the How To Build Tectonic guide for more details.

geturl-curl

Use the curl crate to implement HTTP requests. In order for this to take effect, you must use --no-default-features because geturl-reqwest is a default feature and it takes precedence.

geturl-reqwest (enabled by default)

Use the reqwest crate to implement HTTP requests. This is the default selection.

native-tls-vendored

If using reqwest, activate the vendored option in the native-tls crate, causing OpenSSL to be vendored. This can be useful when cross-compiling or building static binaries, but is discouraged because that means that the resulting binaries won't benefit from security fixes to system TLS libraries.

serialization (enabled by default)

This feature enables (de)serialization using the serde crate. At the moment, this is only used to read per-user configuration from a TOML file. If this feature is disabled, the per-user configuration file will be silently ignored. This feature is provided because serialization requires the serde_derive crate, which in turn uses Rust’s proc_macro feature. The proc_macro functionality is difficult to build with statically linked targets, although Tectonic’s CI system demonstrates how to make it work.