Src/Howto/Build Tectonic/Bundle Default Config

How To: Build Tectonic: Configure the Default Bundle

Tectonic supports overriding the default bundle configuration at build time through environment variables. This feature is particularly useful for:

- System packagers who need to specify bundle sources during compilation
- Environments requiring reproducible builds
- Users who want to use mirrored bundles for better reliability

Build-time Environment Variables for the Default Bundle

Two environment variables control the bundle configuration:

`TECTONIC_BUNDLE_PREFIX`

This variable is required at compile time and specifies the base URL prefix for bundles.
A default value is provided in the build script crates/bundles/build.rs in the source repository.

The variable is used to construct bundle URLs in the following pattern:

bash

$TECTONIC_BUNDLE_PREFIX/default_bundle_v$FORMAT_VERSION.tar

where $FORMAT_VERSION is a suffix from an internal variable, used to distinguish different versions
of the bundle's format for backward compatibility.

For example, the current default is given by:

bash

as of January 2025

TECTONIC_BUNDLE_PREFIX=https://relay.fullyjustified.net

so the full bundle URL is https://relay.fullyjustified.net/default_bundle_v33.tar,
in which _v33 indicates the version of the bundle format.
Note that this hardcoded default may change, and the default value documented here may be outdated.
Please refer to the source code of Tectonic for the latest default.

`TECTONIC_BUNDLE_LOCKED`

This variable is optional and, when set, provides a fixed URL for the bundle. If this variable contains any non-empty value, it takes precedence over the format-version-specific URL construction using TECTONIC_BUNDLE_PREFIX.

Usage Examples

To build Tectonic with a custom bundle prefix:

TECTONIC_BUNDLE_PREFIX="https://mirror.example.com/tectonic-bundles" cargo build

To build Tectonic with a locked bundle URL:

TECTONIC_BUNDLE_LOCKED="https://mirror.example.com/tectonic-bundles/my-fixed-bundle.tar" cargo build

Notes

- The bundle URL configuration happens at build time and may be overridden by appropriate --bundle flags at runtime.
- If using TECTONIC_BUNDLE_LOCKED, ensure the URL points to a compatible bundle version.

---

Src/Howto/Build Tectonic/Cargo Vcpkg Dep Install

How To: Build Tectonic: Install Dependencies With cargo-vcpkg

A convenient, fairly cross-platform way to install Tectonic’s dependencies is
using the [cargo-vcpkg] tool. It will take care of setting up [vcpkg], providing
the needed dependencies, and informing Tectonic’s build system about how to find
them. It will, however, generally require that the dependencies be compiled from
scratch.

[cargo-vcpkg]: https://crates.io/crates/cargo-vcpkg
[vcpkg]: https://vcpkg.readthedocs.io/

First, install [cargo-vcpkg] if needed:

cargo install cargo-vcpkg

Then, in the Tectonic source tree, run the command to obtain all of the needed
dependencies:

cargo vcpkg build

Then set the VCPKG_ROOT environment variable to tell the build system where
the dependencies may be found. In a [bash] shell, a good command is:

export VCPKG_ROOT="${CARGO_TARGET_DIR:-$(pwd)/target}/vcpkg"

[bash]: https://www.gnu.org/software/bash/

If you’re building on Windows, you’ll likely want to make sure that your
[RUSTFLAGS] variable includes a +crt-static [target feature] and set the
VCPKGRS_TRIPLET variable to x64-windows-static-release. This is a custom
[vcpkg triplet] provided by Tectonic’s build system (in the directory
dist/vcpkg-triplets) that is automatically activated by its [cargo-vcpkg]
integration. If you don’t use [cargo-vcpkg], the default triplet is
x64-windows-static if the +crt-static feature is activated, or
x64-windows-static-md if it is not.

If you’ve done the full vcpkg install, you might as well build with [an external
Harfbuzz][external-harfbuzz]. Therefore a full Windows build invocation —
launched from bash — might look like this:

[RUSTFLAGS]: https://doc.rust-lang.org/cargo/reference/environment-variables.html
[target feature]: https://rust-lang.github.io/packed_simd/perf-guide/target-feature/rustflags.html
[vcpkg triplet]: https://vcpkg.readthedocs.io/en/latest/users/triplets/
[external-harfbuzz]: ./index.md#choose-cargo-features

cargo vcpkg build
export VCPKG_ROOT="${CARGO_TARGET_DIR:-$(pwd)/target}/vcpkg"
export RUSTFLAGS='-Ctarget-feature=+crt-static'  # Windows only
export VCPKGRS_TRIPLET='x64-windows-static-release'  # Windows only
export TECTONIC_DEP_BACKEND=vcpkg
cargo build --features external-harfbuzz

Note that if you are going to run additional commands such as cargo test,
you’re going to need to ensure that the same environment variables *and feature
flags* are used consistently.

---

Src/Howto/Build Tectonic/External Dep Install

How To: Build Tectonic: Install System Dependencies

Here are quick commands to install Tectonic’s dependencies using various package
managers:

- Debian and Ubuntu Linux and related variants
- RHEL, CentOS, and Fedora Linux and related variants
- Homebrew on macOS
- conda on various operating systems
- vcpkg on various operating systems (including Windows)

If none of these fit your needs, you’ll need to figure out the right packages
for your particular setup. Tectonic requires the following libraries:

- fontconfig (except on macOS)
- freetype2
- graphite2
- harfbuzz
- ICU4C
- libpng
- zlib
- Whichever SSL library is required for your system by the [rust-native-tls]
crate: probably OpenSSL

[rust-native-tls]: https://github.com/sfackler/rust-native-tls/#readme

Debian and Ubuntu Linux

Install Tectonic’s dependencies with:

sudo apt-get install \
  libfontconfig1-dev libgraphite2-dev libharfbuzz-dev libicu-dev libssl-dev zlib1g-dev

RHEL, CentOS, and Fedora Linux

Install Tectonic’s dependencies with:

sudo dnf install \
  gcc-c++ fontconfig-devel graphite2-devel harfbuzz-devel libicu-devel openssl-devel zlib-devel

Homebrew on macOS

If you use [Homebrew], be aware that you can install Tectonic with it directly!

[Homebrew]: https://brew.sh

brew install tectonic

If you want to compile Tectonic yourself, the following command will install the
dependencies:

brew install --only-dependencies tectonic

You will also need to make sure that your environment has [pkg-config] set up to
find the Homebrew libraries correctly.

[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/

Conda

If you use [Conda], be aware that you can install Tectonic with it directly,
using the [conda-forge] channel!

[Conda]: https://docs.conda.io/
[conda-forge]: https://conda-forge.org/

conda install -c conda-forge tectonic

But if you want to compile Tectonic yourself, the following command will install
the dependencies:

conda install fontconfig freetype graphite2 harfbuzz icu libpng openssl zlib

You will also need to make sure that your environment has [pkg-config] set up to
find the Conda libraries correctly.

vcpkg

If you wish to use [vcpkg] to provide Tectonic’s build dependencies, we
recommend that you use the cargo-vcpkg tool. But
for the record, to install Tectonic’s dependencies through vcpkg directly, you
should probably run:

[vcpkg]: https://vcpkg.readthedocs.io/

vcpkg install fontconfig freetype "harfbuzz[graphite2]" icu

---

Src/Howto/Build Tectonic/Index

How To: Build Tectonic

This document lays out the options available for building the Tectonic [Rust
crate][rust-crate] and/or [executable] from source code. Because Tectonic relies
on a large number of system libraries and tightly-integrated C/C++ code, it can
be more challenging to compile than most Rust code.

[rust-crate]: https://doc.rust-lang.org/rust-by-example/crates.html
[executable]: https://en.wikipedia.org/wiki/Executable

For this reason, if you just want to run Tectonic, we recommend that you start
by [installing][install] a pre-built version if possible. Using a pre-compiled
binary will save you time and, possibly, headaches.

[install]: ../installation/index.md

Basic Prerequisites

To build Tectonic you will need Rust, C, and C++ compilers installed. It is
beyond the scope of this document to give instructions on this topic, besides
pointing you to the Rust installation
page.

You do not necessarily need to download a copy of the Tectonic source code, if
the [cargo install] command will meet your needs.

[cargo install]: https://doc.rust-lang.org/cargo/commands/cargo-install.html

Third-Party Dependencies

Tectonic relies on a number of well-established third-party libraries that deal
with fonts, Unicode, text shaping, and so on. Specifically:

- fontconfig for discovering system fonts (except on
macOS)
- freetype2 for parsing font files
- graphite2 for shaping certain unusual scripts
- Harfbuzz for text shaping
- ICU4C for Unicode data and algorithms
- libpng for parsing PNG images
- OpenSSL for HTTPS if you’re not on a Mac or
Windows machine (or whichever SSL library is required for your system by the
[rust-native-tls] crate)
- zlib for compression algorithms

[Harfbuzz]: https://harfbuzz.github.io/
[rust-native-tls]: https://github.com/sfackler/rust-native-tls/#readme

To build Tectonic, your first task is to decide where you want these library
dependencies to come from.

- Tectonic can provide some dependencies internally ("vendor" them). This is
the default for [Harfbuzz]. You can use [Cargo features][cargo-features],
described below, to control when this happens. For some third-party libraries
needed by Tectonic, vendoring is not possible.
- You can install the dependencies externally, with a system such as your
OS’s package manager, and tell the Tectonic build system how to access them.
Read [how to install Tectonic’s dependencies externally][external-dep-install]
for quick recipes as to how to do that.
- As an intermediate approach, you can use cargo-vcpkg to compile the
dependencies for Tectonic’s use with [vcpkg]. Read [this
page][cargo-vcpkg-dep-install] to learn how to do that.

[external-dep-install]: ./external-dep-install.md
[vcpkg]: https://vcpkg.readthedocs.io
[cargo-vcpkg-dep-install]: ./cargo-vcpkg-dep-install.md

You’ll have to set up one of two ways for the Tectonic build system to gather
the appropriate information about how to compile against the external
dependencies:

- [pkg-config], the default system, is the appropriate choice in most cases.
Generally all you need to do is make sure that the pkg-config program is
installed using the same framework as you used to install the library
dependencies. You can force the Tectonic build system to use pkg-config for
dependency discovery by setting the environment variable
TECTONIC_DEP_BACKEND to the value pkg-config.
- [vcpkg] is the choice to use if you installed your dependencies this way,
either [using cargo-vcpkg][cargo-vcpkg-dep-install] or separately. Activate
this mode by setting the environment variable TECTONIC_DEP_BACKEND to the
value vcpkg.

[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/

If using [pkg-config], setting the environment variable
TECTONIC_PKGCONFIG_FORCE_SEMI_STATIC will cause the build system to attempt to
link with external libraries statically rather than dynamically. System
libraries, such as libc and libm on Unix systems, will still be linked
dynamically. This mode is planned to be superseded by better support for
"vendoring" dependent libraries.

Choose Cargo Features

The Cargo build framework offers the concept of [features][cargo-features] to
control build options. Tectonic offers the following features:

[cargo-features]: https://doc.rust-lang.org/cargo/reference/features.html

- 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.
- geturl-curl. Uses the [curl] crate to get URLs. In order for this to
take effect, you must use --no-default-features, because geturl-reqwest is
a default feature and takes precedence.
- geturl-reqwest (enabled by default). Uses the [reqwest] crate to get
URLs. This is a good portable default.
- 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.

[curl]: https://docs.rs/curl/
[reqwest]: https://docs.rs/reqwest/
[native-tls]: https://github.com/sfackler/rust-native-tls

Some lesser-used features are:

- serialization (enabled by default). Disabling this feature turns off all
Tectonic features that require the [serde] crate. This option is provided
because Tectonic’s use of serde requires [procedural macro][proc-macro]
support, which is not available by default on static-only compilation
environments. However, it is likely that serialization support will become
mandatory in the future, and one can still produce static tectonic
executables using a cross-compilation approach. Therefore we do not recommend
that you rely on this feature.
- profile. Compile Tectonic code in such a way as to make it profileable.
In particular, this forces the C/C++ compiler to include frame pointer
information unless it is known that such information is not needed for
profiling on the target platform.

[serde]: https://crates.io/crates/serde
[proc-macro]: https://doc.rust-lang.org/reference/procedural-macros.html

To avoid activating a feature that is enabled by default, you must pass the
--no-default-features flag to the cargo command that you run. Features are
enabled with a flag such as --features "serialization profile".

Compile the Code

To build the latest released version of Tectonic without needing to download its
source code, first *ensure that your build environment variables are set up
properly* and determine what feature flags you need. Then run:

cargo install tectonic

inserting any feature flags after the install. To install the latest version
from Git, do the same but use:

cargo install --git https://github.com/tectonic-typesetting/tectonic.git

Many other variations are possible. See the [cargo install] documentation for
more.

If you have downloaded its source code (perhaps because you wish to make your
own improvements), make sure that you’re inside the Tectonic source tree and run:

cargo build

once again adding any feature flags and ensuring that any necessary build
environment variables are set up properly. Read [The Cargo Book][cargo-book] for
vastly more information about where you can go from there.

[cargo-book]: https://doc.rust-lang.org/cargo/index.html

---

Src/Howto/Auctex Setup/Index

How To: Use Tectonic with AucTeX

This section is a guide aimed at GNU
Emacs users for setting up
AucTeX with Tectonic as the TeX/LaTeX
distribution.

Basic Prerequisites

To follow this section you will need Tectonic and GNU Emacs installed on your
system. Additionally, you will require the AucTeX emacs package to be installed
before following along.

Note: This section makes use of the V2 tectonic CLI,

invoked using the tectonic -X flag or nextonic command alias.

Setup

All the code displayed in this section should go into your init.el file (or
equivalent, such as config.el if you are using
Doomemacs).

First, load the AucTeX package.

lisp

(require 'latex)

You will need to set the default TeX engine AucTeX uses to figure out the build
commands to use Tectonic instead of traditional TeX distributions. Therefore we
have to modify the TeX-engine-alist variable.
* The first element of the list is the symbol that AucTeX recognizes.
* The second element is a string with the name of the TeX distribution.
* The third element is the shell command for compiling plain TeX documents.
* The fourth element is the shell command for compiling LaTeX documents. Here we
are assuming the user is using a Tectonic project (generated using tectonic -X new <proj-name>).
* The last element is the shell command for compiling ConTeXt documents, left
unconfigured for now.

lisp

(setq TeX-engine-alist '((default
                          "Tectonic"
                          "tectonic -X compile -f plain %T"
                          "tectonic -X watch"
                          nil)))

Next, modify the LaTeX-command-style so that AucTex doesn’t add extra options
to it that Tectonic does not recognize. We simply set it to the %(latex)
expansion (from TeX-expand-list-builtin), removing any other extra options.

lisp

(setq LaTeX-command-style '(("" "%(latex)")))

We need to set the TeX-check-TeX variable to nil since AucTeX will try to
find a traditional distribution like TeXLive or others, and will fail since
Tectonic doesn’t meet its criteria.

Additionally, we should also set TeX-process-asynchronous to t, so that
running Tectonic in watch mode doesn’t hang up Emacs.

We’ll also just ensure that the TeX-engine is set to default.

lisp

(setq TeX-process-asynchronous t
      TeX-check-TeX nil
      TeX-engine 'default)

Finally, modify the TeX-command-list to use the appropriate commands and not
pass in extra metadata and options to Tectonic that cause it to error out. This
needs to be done in place.

lisp

(let ((tex-list (assoc "TeX" TeX-command-list))
      (latex-list (assoc "LaTeX" TeX-command-list)))
  (setf (cadr tex-list) "%(tex)"
        (cadr latex-list) "%l"))

And that is all! You should now be able to
1. Compile plain TeX files.
2. Build Tectonic LaTeX projects in watch mode.

Additional Configuration and Usage Suggestions

Compile LaTeX outside a Tectonic project

To do this, you can simply invoke M-x TeX-command-master and select the
Other option, passing in the compile command tectonic -X compile -f latex <name of file>.

Caution: Compiling a document with multiple LaTeX files in this manner

isn’t extensively tested, as using a Tectonic project is the better way in

that case. Any bug reports are welcome.

Live PDF Preview in Tectonic projects

AucTeX expects the output PDF after compiling to be in the same directory as the
input file. So it will error out when that is not the case, since Tectonic
places the output in a build directory.

This behavior can be controlled by using the TeX-output-dir variable on a per
project basis.

This configuration assumes you are using project.el, although porting this
code to projectile.el should be trivial.

lisp

(add-hook 'after-change-major-mode-hook
          (lambda ()
            (when-let ((project (project-current))
                       (proot (project-root project)))
              (when (file-exists-p (expand-file-name "Tectonic.toml" proot))
                (setq-local TeX-output-dir (expand-file-name "build/index" proot))))))

We are basically looking for Tectonic.toml file in the project root, and if it
exists, setting the TeX-output-dir to the appropriate path to the build
directory. You may replace the "build/index" path with wherever your PDF file
is placed after it is generated by Tectonic.

---

Src/Getting Started/First Document

Getting Started: Build Your First Document

Now that [you’ve installed Tectonic][install], let’s create and build your first
[document].

[install]: ./install.md
[document]: ../ref/documents.md

Important: *From here on out, this [Getting Started][gs-index] guide will
use what we call the ["V2" interface][v2cli] to the Tectonic program. The V2
interface coexists with, but has a fairly different approach than, the ["V1"
interface][v1cli]. We are gradually migrating from V1 to V2. Neither interface
(V1 or V2) is the same as the one exposed by classic TeX tools such as
pdflatex.*

[gs-index]: ./index.md
[v2cli]: ../ref/v2cli.md
[v1cli]: ../ref/v1cli.md

Create a new document

The Tectonic [V2 interface][v2cli] has a "multitool" structure similar to that
of other powerful tools such as [git] and [cargo]. To create a new document, we
use a [new][cli-new] subcommand that looks like this:

tectonic -X new myfirstdoc

[git]: https://git-scm.com/
[cargo]: https://doc.rust-lang.org/cargo/
[cli-new]: ../v2cli/new.md

This will create a new [Tectonic workspace][workspace] directory named
myfirstdoc containing a file Tectonic.toml and a sub-directory named src.
Enter this new directory in your command prompt.

[workspace]: ../ref/workspaces.md

cd myfirstdoc

Note: *The -X flag activates the V2 interface. Don’t forget it! Eventually
it will become unnecessary and you’ll just be able to write tectonic new, but
that changeover hasn’t happened yet.*

If you’ve got an existing TeX file, you can process it in one-off fashion with:

tectonic -X compile myfile.tex

See [the tectonic -X compile documentation][cli-compile] for all of the options.

[cli-compile]: ../v2cli/compile.md

Building your document

To compile your document, run:

tectonic -X build

If you haven’t run Tectonic on your computer before, this command will take a
minute or two as it downloads the support files that it needs and generates the
LaTeX "format file" storing the default macro collection. Tectonic will cache
these files and avoid downloading them again. Test it out by running the build
again:

tectonic -X build

This time the command should finish much more quickly, with no messages about
downloading files. The output PDF document will be placed at the path
build/default/default.pdf relative to your document directory:

ls -l build/default/

If you’re familiar with traditional TeX engines, you’ll have noticed that
Tectonic’s "user experience" is substantially different from those engines:

1. Tectonic doesn’t print out the usual chatter — unless there’s an error.
2. Tectonic automatically reruns the TeX stage until its output stabilizes.
3. By default, Tectonic doesn’t write out intermediate files such as
(texput.aux, texput.log).
4. You ought not have seen this yet, but if you make a mistake in your TeX,
Tectonic will quit with an error message, rather than asking you to type X2
or whatever.

We hope that you’ll agree that these changes make for a program that is much
more pleasant to use than the traditional tools.

Cache

The location of the cache depends on your operating system. You can use the
[V2 Interface][v2cli-ref] to find the exact cache location on your machine
or take a look [at the implementation][user-cache-impl].

If you need to change the location of the cache, you can do that by setting
the environment variable TECTONIC_CACHE_DIR to the path of a directory.
We recommend leaving the cache location at the default unless there is a
compelling reason to change it.

[v2cli-ref]: ../ref/v2cli.md
[user-cache-impl]: https://docs.rs/tectonic_io_base/latest/tectonic_io_base/app_dirs/fn.ensure_user_cache_dir.html

---

Src/Getting Started/Index

Getting Started

This chapter of the book will introduce you to Tectonic, with a special emphasis
on the ways that it’s different from the TeX systems that you might have seen
before. We’ll assume a very basic familiarity with TeX and LaTeX, and that you
know how to use a command-line interface on your computer.

The sections in this chapter are:

1. Install Tectonic
2. Build your first document
3. Use a Unicode font

---

Src/Getting Started/Install

Getting Started: Install Tectonic

Let’s start out by making sure that Tectonic is installed on your system.

Even this step will be very different than what you might be used to with other
TeX systems. To install a normal TeX system such as [TeXLive], you normally need
to download gigabytes of support files and set them up in a complex directory
hierarchy. Tectonic, on the other hand, is distributed as a single executable
file. That one file not only combines the functionality of many standard TeX
programs, but it also can download the many necessary support files on the fly.
This makes Tectonic super easy to install.

[TeXLive]: https://www.tug.org/texlive/acquire-netinstall.html

The quickest way to get started is to use your terminal. On a computer running a
Unix-like operating system, including macOS, just run the following command in
your terminal:

curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net |sh

This will download the tectonic program and place it into the directory where
you ran the command.

On Windows, copy-paste this into a PowerShell window, which will unpack
tectonic.exe for you:

ps1

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://drop-ps1.fullyjustified.net'))

No matter your operating system, you should move the unpacked file into a
directory in your executable search path so that you can run Tectonic from any
working directory. For the time being, the download script doesn’t do this
because it can be tricky to automatically determine what the best installation
destination would be.

Alternatively, you can [install a packaged version of Tectonic][inst-packaged]
if one is available. For detailed instructions and additional installation
options, go to the [How To Install Tectonic][inst-ref] guide.

[inst-packaged]: ../installation/index.md#pre-built-binary-packages
[inst-ref]: ../installation/index.md

You’ll know that you’re set up when you can go to your computer’s command prompt
and run:

tectonic --help

and the result is that you get a printout of information about different options
and arguments that you can pass to the Tectonic program. (From now on we’ll use
a convention of a leading $ to indicate a command that you should run at your
computer’s command prompt. You don’t type the dollar sign itself.)

To be explicit, *Tectonic does not invoke an external latex program, and
Tectonic is not a "wrapper" for (La)TeX. Tectonic is* the LaTeX program. This
is essential. [The goals of the Tectonic project][goals] involve a fundamental
transformation of how we use TeX to create technical documents, and it is not
possible to achieve that without radical surgery to the heart of how TeX has
traditionally operated.

[goals]: ../introduction/index.md#the-goals-of-tectonic

---

Src/Getting Started/Unicode

Getting Started: Use a Unicode Font

You’ve [created your first Tectonic document][first-document]. Great! Now, let’s
start exploring the ways in which Tectonic helps you create modern [technical
documents][tech-docs].

[first-document]: ./first-document.md
[tech-docs]: ../introduction/index.md#technical-documents

We’ve already seen a few ways that Tectonic differs from traditional TeX
engines. Perhaps the most fundamentally important difference, however, is the
one that we’ll explore in this section.

Note: *This [Getting Started][gs-index] guide uses what we call the ["V2"
interface][v2cli] to the Tectonic command-line tool. The V2 interface coexists
with, but has a fairly different approach than, the ["V1"interface][v1cli]. We
are gradually migrating from V1 to V2. Neither interface (V1 or V2) is the same
as the one exposed by classic TeX tools such as pdflatex.*

[gs-index]: ./index.md
[v2cli]: ../ref/v2cli.md
[v1cli]: ../ref/v1cli.md

Unicode

When TeX was first developed [more than 40 years ago][tex-history], digital
systems for representing human writing were pretty primitive. Because TeX needed
to represent a variety of languages and mathematics, it was endowed with
comparatively sophisticated tools to both accept and emit characters that aren’t
found in standard English. TeX’s good multi-lingual support was one of the
things that made it groundbreaking. Eventually, however, a consortium of major
technology companies developed the much more comprehensive [Unicode] standards
for representing the world’s writing systems digitally. By now, they’re
universally adopted. So while the TeX ecosystem started out ahead of the curve,
some of its core systems are designed around an incompatible and, frankly,
dead-end framework.

[tex-history]: https://en.wikipedia.org/wiki/TeX#History
[Unicode]: https://home.unicode.org/

That is not to imply that the whole TeX universe is stuck in the past! Many
people have worked extremely hard to bridge the worlds of TeX and Unicode. The
code in Tectonic, in particular, is based on [XeTeX], which adds Unicode support
to the classic TeX experience. Without the efforts of the [XeTeX] team and many
other dedicated volunteers in the TeX world, Tectonic wouldn’t be able to offer
Unicode support.

[XeTeX]: http://xetex.sourceforge.net/

Modern Fonts

Tectonic’s support for Unicode allows it to take advantage of modern fonts that
are distributed using formats such as [OpenType]. Besides opening up access to a
whole world of typographic progress — a good font is the result of years of
expert effort — this support positions Tectonic to create outputs in not just
[PDF] but [HTML] formats. HTML capability is still under development, but it’s
one of the prime reasons that the Tectonic project was started.

[OpenType]: https://en.wikipedia.org/wiki/OpenType
[PDF]: https://en.wikipedia.org/wiki/PDF
[HTML]: https://en.wikipedia.org/wiki/HTML

The choice of fonts is foundational to TeX’s document processing, so modern
fonts aren’t automatically activated. To start using a nice new font like [TeX
Gyre Pagella][pagella] (derived from [Palatino]), edit your
src/_preamble.tex file and add the following lines after the \documentclass
command:

[pagella]: https://www.fontsquirrel.com/fonts/tex-gyre-pagella
[Palatino]: https://en.wikipedia.org/wiki/Palatino

tex

\usepackage{fontspec}
\setmainfont{texgyrepagella}[
  Extension = .otf,
  UprightFont = *-regular,
  BoldFont = *-bold,
  ItalicFont = *-italic,
  BoldItalicFont = *-bolditalic,
]

Now rebuild your document:

tectonic -X build

You’ll probably see Tectonic download some files: namely, the new font files
that you have started using. Tectonic’s ability to fetch such files on the fly
is why its installation is so much easier than a traditional TeX engine.

If you open up your rebuilt document, it will be using your new font, although
the difference can be difficult to detect with such a small amount of sample
text.

Unicode Input Text

Tectonic’s support for Unicode broadens its output capabilities through the
use of modern fonts. But that’s not all: Unicode also broadens the inputs
that Tectonic accepts.

With Tectonic, you can type non-English characters directly into your input TeX
files, which are parsed assuming the virtually-universal [UTF-8 Unicode text
encoding][utf8]. For instance, you can open up your src/index.tex file and
copy-paste in the following [verse][bateau] with accented characters:

tex

Ô que ma quille éclate! Ô que j’aille à la mer!

[utf8]: https://en.wikipedia.org/wiki/UTF-8
[bateau]: https://en.wikipedia.org/wiki/Le_Bateau_ivre

Rebuild your document and see your new text in the output:

tectonic -X build

Whatever, you might say. *I know how to get these accented characters with TeX
commands:*

tex

\^O que ma quille \'eclate! \^O que j'aille \a la mer!

Fair enough. But now try typing in [Bashô’s "old pond" haiku][old-pond]:

tex

古池や蛙飛び込む水の音
  ふるいけやかわずとびこむみずのおと

We’ll wait.

[old-pond]: https://www.japantimes.co.jp/news/2019/10/19/national/history/frog-jump-bashos-pond/

(Note, however, that if you copy-paste this text into our sample document, it won’t work: you haven’t activated a font able to handle the Japanese characters. You’ll get a lot of warnings to that effect.)

---

`Src/Installation/Index`

`How To: Install Tectonic`

One of the big advantages that Tectonic offers compared to the traditional TeX stack is that all of Tectonic’s functionality is delivered in a single executable file — not the usual tree of thousands of interlocking data files and binary tools.

You have several options for obtaining the Tectonic executable. The best choice depends on your computing environment and your needs.

- For the fastest and easiest installation, copy-paste a command into your terminal that will automatically download the right Tectonic program for your computer - Direct download a Tectonic release - Pre-built binary packages for your favorite operating system or package manager - Compile it yourself

The copy-paste method should cover most use cases, but if you want better integration with your operating system or computing environment, packaged versions might make more sense. There should be no need to compile Tectonic yourself unless you want to, or you’re hoping to run it on an unusual platform.

`Copy-paste a terminal command`

This is generally the easiest way to get Tectonic onto your computer. On a computer running a Unix-like operating system, including macOS, just run the following command in your terminal:

sh

curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net |sh

This will download the tectonicprogram and place it into the directory where you ran the command.

On Windows, you can do the same in a PowerShell window, which will unpacktectonic.exe for you:

ps1

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://drop-ps1.fullyjustified.net'))

No matter your operating system, you should probably move the unpacked file into a directory in your executable search path so that you can run Tectonic from any working directory. For the time being, the download script doesn’t do this because it can be tricky to automatically determine what the best installation destination would be.

`Direct download`

You can [download the latest release of Tectonic here][gh-latest] on GitHub. Each release is published with precompiled executables attached. Because Tectonic is distributed as a single executable, all you need to do is download the appropriate archive for your platform and unpack it.

[gh-latest]: https://tectonic-typesetting.github.io/latest.html

For instance, on most Linux systems, you’ll want to download the file with the name looking liketectonic-<VERSION>-x86_64-unknown-linux-gnu.tar.gz. This tarball will unpack to a single file,tectonic, which is the Tectonic executable.

`Pre-built binary packages`

Tectonic may be available in precompiled packages offered by either your operating system or standalone package managers. Check out [the Tectonic source repository][repo] for an up-to-date listing.

[repo]: https://github.com/tectonic-typesetting/tectonic/#readme

In most cases, the package name will be tectonicand will provide a command-line tool also namedtectonic.

`Pre-built packages for (Ana)conda`

Tectonic is available for the [Conda package manager][conda], which has the advantages of (1) not requiring any administrator privileges and (2) supporting Windows, macOS, and Linux. If you’d like to install Tectonic using a package manager and you’re not aware of a different option that’s a better fit for your needs, we recommend using Conda.

[conda]: https://docs.conda.io/

If you don’t already have Conda installed, we recommend that you [install the "Miniconda" package][miniconda] provided by [Anaconda, Inc.][anaconda]. Once complete, the commandconda will now be available in your terminal.

[miniconda]: https://docs.conda.io/en/latest/miniconda.html [anaconda]: https://www.anaconda.com/

Once the condacommand is available, you can install Tectonic and its support libraries using conda-forge, a community-led Conda packaging project. To install Tectonic you must activate conda-forge, which can be done temporarily like so:

sh

conda install -c conda-forge tectonic

`Arch Linux`

For users of [Arch Linux], there are two Tectonic packages available: [tectonic][arch-tectonic] from the official repositories, which can be installed with

sh

sudo pacman -S tectonic


and [tectonic-git][arch-tectonic-git] from the [AUR].
[Arch Linux]: https://archlinux.org/
[arch-tectonic]: https://archlinux.org/packages/extra/x86_64/tectonic/
[AUR]: https://aur.archlinux.org/
[arch-tectonic-git]: https://aur.archlinux.org/packages/tectonic-git
Homebrew

There is a tectonicpackage in Homebrew. If you already have Homebrew installed, installing Tectonic should be as simple as:

sh

brew install tectonic

We also have instructions about [installing Tectonic’s dependencies using Homebrew][homebrew-deps] if you’d like to compile Tectonic yourself on your Homebrew-based computer.

[homebrew-deps]: /howto/build-tectonic/external-dep-install.md#homebrew-on-macos

`MacPorts`

There is a tectonicport in MacPorts. If you already have MacPorts installed, installing Tectonic should be as simple as:

sh

sudo port install tectonic

`nix or nixOS`

If you’re using [nix], you can imperatively install [tectonic][nix-tectonic] with:

sh

nix-env -f '<nixpkgs>' -iA tectonic

in your shell. You can also create a temporary environment usingnix-shell:

sh

nix-shell '<nixpkgs>' -A tectonic

[nix]: https://nixos.org/ [nix-tectonic]: https://nixos.org/nixos/packages.html#tectonic

`Void Linux`

Void Linux has a tectonicpackage in the [void-packages] repository. To install it, run:

sh

sudo xbps-install -S tectonic

[void-packages]: https://github.com/void-linux/void-packages/blob/master/srcpkgs/tectonic/template

`Compile Tectonic Yourself`

You can always compile Tectonic yourself. If your system has C++ and Rust compilers installed, this may be as simple as running:

sh

cargo install tectonic

However, Tectonic requires various C/C++ support libraries that may not be available on your system by default. There are also various build options that you can turn on and off if you have more specialized needs. For all the details, consult the [How To Build Tectonic][howto-build] guide.

[howto-build]: ../howto/build-tectonic/index.md

---

`Src/Introduction/Index`

`Introduction`

This book describes the Tectonic typesetting system. The goal of the Tectonic project is to empower people to create beautiful, effective technical documents.

`Technical documents`

What do we mean by "technical documents"? While the Tectonic project seeks to cast its net as widely as possible, common examples might be software manuals, scientific papers, or analytical reports. What features do such documents include that traditional authoring frameworks have trouble supporting?

- Mathematics. Any kind of mathematical typesetting is challenging. Beautiful mathematical typesetting is extremely hard and requires deep integration with the overall typesetting system. - Abundant cross-references. Technical documents often involve extensive internal and external cross-references (links), and managing such links is a nightmare without extremely good tooling support. - Rich content. Technical documents also generally include a great deal of rich content beyond their text, such as figures, tables, and code. In the best documents, this content is seamlessly integrated into the document presentation, with precise author control over that presentation. - Integrated computation. In the 21st century, it is finally possible to integrate computation — runnable code samples, interactive graphics, live-updating data, and so on — into documents, and it is becoming clear that this new capability is not just evolutionary, but revolutionary. - Hackability. Finally, we also believe that technical documents should ideally be "hackable," meaning that people should be able to see how they work "under the hood" and use them as a basis for their own creations.

`Tectonic and TeX`

At the core of Tectonic is a modernized, complete, self-contained [TeX]/[LaTeX] engine, powered by [XeTeX] and [TeXLive].

[TeX]: https://en.wikipedia.org/wiki/TeX [LaTeX]: https://www.latex-project.org/ [XeTeX]: http://xetex.sourceforge.net/ [TeXLive]: https://www.tug.org/texlive/

For those new to it, [TeX] is a programming language. While most programming languages create software, [TeX] creates typeset documents. [TeX] is quite archaic in some ways, but in many fields it’s still the tool of choice for authoring the kinds of documents described above.

- [TeX] is absolutely unparalleled in its ability to typeset math. Workers in virtually every mathematics-heavy field use [TeX] to create documents. - The [TeX] ecosystem provides infrastructure for deep and rich cross-referencing with programs like [bibtex]. - Another hallmark of the [TeX] ecosystem is longstanding support for complex figures, tables, and other forms of rich content included in the document. - Because [TeX] is a programming language for creating documents, [TeX]-based documents can be hackable in exactly the same way as the open-source programs that underly so much of the modern software ecosystem.

[bibtex]: http://www.bibtex.org/

The fundamental principle underlying the Tectonic project is that [TeX] is, and can continue to be, the best language out there for creating the beautiful, effective technical documents that the world deserves. The [TeX] language is an amazingly clever piece of engineering, and the fact that it’s still in use 40 years (!) after its creation speaks for itself. But by the same token, there is a lot about the [TeX] software ecosystem that is archaic and outdated. The goal of Tectonic is to build on the good stuff and leave behind the things that don’t make sense anymore.

In particular, Tectonic is derived from the source code that powers the [XeTeX] engine, and the bulk of its code is the same core engine that implements the complex, Unicode-aware typesetting performed by [XeTeX]. Tectonic provides both a new user experience around that engine, and several key interventions that enable the engine to be used in fundamentally new ways.

`The goals of Tectonic`

As stated above, the overall goal of the Tectonic project is to enable people to create beautiful, effective technical documents. In particular, there are several elements of the existing [TeX] ecosystem that Tectonic aims to improve upon:

- User experience. Many aspects of the classic [TeX] user experience (UX) are bizarre and unpleasant to modern users. In particular, its error messages and diagnostic output can be utterly mystifying. Tectonic chooses to break compatibility with classic [TeX] when doing so offers the chance to improve the UX. - Embeddability. The modern [TeX] software system consists of a suite of interacting command-line programs modifying a complex tree of thousands of support files. This makes it extremely unpleasant to embed the [TeX] engine within other software systems, which prevents a whole host of exciting use cases. Tectonic delivers its engine as a reusable software library and aims to make that library easy to embed and reuse anywhere code can run. - Reproducibility. For the same reasons that the classic [TeX] experience is difficult to embed, it is difficult to guarantee reproducible document builds. For many technical documents, reproducibility is a highly-respected virtue if not an outright requirement. Tectonic aims to enable easy, byte-for-byte reproducible builds. - Web output. Modern displays and Web browsers are incredibly powerful, versatile tools. One of the motivations for the founding of the Tectonic project was the belief that current Web-based technical documents are falling far short of what should be possible, and the belief that some changes in the core [TeX] engine are necessary to fully unlock its ability to produce excellent Web-based output.

---

`Src/Lang Impl/Index`

`The Tectonic Implementation of the TeX Language`

TODO: links to TeX language guides

TODO: document customizations, e.g. \TectonicCodaTokens.

---

`Src/Ref/Documents`

`Documents`

*This concept only applies to Tectonic’s [V2 interface][v2cli-ref]. It is not relevant to [the original ("V1") interface][v1cli-ref].*

[v2cli-ref]: ./v2cli.md [v1cli-ref]: ./v1cli.md

The fundamental unit of processing in Tectonic is the document. The main purpose of Tectonic is to compile documents from their TeX source to one or more output formats.

`Source structure`

Every Tectonic document is defined by a [Tectonic.toml][tectonic-toml] file, which is found at the root of its source tree. This directory is also the root of the current Tectonic [workspace]. At the moment, "workspaces" and "documents" are the same thing, but in the future it might become possible to define multiple documents inside a single workspace.

[tectonic-toml]: ./tectonic-toml.md [workspace]: ./workspaces.md

The TeX sources are stored in a srcsubdirectory of the document root. Fresh workspaces will contain a file namedmain.tex, but this may be configured in [Tectonic.toml][tectonic-toml]. The [build command][cli-build] will process these files in the order they're provided in the inputs array.

[cli-build]: ../v2cli/build.md

`Build structure`

Build outputs are placed in the document’s build directory. By default, this is abuild subdirectory of the document root.

---

`Src/Ref/Tectonic Toml`

`The` Tectonic.toml `File`

Starting with [the V2 interface][v2], the Tectonic.tomlfile defines a Tectonic document.

[v2]: ./v2cli.md

`Contents`

The Tectonic.tomlfile is written in the [TOML] format. Allowed items in the file are detailed below.

[TOML]: https://toml.io/

text

/ Detailed source-code truncated for AI context efficiency. /

---

`Src/Ref/V1cli`

`"V1" (Default) Command Line Interface`

Tectonic is distributed as a single executable, tectonic, that is meant to be invoked from the command line. We’re starting to refer to this program’s command-line interface as the "V1" interface, because a new "V2" interface is currently under development.

The V1 interface is "[rustc]-like", offering a single primary workflow with lots of options controlling its behavior. In comparison, the V2 interface is "[cargo]-like", with a variety of subcommands anchored around a [Tectonic.toml] file defining a document to build.

[cargo]: https://doc.rust-lang.org/cargo/ [Tectonic.toml]: ./tectonic-toml.md [rustc]: https://doc.rust-lang.org/rustc/command-line-arguments.html

`Current status`

The V1 interface is the default. If you want to use the V2 interface, you need to take special steps, as described in its documentation.

`Basic usage`

The V1 interface takes an input TeX file and compiles it. Basic usage is often as simple as:

sh

tectonic myfile.tex

This will compile the file and create myfile.pdfif nothing went wrong. You can use an input filename of-to have Tectonic process standard input. (In this case, the output file will be namedtexput.pdf.)

`Options`

In the V1 interface there are a variety of options that control the engine’s behavior. If you have Tectonic installed, you can view them withtectonic
--help.

The following are the available flags.

| Short | Full | Explanation | |:------|:-------------------------------|:-------------------------------------------------------------------------------------------------------| |-b | --bundle <path or url>| Use this bundle instead of the default | |-c | --chatter <level> | How much chatter to print when running [default: default] [possible values: default, minimal] | | |--color <when> | Enable/disable colorful log output [default: auto] [possible values: always, auto, never] | |-f | --format <path> | The name of the "format" file used to initialize the TeX engine [default: latex] | |-h | --help| Prints help information | | |--hide <hide_path>... | Tell the engine that no file at <hide_path>exists, if it tries to read it | |-k | --keep-intermediates| Keep the intermediate files generated during processing | | |--keep-logs| Keep the log files generated during processing | | |--makefile-rules <dest_path> | Write Makefile-format rules expressing the dependencies of this run to <dest_path>| |-C | --only-cached| Use only resource files cached locally | |-o | --outdir <outdir> | The directory in which to place output files [default: the directory containing <input>] | | |--outfmt <format> | The kind of output to generate [default: pdf] [possible values: pdf, html, xdv, aux, fmt] | | |--pass <pass> | Which engines to run [default: default] [possible values: default, tex, bibtex_first] | |-p | --print| Print the engine’s chatter during processing | |-r | --reruns <count>| Rerun the TeX engine exactly this many times after the first | | |--synctex| Generate SyncTeX data | | |--untrusted| Input is untrusted — disable all known-insecure features | |-V | --version| Prints version information | |-Z | -Z <option>... | Unstable options. Pass -Zhelp to show a list |

---

`Src/Ref/V2cli`

`"V2" (Prototype) Command-Line Interface`

The "V2" command-line interface to Tectonic is a substantially new interface to the Tectonic engine introduced in the 0.4.x release series.

In short, the V2 interface is "[cargo]-like", with a variety of subcommands anchored around a [Tectonic.toml] file defining a document to build. For comparison, the original ("V1") interface is more "[rustc]-like", offering a single primary workflow with lots of options controlling its behavior.

[cargo]: https://doc.rust-lang.org/cargo/ [Tectonic.toml]: ./tectonic-toml.md [rustc]: https://doc.rust-lang.org/rustc/command-line-arguments.html

`Current status`

The V2 interface is currently available but not the default. It can be activated as described below.

`Activating the V2 Interface`

Because the V2 interface is not the current default, it must be explicitly activated. There are several ways to do this. One way is to use-Xfor the very first command-line argument to thetectonic executable, like so:

sh

tectonic -X build

It is anticipated that this form of invocation will be supported indefinitely.

Alternatively, if the Tectonic executable is run under a name containing the stringnextonic, the V2 interface will also be enabled. In this case, no -Xis needed (or allowed, at the moment):

sh

nextonic build

You can use various Unix argv[0]hacks to achieve this, or you can just rename or symlink thetectonic binary to nextonic manually.

`Shell completions`

Shell completions for the nextonicexecutable can be generated usingnextonic show shell-completions, plus the name of your shell. Currently, completions are only available for thenextonic command.

As an example, you can generate shell completions for zsh and save it to a file with the following command:

zsh

nextonic show shell-completions zsh > _nextonic

You can then move the completion file to a location where zsh can auto load; for example,/usr/local/share/zsh/site-functionswould probably work for most Unix systems. Alternatively, you can evaluate the completions directly in you~/.zshrc, e.g.

zsh

eval "$(nextonic show shell-completions zsh)"

Currently supported shells are listed in the --help text:

zsh

nextonic show shell-completions --help

`External tools`

The V2 interface also supports external commands. If you run tectonic -X cmd, where cmd is NOT built into Tectonic, Tectonic will search for a binary called tectonic-cmd and run it if it exists.

In particular, if a tectonic-biberbinary is found it will be preferred over the regularbiber binary when generating bibliography with the biblatexpackage. This may help resolve [possible version mismatch][biber-mismatch] betweenbiber and the bundled biblatexfiles when there are multiple TeX installations on a system.

[biber-mismatch]: https://github.com/tectonic-typesetting/tectonic/issues/893

`Migration plan`

The plan is to eventually migrate to make the V2 interface the default. This will be implemented as follows:

1. Under the current situation, the V2 interface can be explicitly activated with the leading-Xflag. The V1 interface can be explicitly selected by using a leading-Yflag. The default is V1. 2. Once the V2 interface is sufficiently stable, the V1 UI will start recommending that people adopt it via the-Xflag. Users that want to keep using the V1 interface will be instructed to explicitly select it with the-Yoption. 3. After a sufficient amount of time, the V1 interface will be flagged as deprecated. 4. After more time has passed, the default will flip: if neither-X nor -Yis provided, the V2 interface will be assumed rather than V1. 5. Eventually, the V1 interface may be entirely removed.

---

`Src/Ref/Workspaces`

`Workspaces`

*This concept only applies to Tectonic’s [V2 interface][v2cli-ref]. It is not relevant to [the original ("V1") interface][v1cli-ref].*

[v2cli-ref]: ./v2cli.md [v1cli-ref]: ./v1cli.md

A Tectonic workspace is a directory tree for building documents. The top-level directory of a workspace contains a [Tectonic.toml][tectonic-toml] file.

[tectonic-toml]: ./tectonic-toml.md

At the moment, a workspace contains exactly one [document], having its source rooted in the workspace root. In the future, Tectonic may be extended so that a workspace might contain more than one document.

[document]: ./documents.md

---

`Src/V2cli/Build`

`tectonic -X build`

Build the current document.

*This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1" CLI), see [its reference page][v1cli-ref].*

[v2cli-ref]: ../ref/v2cli.md [v1cli-ref]: ../ref/v1cli.md

#### Usage Synopsis

sh

tectonic -X build
  [--keep-intermediates] [-k]
  [--keep-logs]
  [--only-cached] [-C]
  [--open]
  [--print] [-p]
  [--target <target>]
  [--untrusted]

#### Remarks

This command builds the current document, as identified by searching for a [Tectonic.toml][tectonic-toml] file in the current directory or one of its parents. The build artifacts will be placed into the document’s build output directory, which defaults to a subdirectorybuildof the document source directory.

[tectonic-toml]: ../ref/tectonic-toml.md

#### Command-Line Options

The --keep-intermediates option (or -kfor short) will cause the engine to save intermediate files (such asmydoc.aux or mydoc.bbl) in the build output directory. By default, these files are stored in memory but not actually written to disk.

The --keep-logsoption will cause the engine to save the main TeX log file (mydoc.log) to disk. By default, this information is discarded.

The --only-cached option (or -Cfor short) will configure the engine to refuse to connect to the network when searching for support files. This can be useful if you’re working on a document in a context where the Internet is unavailable (e.g., on an airplane). While the engine generally avoids unnecessary network connections, referencing a new file in your document will cause it to look for that file in the online support bundle.

The --open option will open the built document using the system handler.

The --print option (or -pfor short) will cause the engine to print the regular terminal output of the TeX engine. This output is similar to, but not identical to, the contents of the log file. By default, this output is only printed if the engine encounters a fatal error.

The --targetoption will only build the output with the specified name. If this option is not given, all outputs will be built.

Use the --untrustedoption if building untrusted content. This is not the default, because in most cases you will trust the document that you’re building, probably because you have created it yourself, and it would be very annoying to have to pass--trustedevery time you build a document that uses shell-escape. See the security discussion in the documentation of the compile command for details. In actual usage, it would obviously be easy to forget to use this option; in cases where untrusted inputs are a genuine concern, we recommend setting the environment variableTECTONIC_UNTRUSTED_MODEto a non-empty value. This has the same effect as the--untrustedoption. Note, however, that a hostile shell user can trivially clear this variable.

---

`Src/V2cli/Bundle`

`tectonic -X bundle`

Commands relating to Tectonic’s "bundles" of support files.

*This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1" CLI), see [its reference page][v1cli-ref].*

[v2cli-ref]: ../ref/v2cli.md [v1cli-ref]: ../ref/v1cli.md

The bundle subcommands are:

- tectonic -X bundle cat-tectonic -X bundle search-tectonic -X bundle create

`tectonic -X bundle cat`

Print out a file stored in the current document’s backing bundle.

#### Usage Synopsis

sh

tectonic -X bundle cat <filename>

#### Example

sh

tectonic -X bundle cat latex.ltx

ltx

%%
%% This is file latex.ltx',
%% generated with the docstrip utility.
...

#### Remarks

If this command is run outside of a document workspace,
the system default bundle will be used.

tectonic -X bundle search

Print out the names of files in the current document’s backing bundle,
potentially with filtering.

#### Usage Synopsis

tectonic -X bundle search [term]

#### Example

tectonic -X bundle search minted

text

minted1.sty
tcbminted.code.tex
minted.4ht
minted.sty

#### Remarks

If no term is specified, all of the files in the bundle are printed. The
ordering of those filenames is unspecified.

The default search method is to use simple substring matching. Other methods may
be added in the future, activated by additional options.

If this command is run outside of a document workspace,
the system default bundle will be used.

tectonic -X bundle create

Create a new bundle. See ./bundles in the tectonic repository.

---

Src/V2cli/Compile

tectonic -X compile

Compile a standalone TeX document.

*This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1"
CLI), see [its reference page][v1cli-ref].*

[v2cli-ref]: ../ref/v2cli.md
[v1cli-ref]: ../ref/v1cli.md

#### Example

Generate myfile.pdf from myfile.tex:

tectonic -X compile myfile.tex

#### Usage Synopsis

tectonic -X compile  # full form
  [--bundle <file_path>] [-b <file_path>]
  [--format <path>] [-f <path>]
  [--hide <hide_path>...]
  [--keep-intermediates] [-k]
  [--keep-logs]
  [--makefile-rules <dest_path>]
  [--only-cached] [-C]
  [--outdir <outdir>] [-o <outdir>]
  [--outfmt <format>]
  [--pass <pass>]
  [--print] [-p]
  [--reruns <count>] [-r <count>]
  [--synctex]
  [--untrusted]
  [-Z <option>...]
  <input>

#### Remarks

This command compiles a freestanding TeX document, outside of the Tectonic
[document][docs-ref] framework. It is virtually the same interface as the ["V1"
command-line interface][v1cli-ref], with lots of options. In comparison, the V2
interface is "[cargo]-like", with a variety of subcommands anchored around a
[Tectonic.toml] file defining a document to build.

[docs-ref]: ../ref/documents.md
[cargo]: https://doc.rust-lang.org/cargo/
[Tectonic.toml]: ./tectonic-toml.md

Basic usage of this command is often as simple as:

tectonic -X compile myfile.tex

This will compile the file and create myfile.pdf if nothing went wrong. You
can use an input filename of - to have Tectonic process standard input. (In
this case, the output file will be named texput.pdf.)

##### Security

By default, the document is compiled in a "trusted" mode. This means that the
calling user can request to enable certain engine features that could raise
security concerns if used with untrusted input: the classic example of this
being TeX’s "shell-escape" functionality. These features are not enabled by
default, but they can be enabled on the command line; in the case of
shell-escape, this is done with -Z shell-escape.

If the command-line argument --untrusted is provided, these features cannot be
enabled, regardless of other settings such as -Z shell-escape. So if you are
going to process untrusted input in a command-line script, as long as you make
sure that --untrusted is provided, the known-dangerous features will be
disabled.

Furthermore, if the environment variable TECTONIC_UNTRUSTED_MODE is set to a
non-empty value, Tectonic will behave as if --untrusted were specified,
regardless of the actual command-line arguments. Setting this variable can
provide a modest extra layer of protection if the Tectonic engine is being run
outside of its CLI form. Keep in mind that untrusted shell scripts and the like
can trivially defeat this by explicitly clearing the environment variable.

#### Options

The following are the available flags.

#### Unstable options

The following unstable options may be available. As the name aims to indicate,
the set of unstable options is subject to change at any time.

| Expression | Explanation |
| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| -Z help | List all unstable options |
| -Z continue-on-errors | Keep compiling even when severe errors occur |
| -Z min-crossrefs=<num> | Equivalent to bibtex’s -min-crossrefs flag - "include after <num> crossrefs" [default: 2] |
| -Z paper-size=<spec> | Change the initial paper size [default: letter] |
| -Z search-path=<path> | Also look in <path> for files (unless --untrusted has been specified), like TEXINPUTS. Can be specified multiple times. |
| -Z shell-escape | Enable \write18 (unless --untrusted has been specified) |
| -Z shell-escape-cwd=<path> | Working directory to use for \write18. Use $(pwd) for same behaviour as most other engines (e.g. for relative paths in \inputminted). Implies -Z shell-escape |
| -Z deterministic-mode | Force a deterministic build environment. Note that setting SOURCE_DATE_EPOCH is usually sufficient for reproducible builds, and this option makes some extra functionality trade-offs. Specifically, deterministic mode breaks SyncTeX’s auxiliary files as they include and rely on absolute file paths |

---

Src/V2cli/Dump

tectonic -X dump

Run a partial document build and dump the contents of a TeX intermediate file to
standard output. This can be useful if you have an external tool that parses
such files, and you wish to integrate it into Tectonic-based authoring
workflows.

*This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1"
CLI), see [its reference page][v1cli-ref].*

[v2cli-ref]: ../ref/v2cli.md
[v1cli-ref]: ../ref/v1cli.md

#### Example

Generate and print the LaTeX aux file for the current document:

tectonic -X dump -s aux

This output can, for example, be piped into [bibtools] to generate a .bib file
that provides exactly the records needed for the document build.

[bibtools]: https://github.com/pkgw/bibtools/

#### Usage Synopsis

tectonic -X dump
  [--only-cached] [-C]
  [--profile <profile>] [-p <profile>]
  [--suffix] [-s]
  [--untrusted]
  <filename>

#### Remarks

This command runs a partial build of the current document, as identified by
searching for a [Tectonic.toml][tectonic-toml] file in the current directory or
one of its parents.

[tectonic-toml]: ../ref/tectonic-toml.md

The "partial build" consists of one pass of the TeX engine. Future versions of
this tool might gain options allowing you to specify different passes. This
command can be used to dump any file created by TeX during the build (so long
as it’s created on the first pass).

#### Command-Line Options

The --only-cached option (or -C for short) will configure the engine to
refuse to connect to the network when searching for support files. This can be
useful if you’re working on a document in a context where the Internet is
unavailable (e.g., on an airplane). While the engine generally avoids
unnecessary network connections, referencing a new file in your document will
cause it to look for that file in the online support bundle.

The --profile option (or -p for short) will select which document output
profile will be used for the build. If unspecified, the profile to use will be
effectively chosen at random.

If the --suffix (-s) argument is provided, the name of the dumped file
simply has to end with the content of the argument <filename>, rather than
match it exactly. Therefore tectonic -X dump -s aux will dump the LaTeX aux
file regardless of its complete name, and tectonic -X dump -s log will dump
the log file. If there happens to be more than one file whose name ends with
your specified suffix, they will all be dumped, in a pseudo-random order.

Use the --untrusted option if working with untrusted content. This is not the
default, because in most cases you will trust the document that you’re
building, probably because you have created it yourself, and it would be very
annoying to have to pass --trusted every time you dump a document that uses
shell-escape. See the security discussion in the documentation of the
compile command for details. In actual usage, it would obviously
be easy to forget to use this option; in cases where untrusted inputs are a
genuine concern, we recommend setting the environment variable
TECTONIC_UNTRUSTED_MODE to a non-empty value. This has the same effect as the
--untrusted option. Note, however, that a hostile shell user can trivially
clear this variable.

---

Src/V2cli/Init

tectonic -X init

Initializes a new Tectonic workspace in the current directory.

_This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1"
CLI), see [its reference page][v1cli-ref]._

[v2cli-ref]: ../ref/v2cli.md
[v1cli-ref]: ../ref/v1cli.md

#### Usage Synopsis

tectonic -X init

#### Remarks

This command will create a bare-bones [Tectonic.toml][tectonic-toml] file in the
target directory. The project’s name will be initialized to the name of the
workspace directory.

[tectonic-toml]: ../ref/tectonic-toml.md

It will also create a placeholder source file in src/main.tex.

#### See Also

- tectonic -X new

---

Src/V2cli/New

tectonic -X new

Create a new Tectonic workspace.

_This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1"
CLI), see [its reference page][v1cli-ref]._

[v2cli-ref]: ../ref/v2cli.md
[v1cli-ref]: ../ref/v1cli.md

#### Usage Synopsis

tectonic -X new [path]

If [path] is unspecified, the workspace is created in the current directory.

#### Remarks

This command will create a bare-bones [Tectonic.toml][tectonic-toml] file in the
target directory. The project’s name will be initialized to the name of the
workspace directory.

[tectonic-toml]: ../ref/tectonic-toml.md

It will also create a placeholder source file in src/main.tex.

#### See Also

- tectonic -X init

---

Src/V2cli/Watch

tectonic -X watch

Build the current document and rebuild it as input files change.

*This is a [V2 CLI][v2cli-ref] command. For information on the original ("V1"
CLI), see [its reference page][v1cli-ref].*

[v2cli-ref]: ../ref/v2cli.md
[v1cli-ref]: ../ref/v1cli.md

#### Usage Synopsis

tectonic -X watch
  [--exec <execute>...] [-x <execute>...]

#### Remarks

This command builds the current document in the same fashion as tectonic -X build, and then stays running and watches for changes to the input
files. It rebuilds the document when changes are detected.

#### Command-Line Options

The --exec option (or -x for short) configures the command used to run the
document build. The value of this option is appended to tectonic -X and
defaults to build. If you want to pass options to the build command, this is
the way to do so.

---

Src/Index

The Tectonic Typesetting System

Tectonic is a modernized, complete, self-contained
TeX/LaTeX
engine, powered by XeTeX and
TeXLive. This book aims to document the core
elements of the Tectonic software system.

Without further ado, we suggest you start with the [Introduction]!

[Introduction]: ./introduction/index.md

Contributions are welcome!

This book is, clearly, a work in progress! Contributions of any kind are most
welcome — please see the discussion in
GitHub issue #62
for some ideas of things that should be documented here.

The documentation is written in [Markdown] (specifically, CommonMark using
[pulldown-cmark]) and rendered into HTML using [mdbook]. The source code lives
in the docs/ subdirectory of [the main tectonic repository]. To make and view
changes, all you need to do is [install mdbook], then run the command:

mdbook serve

in the docs/ directory.

[Markdown]: https://commonmark.org/
[pulldown-cmark]: https://crates.io/crates/pulldown-cmark
[mdbook]: https://rust-lang-nursery.github.io/mdBook/
[the main tectonic repository]: https://github.com/tectonic-typesetting/tectonic
[install mdbook]: https://github.com/rust-lang-nursery/mdBook#installation

Members of the Tectonic community are eager to help if you run into any issues —
please launch a discussion on [the Tectonic forum] if you’d like to get
involved!

[the Tectonic forum]: https://github.com/tectonic-typesetting/tectonic/discussions

---

Src/SUMMARY

The Tectonic Typesetting System

Overview

- Introduction
- Getting Started
- Install Tectonic
- Build Your First Document
- Use a Unicode Font
- The Tectonic Implementation of the TeX Language

"V2" Command-Line Interface

- tectonic -X build
- tectonic -X bundle
- tectonic -X compile
- tectonic -X dump
- tectonic -X init
- tectonic -X new
- tectonic -X show
- tectonic -X watch

Concept Reference

- Documents
- The Tectonic.toml File
- "V1" Command-Line Interface
- "V2" Command-Line Interface
- Workspaces

How-To Guides

- Installing Tectonic
- Building Tectonic
- Install Dependencies Externally
- Install Dependencies With cargo-vcpkg
- Use Tectonic with AucTeX

---

CHANGELOG

See elsewhere for changelog

This project’s release notes are curated from the Git history of its main
branch. You can find them by looking at [the version of this file on the
release branch][branch] or the [GitHub release history][gh-releases].

[branch]: https://github.com/tectonic-typesetting/tectonic/blob/release/CHANGELOG.md
[gh-releases]: https://github.com/tectonic-typesetting/tectonic/releases

---

CONTRIBUTING

Contributing to Tectonic

Thanks for your interest in contributing to Tectonic!

There are a variety of ways to contribute to the project. This document is
concerned with things that you do on GitHub: submitting code and managing bug
reports. Please see
the corresponding section of the main Tectonic website
for a bigger-picture overview.

Code of Conduct

The only restriction for contributions is that you must abide by Tectonic’s
Code of Conduct. In summary, it says that you should
not act like a jerk. Good-faith efforts to follow the letter and spirit of the
Code of Conduct are required of all Tectonic community members.

Pull Requests

Pull requests are very welcome! If you are pondering a substantial change,
please
open an issue
before starting work so that the design can be discussed with the development
team.

The CI system requires
that all submitted Rust code be formatted according to the
rustfmt tool. We strongly
recommend that you achieve this by configuring your text editor to apply
rustfmt formatting every time you save a file,
as per these instructions.
The Git history stays easier to read this way since we avoid making commits
that simply reformat existing code.

Legalities

New Tectonic code is licensed under the MIT License, and we assign its copyright
to "the Tectonic Project". Any code that you submit to Tectonic will be assumed
to be made available under these terms unless explicitly stated otherwise.

---

README

[](https://dev.azure.com/tectonic-typesetting/tectonic/_build/latest?definitionId=11&branchName=master)
[](https://crates.io/crates/tectonic)
[](https://codecov.io/gh/tectonic-typesetting/tectonic)

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." If you want to build the [tectonic][crate] Rust crate, check out its
README.

[crate]: https://crates.io/crates/tectonic

Developer dashboard

- User website
- Community discussion forum
- Installation
- 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.)

---

Src/Howto/Build Tectonic/Bundle Default Config Copy Section

How To: Build Tectonic: Configure the Default Bundle

Build-time Environment Variables for the Default Bundle Copy Chapter

TECTONIC_BUNDLE_PREFIX TECTONIC_BUNDLE_PREFIX')" title="Copy section prompt for LLMs"> Copy Section

as of January 2025

TECTONIC_BUNDLE_LOCKED TECTONIC_BUNDLE_LOCKED')" title="Copy section prompt for LLMs"> Copy Section

Usage Examples Copy Chapter

Notes Copy Section

Src/Howto/Build Tectonic/Cargo Vcpkg Dep Install Copy Section

How To: Build Tectonic: Install Dependencies With cargo-vcpkg

Src/Howto/Build Tectonic/External Dep Install Copy Section

How To: Build Tectonic: Install System Dependencies

Debian and Ubuntu Linux Copy Chapter

RHEL, CentOS, and Fedora Linux Copy Chapter

Homebrew on macOS Copy Chapter

Conda Copy Chapter

vcpkg Copy Chapter

Src/Howto/Build Tectonic/Index Copy Section

How To: Build Tectonic

Basic Prerequisites Copy Chapter

Third-Party Dependencies Copy Chapter

Choose Cargo Features Copy Chapter

Compile the Code Copy Chapter

Src/Howto/Auctex Setup/Index Copy Section

How To: Use Tectonic with AucTeX

Basic Prerequisites Copy Chapter

Setup Copy Chapter

Additional Configuration and Usage Suggestions Copy Chapter

Compile LaTeX outside a Tectonic project Copy Section

Live PDF Preview in Tectonic projects Copy Section

Src/Getting Started/First Document Copy Section

Getting Started: Build Your First Document

Create a new document Copy Chapter

Building your document Copy Chapter

Cache Copy Chapter

Src/Getting Started/Index Copy Section

Getting Started

Src/Getting Started/Install Copy Section

Getting Started: Install Tectonic

Src/Getting Started/Unicode Copy Section

Getting Started: Use a Unicode Font

Unicode Copy Chapter

Modern Fonts Copy Chapter

Unicode Input Text Copy Chapter

Src/Installation/Index Copy Section

How To: Install Tectonic

Copy-paste a terminal command Copy Chapter

Direct download Copy Chapter

Pre-built binary packages Copy Chapter

Pre-built packages for (Ana)conda Copy Section

Arch Linux Copy Section

Homebrew Copy Section

MacPorts Copy Section

nix or nixOS Copy Section

Void Linux Copy Section

Compile Tectonic Yourself Copy Chapter

Src/Introduction/Index Copy Section

Introduction

Technical documents Copy Chapter

Tectonic and TeX Copy Chapter

The goals of Tectonic Copy Chapter

Src/Lang Impl/Index Copy Section

The Tectonic Implementation of the TeX Language

Src/Ref/Documents Copy Section

Documents

Source structure Copy Chapter

Build structure Copy Chapter

Src/Ref/Tectonic Toml Copy Section

The Tectonic.toml File

Contents Copy Chapter

Src/Ref/V1cli Copy Section

"V1" (Default) Command Line Interface

Current status Copy Chapter

Basic usage Copy Chapter

Options Copy Chapter

Src/Ref/V2cli Copy Section

"V2" (Prototype) Command-Line Interface

Current status Copy Chapter

Activating the V2 Interface Copy Chapter

Shell completions Copy Chapter

Src/Howto/Build Tectonic/Bundle Default Config

Build-time Environment Variables for the Default Bundle

`TECTONIC_BUNDLE_PREFIX`

`TECTONIC_BUNDLE_LOCKED`

Usage Examples

Notes

Src/Howto/Build Tectonic/Cargo Vcpkg Dep Install

Src/Howto/Build Tectonic/External Dep Install

Debian and Ubuntu Linux

RHEL, CentOS, and Fedora Linux

Homebrew on macOS

Conda

vcpkg

Src/Howto/Build Tectonic/Index

Basic Prerequisites

Third-Party Dependencies

Choose Cargo Features

Compile the Code

Src/Howto/Auctex Setup/Index

Basic Prerequisites

Setup

Additional Configuration and Usage Suggestions

Compile LaTeX outside a Tectonic project

Live PDF Preview in Tectonic projects

Src/Getting Started/First Document

Create a new document

Building your document

Cache

Src/Getting Started/Index

Src/Getting Started/Install

Src/Getting Started/Unicode

Unicode

Modern Fonts

Unicode Input Text

`Src/Installation/Index`

`How To: Install Tectonic`

`Copy-paste a terminal command`

`Direct download`

`Pre-built binary packages`

`Pre-built packages for (Ana)conda`

`Arch Linux`

Homebrew

`MacPorts`

`nix or nixOS`

`Void Linux`

`Compile Tectonic Yourself`

`Src/Introduction/Index`

`Introduction`

`Technical documents`

`Tectonic and TeX`

`The goals of Tectonic`

`Src/Lang Impl/Index`

`The Tectonic Implementation of the TeX Language`

`Src/Ref/Documents`

`Documents`

`Source structure`

`Build structure`

`Src/Ref/Tectonic Toml`

`The` Tectonic.toml `File`

`Contents`

`Src/Ref/V1cli`

`"V1" (Default) Command Line Interface`

`Current status`

`Basic usage`

`Options`

`Src/Ref/V2cli`

`"V2" (Prototype) Command-Line Interface`

`Current status`

`Activating the V2 Interface`

`Shell completions`

`External tools`

`Migration plan`

`Src/Ref/Workspaces`

`Workspaces`

`Src/V2cli/Build`

`tectonic -X build`

`Src/V2cli/Bundle`

`tectonic -X bundle`

`tectonic -X bundle cat`

tectonic -X bundle search