# 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:

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>

$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

### 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:

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