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!

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.

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!

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.

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.

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.

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

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.

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:

[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 if one is available. For detailed instructions and additional installation options, go to the How To Install Tectonic guide.

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 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.

Getting Started: Build Your First Document

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

Important: From here on out, this Getting Started guide will use what we call the “V2” interface to the Tectonic program. The V2 interface coexists with, but has a fairly different approach than, the “V1” interface. 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.

Create a new document

The Tectonic V2 interface 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 subcommand that looks like this:

$ tectonic -X new myfirstdoc

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

$ 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 for all of the options.

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 to find the exact cache location on your machine or take a look at the implementation.

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.

Getting Started: Use a Unicode Font

You’ve created your first Tectonic document. Great! Now, let’s start exploring the ways in which Tectonic helps you create modern 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 guide uses what we call the “V2” interface to the Tectonic command-line tool. The V2 interface coexists with, but has a fairly different approach than, the “V1”interface. 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.

Unicode

When TeX was first developed more than 40 years ago, 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.

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.

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.

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 (derived from Palatino), edit your src/_preamble.tex file and add the following lines after the \documentclass command:

\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. For instance, you can open up your src/index.tex file and copy-paste in the following verse with accented characters:

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

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:

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

Fair enough. But now try typing in Bashô’s “old pond” haiku:

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

We’ll wait.

(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.)

The Tectonic Implementation of the TeX Language

TODO: links to TeX language guides

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

tectonic -X build

Build the current document.

This is a V2 CLI command. For information on the original (”V1” CLI), see its reference page.

Usage Synopsis

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 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 subdirectory build of the document source directory.

Command-Line Options

The --keep-intermediates option (or -k for short) will cause the engine to save intermediate files (such as mydoc.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-logs option 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 -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 --open option will open the built document using the system handler.

The --print option (or -p for 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 --target option will only build the output with the specified name. If this option is not given, all outputs will be built.

Use the --untrusted option 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 --trusted every 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 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.

tectonic -X bundle

Commands relating to Tectonic’s “bundles” of support files.

This is a V2 CLI command. For information on the original (”V1” CLI), see its reference page.

The bundle subcommands are:

• tectonic -X bundle cat
• tectonic -X bundle search

tectonic -X bundle cat

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

Usage Synopsis

tectonic -X bundle cat <filename>

Example

$ tectonic -X bundle cat latex.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
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 compile

Compile a standalone TeX document.

This is a V2 CLI command. For information on the original (”V1” CLI), see its reference page.

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]
  [--web-bundle <url>] [-w <url>]
  [-Z <option>...]
  <input>

Remarks

This command compiles a freestanding TeX document, outside of the Tectonic document framework. It is virtually the same interface as the “V1” command-line interface, 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.

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.

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 command. For information on the original (”V1” CLI), see its reference page.

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.

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 file in the current directory or one of its parents.

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.

tectonic -X init

Initializes a new Tectonic workspace in the current directory.

This is a V2 CLI command. For information on the original (”V1” CLI), see its reference page.

Usage Synopsis

tectonic -X init

Remarks

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

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

See Also

• tectonic -X new

tectonic -X new

Create a new Tectonic workspace.

This is a V2 CLI command. For information on the original (”V1” CLI), see its reference page.

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 file in the target directory. The project’s name will be initialized to the name of the workspace directory.

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

See Also

• tectonic -X init

tectonic -X show

tectonic -X watch

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

This is a V2 CLI command. For information on the original (”V1” CLI), see its reference page.

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.

Documents

This concept only applies to Tectonic’s V2 interface. It is not relevant to the original (”V1”) interface.

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 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.

The TeX sources are stored in a src subdirectory of the document root. Fresh workspaces will contain a file named main.tex, but this may be configured in Tectonic.toml. The build command will process these files in the order they’re provided in the inputs array.

Build structure

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

The Tectonic.toml File

Starting with the V2 interface, the Tectonic.toml file defines a Tectonic document.

Contents

The Tectonic.toml file is written in the TOML format. Allowed items in the file are detailed below.

[doc]
name = <string>  # the document name
bundle = <url or filesystem path>  # the source of the TeX bundle

# Extra search paths for TeX sources, images, etc.
#
# This is particularly useful if you have files used
# by multiple Tectonic documents. For example:
#
# repo-root/
#  ├── resources/
#  │   └── classes, images, other shared resources
#  ├── doc1/
#  │   ├── src/
#  │   └── Tectonic.toml  <-- Contains `extra_paths = ["../resources"]`
#  └── doc2/
#      ├── src/
#      └── Tectonic.toml  <-- Contains `extra_paths = ["../resources"]`
extra_paths = ["", ""]



# The doc.metadata table may contain arbitrary data.
# It does not affect Tectonic in any way.
[doc.metadata]
pubish = false
arr = [1, 2, [6, 7]]



# One (of possibly many) output specifications.
[[output]]

# This output's name. By default, build products for each output will be
# placed in the build directory under subdirectory with this name.
name = "output name"

# The output's type. Right now, only "pdf" is valid.
type = "pdf"

# The TeX "format" of preloaded macros to use when compiling the document.
# This is optional, with a default of "latex" (which corresponds to the
# standard LaTeX format). The exact set of formats that are supported will
# depend on the bundle that is being used.
tex_format = "latex"

# Whether the TeX “shell escape”, AKA `\write18`, mechanism is allowed.
# This is optional and defaults to false.
#
# Shell-escape is insecure, since it give the document access to your shell.
# It also is non-portable, because it requires your document to be built
# is run in an environment where a shell exists.
# Naturally, its use is strongly discouraged, but some packages depend on
# this feature.
shell_escape = false

# The working directory path to use for “shell escape”. The default is a
# temporary directory if `output.shell_escape` is true, else it's disabled.
# The path can be absolute or relative to the root file, but it must exist.
# Specifying this path automatically sets `output.shell_escape` to true.
# This is optional, and defaults to a temporary directory.
shell_escape_cwd = "string"

# The input file we'll use to build this document,
# Given as a path relative to the `./src` directory.
#
# This may also be an array of file paths,
# the contents of which are concatenated while building.
# You could, for example, define:
# inputs = ["preamble.tex", "main.tex"]
#
# Finally, you may include an "inline" document as follows:
# inputs = [
#   { inline = "\\documentclass[a4paper]{article}" },
#   "main.tex"
# ]
# This will insert "\documentclass[a4paper]{article}" before main.tex
# (with a newline), allowing you to set options without making a new file.
inputs = "main.tex"


# Deprecated input specification.
# These options serve the same purpose as `inputs` above, but shouldn't be used
# unless you have a legacy document.
#
# If you do have a legacy document, you should replace these options with the following:
# inputs = ["_preamble.tex", "index.tex", "_postamble.tex"]
#
# Note that these options may NOT be used with `inputs`.
# You may only use one kind of input specification.
preamble = "_preamble.tex" # the preamble file to use (within `src`)
index = "index.tex" # the index file to use (within `src`)
postamble = "_postamble.tex" # the postamble file to use (within `src`)

“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.

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:

tectonic 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.)

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 with tectonic --help.

The following are the available flags.

“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.

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 -X for the very first command-line argument to the tectonic executable, like so:

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 string nextonic, the V2 interface will also be enabled. In this case, no -X is needed (or allowed, at the moment):

nextonic build

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

Shell completions

Shell completions for the nextonic executable can be generated using nextonic show shell-completions, plus the name of your shell. Currently, completions are only available for the nextonic command.

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

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-functions would probably work for most Unix systems. Alternatively, you can evaluate the completions directly in you ~/.zshrc, e.g.

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

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

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.

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 -X flag. The V1 interface can be explicitly selected by using a leading -Y flag. The default is V1.
2. Once the V2 interface is sufficiently stable, the V1 UI will start recommending that people adopt it via the -X flag. Users that want to keep using the V1 interface will be instructed to explicitly select it with the -Y option.
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 -Y is provided, the V2 interface will be assumed rather than V1.
5. Eventually, the V1 interface may be entirely removed.

Workspaces

This concept only applies to Tectonic’s V2 interface. It is not relevant to the original (”V1”) interface.

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

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.

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:

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, you can do the same in a PowerShell window, which will unpack tectonic.exe for you:

[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 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.

For instance, on most Linux systems, you’ll want to download the file with the name looking like tectonic-<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 for an up-to-date listing.

In most cases, the package name will be tectonic and will provide a command-line tool also named tectonic.

Pre-built packages for (Ana)conda

Tectonic is available for the Conda package manager, 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.

If you don’t already have Conda installed, we recommend that you install the “Miniconda” package provided by Anaconda, Inc.. Once complete, the command conda will now be available in your terminal.

Once the conda command 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:

$ conda install -c conda-forge tectonic

Arch Linux

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

$ sudo pacman -S tectonic

and tectonic-git from the AUR.

Homebrew

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

$ brew install tectonic

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

MacPorts

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

$ sudo port install tectonic

nix or nixOS

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

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

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

$ nix-shell '<nixpkgs>' -A tectonic

Void Linux

Void Linux has a tectonic package in the void-packages repository. To install it, run:

$ sudo xbps-install -S tectonic

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:

$ 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 guide.

How To: Build Tectonic

This document lays out the options available for building the Tectonic 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.

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

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.

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

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, 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 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 to learn how to do that.

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 or separately. Activate this mode by setting the environment variable TECTONIC_DEP_BACKEND to the value vcpkg.

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 to control build options. Tectonic offers the following 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.
• 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.

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 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.

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 for vastly more information about where you can go from there.

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

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!

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.

Conda

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

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 install fontconfig freetype "harfbuzz[graphite2]" icu

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.

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"

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. Therefore a full Windows build invocation — launched from bash — might look like this:

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.

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.

(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.

(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.

(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.

(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.

(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.

(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.