How To: Build Tectonic

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

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

Basic Prerequisites

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

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

Third-Party Dependencies

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

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

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

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

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

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

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

Choose Cargo Features

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

  • external-harfbuzz. By default, the Tectonic crates will build and link to a “vendored” (static, internal) version of the Harfbuzz text shaping library. If you would like to link to an externally-supplied version instead, enable this feature.
  • geturl-curl. Uses the curl crate to get URLs. In order for this to take effect, you must use --no-default-features, because geturl-reqwest is a default feature and takes precedence.
  • geturl-reqwest (enabled by default). Uses the reqwest crate to get URLs. This is a good portable default.
  • native-tls-vendored. If using reqwest, activate the vendored option in the native-tls crate, causing OpenSSL to be vendored. This can be useful when cross-compiling or building static binaries, but is discouraged because that means that the resulting binaries won’t benefit from security fixes to system TLS libraries.

Some lesser-used features are:

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

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

Compile the Code

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

cargo install tectonic

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

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

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

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

cargo build

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