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 thread 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 is 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, 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 download the latest release from GitHub, or to install a packaged version if one is available. If you’d like to see detailed instructions, go to the How To Install Tectonic guide. But the short version of the GitHub approach is that you should:

  1. Click through to the most recent non-preview release
  2. Download the .tar.gz or .zip file that corresponds to your computer’s operating system and CPU type
  3. Unpack that archive to obtain the tectonic executable file. (Or, tectonic.exe on Windows.)
  4. Put that file in the appropriate location so that you can easily run it from your computer’s command prompt.

That’s all there is to it! 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. (Here and elsewhere 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 in one-off fashion with:

$ tectonic -X compile myfile.tex

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

Basic document source structure

The source code to your document is stored in the src subdirectory of your new document. Check it out:

$ ls src

You’ll see three files that were created by the new command:

  • _preamble.tex
  • index.tex
  • _postamble.tex

These files are pre-populated with extremely basic contents following this suggested source structure:

  • The “preamble” file should contain all of your (La)TeX initialization boilerplate, up to and including the LaTeX \begin{document} command.
  • The “index” file contains all of your actual document content, without any of the annoying boilerplate. When you create a new Tectonic document, it just contains the text Hello, world.
  • The “postamble” file should contain all of your cleanup code, starting with the LaTeX \end{document} command. There will almost never need to be any other content in this file.

When Tectonic builds your document, it processes these files in the order listed above, so all three of them need to be available. But the breakdown suggested above is only a suggestion, nothing more. If you want all of your boilerplate and content to be in a single file, we recommend putting it all in index.tex and making your preamble and postamble be empty.

The motivation for this separation is partially stylistic, but not entirely so. In the future, we anticipate that there might be different ways to build the same document that invoke different preamble or postamble contents.

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), open up 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 Tectonic’s 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]
  [--keep-logs]
  [--only-cached]
  [--print]
  [--open]
  [--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 --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 encounteres a fatal error.

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

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

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 PATH] [-b PATH]
  [--chatter LEVEL] [-c LEVEL]
  [--color WHEN]
  [--format PATH] [-f]
  [--hide PATH...]
  [--keep-intermediates] [-k]
  [--keep-logs]
  [--makefile-rules PATH]
  [--only-cached] [-C]
  [--open]
  [--outdir DIR] [-o]
  [--outfmt FORMAT]
  [--pass PASS]
  [--print] [-p]
  [--reruns COUNT] [-r COUNT]
  [--synctex]
  [--untrusted]
  [--web-bundle URL] [-w]
  [-Z UNSTABLE-OPTION]
  TEXPATH

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.

ShortFullExplanation
-b--bundle <PATH>Use this Zip-format bundle file to find resource files instead of the default
-c--chatter <LEVEL>How much chatter to print when running. Possible values: default, minimal
--color <WHEN>When to colorize the program’s output: always, auto, or never
--format <PATH>The name of the "format" file used to initialize the TeX engine. Default: latex
-h--helpPrints help information
--hide <PATH>...Tell the engine that no file at <PATH> exists, if it tries to read it
-k--keep-intermediatesKeep the intermediate files generated during processing
--keep-logsKeep the log files generated during processing
--makefile-rules <PATH>Write Makefile-format rules expressing the dependencies of this run to <PATH>
-C--only-cachedUse only resource files cached locally
--openOpen the output PDF after it is built
-o--outdir <OUTDIR>The directory in which to place output files. Default: the directory containing INPUT
--outfmt <FORMAT>The kind of output to generate. Possible values: pdf (the default), html, xdv, aux, format
--pass <PASS>Which engines to run. Possible values: default, tex, bibtex_first
-p--printPrint the engine's chatter during processing
-r--reruns <COUNT>Rerun the TeX engine exactly this many times after the first
--synctexGenerate SyncTeX data
--untrustedInput is untrusted: disable all known-insecure features
-V--versionPrints version information
-w--web-bundle <URL>Use this URL find resource files instead of the default
-Z-Z <UNSTABLE-OPTION>Activate experimental “unstable” options

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.

ExpressionExplanation
-Z helpList all unstable options
-Z continue-on-errorsKeep compiling even when severe errors occur
-Z min-crossrefs=<num>Equivalent to bibtex's -min-crossrefs flag. Default vaue: 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-escapeEnable \write18 (unless --untrusted has been specified)

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]
  [--untrusted]
  [--profile PROFILE] [-p PROFILE]
  [--suffix] [-s]
  <FILENAME-OR-PATTERN>

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 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-OR-PATTERN, rather than matching it exactly. Therefore tectonic -X build -s aux will dump the LaTeX aux file regardless of its complete name, and tectonic -X build -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 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 [DIRECTORY]

If {DIRECTORY} 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 placeholder source files in a src subdirectory: index.tex, _preamble.tex, and _postamble.tex. The default build command will process these files in the expected order:

  1. src/_preamble.tex
  2. src/index.tex
  3. src/_postamble.tex

The intention of this framework is to allow you to isolate the main content of your document from the usual LaTeX boilerplate. There are no restrictions on what kind of content may be placed in each file, though.

tectonic -X show

Display various useful pieces of information.

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

The show subcommands are:

tectonic -X show user-cache-dir

Print out the location of Tectonic’s default per-user cache directory.

Usage Synopsis

tectonic -X show user-cache-dir

Example

$ tectonic -X show user-cache-dir
/home/knuth/.cache/Tectonic # Unix

$ tectonic -X show user-cache-dir
/home/knuth/Library/Caches/Tectonic # macOS

$ tectonic -X show user-cache-dir
C:\Users\knuth\AppData\Local\TectonicProject\Tectonic # Windows

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 COMMAND] [-x COMMAND]

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 that is 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 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. This directory should contain at least three files: index.tex, _preamble.tex, and _postamble.tex. These filenames can be changed in the Tectonic.toml configuration file. The build command will process these files in the following order:

  1. src/_preamble.tex
  2. src/index.tex
  3. src/_postamble.tex

The intention of this framework is to allow you to isolate the main content of your document from the usual LaTeX boilerplate. There are no restrictions on what kind of content may be placed in each file, though. The preamble and postamble can be empty if you’d like. The new command will stub out these files for you.

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 expressed in, yes, 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

[[output]]  # one or more output specifications
name = <string>  # the output's name
type = <"pdf">  # the output's type
tex_format = [string]  # optional, defaults to "latex": the TeX format to use
shell_escape = [bool]  # optional, defaults to false: whether "shell escape" (\write18) is allowed
preamble = [string] # optional, defaults to "_preamble.tex": the preamble file to use (within `src`)
index = [string] # optional, defaults to "index.tex": the index file to use (within `src`)
postamble = [string] # optional, defaults to "_postamble.tex": the postamble file to use (within `src`)

Unexpected items are not allowed.

Items

doc.name

The name of the document. This is distinct from the document title. This value will be used to name output files, so it should be relatively short and filesystem-friendly.

doc.bundle

A string identifying the location of the “bundle” of TeX support files underyling the processing of the document.

In most circumstances this value should be a URL. The tectonic -X new command will populate this field with the current recommended default.

This field can also be a filesystem path, pointing to either a Zip-format bundle or a directory of support files. This mode of operation is discouraged because it limits reproducibility. URLs with a file: protocol are also treated identically to filesystem paths.

output

A list of dictionaries defining different outputs to be created from the document source.

output.name

A name given to the output. By default, build products for each output will be placed in the build directory, in a subdirectory with this name.

output.type

The kind of output to create. Currently, the only allowed option is "pdf", which creates a Portable Document Format file.

output.tex_format

The TeX “format” of preloaded macros to use when compiling the document. The default is "latex", corresponding to the standard LaTeX format. The exact set of formats that are supported will depend on the bundle that is being used.

output.shell_escape

Whether the TeX “shell escape”, AKA \write18, mechanism is allowed. The default is false. Shell-escape is inherently insecure because its usages require that text from the document compilation is passed directly to the operating-system shell. It also is inherently unportable, because it requires that your document compilation run in an environment where an operating system shell exists and can be invoked. Its use is therefore strongly discouraged, but some packages require it.

output.preamble

The preamble file to build the document with for this output. This defaults to "_preamble.tex" within the src directory. Typically this file will contain document setup steps.

output.index

The index file to build the document with for this output. This defaults to "index.tex" within the src directory. Typically this file will contain the body of the document.

output.postamble

The postamble file to build the document with for this output. This defaults to "_postamble.tex" within the src directory. Typically this file will contain document closing steps.

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

ShortFullExplanation
-b--bundle <PATH>Use this Zip-format bundle file to find resource files instead of the default
-c--chatter <LEVEL>How much chatter to print when running [default: default] [possible values: default, minimal]
--format <PATH>The name of the "format" file used to initialize the TeX engine [default: latex]
-h--helpPrints help information
--hide <PATH>...Tell the engine that no file at <PATH> exists, if it tries to read it
-k--keep-intermediatesKeep the intermediate files generated during processing
--keep-logsKeep the log files generated during processing
--makefile-rules <PATH>Write Makefile-format rules expressing the dependencies of this run to
-C--only-cachedUse 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, format]
--pass <PASS>Which engines to run [default: default] [possible values: default, tex, bibtex_first]
-p--printPrint the engine's chatter during processing
-r--reruns <COUNT>Rerun the TeX engine exactly this many times after the first
--synctexGenerate SyncTeX data
-V--versionPrints version information
-w--web-bundle <URL>Use this URL find resource files instead of the default

“V2” (Prototype) Command-Line Interface

The “V2” command-line interface to Tectonic is 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.

Migration plan

The plan is to eventually migrate to make the V2 interface into 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 or -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 the original (“V1”) interface.

A Tectonic workspace is a directory tree for building documents. The toplevel 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.

Know what you want? Download the latest pre-built Tectonic binaries here.

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

The direct download 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.

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, that 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 it 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 it 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 profile-able. 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 for install Tectonic’s dependencies using various package managers:

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

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[icu,graphite2]"

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 to get the vcpkg build scripts to use the x64-windows-static vcpkg triplet, which is the default one used by our cargo-vcpkg setup, as opposed to x64-windows-static-md, which is activated otherwise. And 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 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.