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

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.

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]

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.

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.

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

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.

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

Installing 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 installing the Tectonic executable. The best choice depends on your computing environment and your needs.

• Direct download
• Pre-built binary packages
• The cargo install method

The direct download method should meet your needs unless you’re hoping to run Tectonic on an unusual platform, in which case you will probably need to install Tectonic using Cargo.

Direct download

You can download the latest release of Tectonic from 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.

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 Anaconda

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 packaing project. To install Tectonic you must activate conda-forge, which can be done temporarily like so:

conda install -c conda-forge tectonic

The cargo install method

If your system has C++ and Rust compilers installed, you can install Tectonic using Rust’s packaging tool, cargo. Make sure that Rust's bin folder ($HOME/.cargo/bin by default) is in your $PATH.

Tectonic currently requires various system support libraries to be installed. This is the most likely cause of difficulty installing Tectonic. These libraries are:

• fontconfig (except on macOS)
• freetype2
• graphite2
• harfbuzz
• ICU4C
• libpng
• zlib

There is significant interest in reducing the number of external dependencies to ease the build process, but the above is where things currently stand.

Debian and Ubuntu Linux

Ensure that the requisite packages are installed with the following command:

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

Once that is done, the following should be sufficient to download and install the latest Tectonic release:

cargo install tectonic

RHEL, CentOS, or Fedora Linux

Ensure that the requisite packages are installed with the following command:

sudo dnf install fontconfig-devel graphite2-devel harfbuzz-devel libicu-devel openssl-devel zlib-devel

Once that is done, the following should be sufficient to download and install the latest Tectonic release:

cargo install tectonic

MacOS / OS X, with Homebrew

To cargo install Tectonic on macOS, the recommended way to install the required dependencies is with Homebrew. Note, however, that you can also just directly install tectonic with Homebrew as well. If you want to compile it yourself, the following commands will install the required formulae:

brew install --only-dependencies tectonic
brew install pkg-config

If the Rust build program cargo not available, also run:

brew install rust

The cargo invocation is then as normal, but you must set up some auxiliary environment variables as well:

export DEP_OPENSSL_INCLUDE=$(brew --prefix openssl)/include
export PKG_CONFIG_PATH=/usr/local/opt/icu4c/lib/pkgconfig
cargo install tectonic

Alternatively, you can build tectonic from source by running

brew install --build-from-source tectonic

Other methods

See also some pages in the “Cookbooks” section of this book for more specialized instructions.

build tectonic with vcpkg on Windows, Linux or macOS

prerequisites

This guide assumes you have git installed and are comfortable using the command-line.

setting up your environment

If you are running macOS prior to 10.15 (Catalina), or a version of Xcode that is not up to date, you may need to install gcc. Windows and Linux should be ready to go if you have a recent compiler installed.

Install cargo-vcpkg

cargo install cargo-vcpkg

Install tectonic dependencies using vcpkg

$ cargo vcpkg build
		Cloning https://github.com/microsoft/vcpkg
	cargo build
		Checkout rev 6d36e2a
	Compiling vcpkg
	Installing freetype harfbuzz[icu,graphite2]
	Compiling bzip2 (triplet x64-osx)
	Compiling zlib (triplet x64-osx)
	Compiling libpng (triplet x64-osx)
	Compiling freetype (triplet x64-osx)
	Compiling libiconv (triplet x64-osx)
	Compiling gettext (triplet x64-osx)
	Compiling graphite2 (triplet x64-osx)
	Compiling icu (triplet x64-osx)
	Compiling ragel (triplet x64-osx)
	Compiling harfbuzz (triplet x64-osx)
		Finished in 247.89s

Build tectonic

Now we need to configure tectonic so it knows we are using vcpkg to build the binary. This is done by setting the TECTONIC_DEP_BACKEND environment variable. TECTONIC_DEP_BACKEND="vcpkg" tells tectonic to use vcpkg instead of trying to resolve the libraries using pkgconfig.

For Linux and macOS, run cargo build with the appropriate environment variables, like this:

TECTONIC_DEP_BACKEND="vcpkg" cargo build --release

Or on Windows, like this for powershell:

$Env:TECTONIC_DEP_BACKEND="vcpkg"
$Env:RUSTFLAGS="-Ctarget-feature=+crt-static"
cargo build --release

Or like this for cmd:

set TECTONIC_DEP_BACKEND="vcpkg"
set RUSTFLAGS="-Ctarget-feature=+crt-static"
cargo build --release

This will take a couple of minutes but should eventually print something like:

    Finished release [optimized] target(s) in 3m 39s

The binary should be in target/release.

Install gcc on macOS

If the cargo vcpkg build step fails on macOS, you may need to install another compiler. One way to do this is using homebrew to install gcc.

brew install gcc

build tectonic with vcpkg on macOS

This tutorial will walk you through how to build a mostly staticly linked tectonic binary on macOS. Why does this matter? Static binaries are more portable and so free you from having to support complex user environments. Thanks to mcgoo's work we can use vcpkg. vcpkg is a C/C++ package manager from Microsoft.

prerequisites

This guide assumes you have git installed and are comfortable using the command-line. You'll also need to install homebrew to install for vcpkg's gcc dependency. Package management is fun.

1. install gcc:

brew install gcc

setting up your environment

1. Install vcpkg

   1. Clone the vcpkg repository:

      git clone https://github.com/Microsoft/vcpkg
      

   2. Install it for your system:

      ./bootstrap-vcpkg.sh
      

2. Install tectonic dependencies using vcpkg. * Run the following command in your checkout of the vcpkg repository sh ./vcpkg install freetype harfbuzz\[icu,graphite2\] It should print something like the following:

   $ ./vcpkg install freetype harfbuzz\[icu,graphite2\]
   The following packages will be built and installed:
   * bzip2[core]:x64-osx
   	freetype[core]:x64-osx
   * gettext[core]:x64-osx
   * graphite2[core]:x64-osx
   	harfbuzz[core,graphite2,icu,ucdn]:x64-osx
   * icu[core]:x64-osx
   * libiconv[core]:x64-osx
   * libpng[core]:x64-osx
   * ragel[core]:x64-osx
   * zlib[core]:x64-osx
   Additional packages (*) will be modified to complete this operation.
   Starting package 1/10: graphite2:x64-osx
   Building package graphite2[core]:x64-osx...
   

build tectonic

Now we only need to configure tectonic so it knows we are using vcpkg to build the binary.

1. Run cargo build with the appropriate environment variables:

   TECTONIC_DEP_BACKEND="vcpkg" VCPKG_ROOT=/Users/me/vcpkg/ cargo build --release
   

You'll need to set VCPKG_ROOT to the full path of your vcpkg checkout. TECTONIC_DEP_BACKEND="vcpkg" tells tectonic to use vcpkg instead of trying to resolve the libraries using pkgconfig. VCPKG_ROOT=/Users/me/vcpkg/ is the root of the vcpkg tree where we just installed the required libraries.

This will take a couple minutes but should eventually print something like:

    Finished release [optimized] target(s) in 3m 39s

Congratulations! You should now have a mostly staticly linked binary in target/release suitable for sharing with users or whatever your needs are.

caveats

I say mostly staticly linked because the binary itself presumes system libraries. You can observe those links by executing otool on a given binary:

otool -L target/release/tectonic

In my case it printed the following:

target/release/tectonic:
	/System/Library/Frameworks/Foundation.framework/Versions/C/Foundation (compatibility version 300.0.0, current version 1454.98.0)
	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1454.98.0)
	/System/Library/Frameworks/CoreGraphics.framework/Versions/A/CoreGraphics (compatibility version 64.0.0, current version 1161.21.2)
	/System/Library/Frameworks/CoreText.framework/Versions/A/CoreText (compatibility version 1.0.0, current version 1.0.0)
	/System/Library/Frameworks/AppKit.framework/Versions/C/AppKit (compatibility version 45.0.0, current version 1561.60.100)
	/usr/lib/libc++.1.dylib (compatibility version 1.0.0, current version 400.9.0)
	/System/Library/Frameworks/Security.framework/Versions/A/Security (compatibility version 1.0.0, current version 58286.70.14)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1252.50.4)
	/usr/lib/libresolv.9.dylib (compatibility version 1.0.0, current version 1.0.0)
	/usr/lib/libobjc.A.dylib (compatibility version 1.0.0, current version 228.0.0)