### Src/Howto/Build Tectonic/Bundle Default Config # How To: Build Tectonic: Configure the Default Bundle Tectonic supports overriding the default bundle configuration at build time through environment variables. This feature is particularly useful for: - System packagers who need to specify bundle sources during compilation - Environments requiring reproducible builds - Users who want to use mirrored bundles for better reliability ## Build-time Environment Variables for the Default Bundle Two environment variables control the bundle configuration: ### `TECTONIC_BUNDLE_PREFIX` This variable is **required** at compile time and specifies the base URL prefix for bundles. A default value is provided in the build script `crates/bundles/build.rs` in the source repository. The variable is used to construct bundle URLs in the following pattern: ```bash $TECTONIC_BUNDLE_PREFIX/default_bundle_v$FORMAT_VERSION.tar ``` where `$FORMAT_VERSION` is a suffix from an internal variable, used to distinguish different versions of the bundle's format for backward compatibility. For example, the current default is given by: ```bash # as of January 2025 TECTONIC_BUNDLE_PREFIX=https://relay.fullyjustified.net ``` so the full bundle URL is `https://relay.fullyjustified.net/default_bundle_v33.tar`, in which `_v33` indicates the version of the bundle format. Note that this hardcoded default may change, and the default value documented here may be outdated. Please refer to the source code of Tectonic for the latest default. ### `TECTONIC_BUNDLE_LOCKED` This variable is **optional** and, when set, provides a fixed URL for the bundle. If this variable contains any non-empty value, it takes precedence over the format-version-specific URL construction using `TECTONIC_BUNDLE_PREFIX`. ## Usage Examples To build Tectonic with a custom bundle prefix: ```sh TECTONIC_BUNDLE_PREFIX="https://mirror.example.com/tectonic-bundles" cargo build ``` To build Tectonic with a locked bundle URL: ```sh TECTONIC_BUNDLE_LOCKED="https://mirror.example.com/tectonic-bundles/my-fixed-bundle.tar" cargo build ``` ### Notes - The bundle URL configuration happens at build time and may be overridden by appropriate `--bundle` flags at runtime. - If using `TECTONIC_BUNDLE_LOCKED`, ensure the URL points to a compatible bundle version. --- ### Src/Howto/Build Tectonic/Cargo Vcpkg Dep Install # 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. [cargo-vcpkg]: https://crates.io/crates/cargo-vcpkg [vcpkg]: https://vcpkg.readthedocs.io/ First, install [cargo-vcpkg] if needed: ```sh cargo install cargo-vcpkg ``` Then, in the Tectonic source tree, run the command to obtain all of the needed dependencies: ```sh 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: ```sh export VCPKG_ROOT="${CARGO_TARGET_DIR:-$(pwd)/target}/vcpkg" ``` [bash]: https://www.gnu.org/software/bash/ If you’re building on Windows, you’ll likely want to make sure that your [`RUSTFLAGS`] variable includes a `+crt-static` [target feature] and set the `VCPKGRS_TRIPLET` variable to `x64-windows-static-release`. This is a custom [vcpkg triplet] provided by Tectonic’s build system (in the directory `dist/vcpkg-triplets`) that is automatically activated by its [cargo-vcpkg] integration. If you don’t use [cargo-vcpkg], the default triplet is `x64-windows-static` if the `+crt-static` feature is activated, or `x64-windows-static-md` if it is not. If you’ve done the full vcpkg install, you might as well build with [an external Harfbuzz][external-harfbuzz]. Therefore a full Windows build invocation — launched from bash — might look like this: [`RUSTFLAGS`]: https://doc.rust-lang.org/cargo/reference/environment-variables.html [target feature]: https://rust-lang.github.io/packed_simd/perf-guide/target-feature/rustflags.html [vcpkg triplet]: https://vcpkg.readthedocs.io/en/latest/users/triplets/ [external-harfbuzz]: ./index.md#choose-cargo-features ```sh cargo vcpkg build export VCPKG_ROOT="${CARGO_TARGET_DIR:-$(pwd)/target}/vcpkg" export RUSTFLAGS='-Ctarget-feature=+crt-static' # Windows only export VCPKGRS_TRIPLET='x64-windows-static-release' # Windows only export TECTONIC_DEP_BACKEND=vcpkg cargo build --features external-harfbuzz ``` Note that if you are going to run additional commands such as `cargo test`, you’re going to need to ensure that the same environment variables *and feature flags* are used consistently. --- ### Src/Howto/Build Tectonic/External Dep Install # How To: Build Tectonic: Install System Dependencies Here are quick commands to install Tectonic’s dependencies using various package managers: - [Debian and Ubuntu Linux](#debian-and-ubuntu-linux) and related variants - [RHEL, CentOS, and Fedora Linux](#rhel-centos-and-fedora-linux) and related variants - [Homebrew on macOS](#homebrew-on-macos) - [conda](#conda) on various operating systems - [vcpkg](#vcpkg) on various operating systems (including Windows) If none of these fit your needs, you’ll need to figure out the right packages for your particular setup. Tectonic requires the following libraries: - [fontconfig](https://fontconfig.org/) (except on macOS) - [freetype2](https://www.freetype.org/) - [graphite2](https://graphite.sil.org/) - [harfbuzz](https://harfbuzz.github.io/) - [ICU4C](http://site.icu-project.org/home) - [libpng](http://www.libpng.org/) - [zlib](https://zlib.net/) - Whichever SSL library is required for your system by the [rust-native-tls] crate: probably [OpenSSL](https://www.openssl.org/) [rust-native-tls]: https://github.com/sfackler/rust-native-tls/#readme ## Debian and Ubuntu Linux Install Tectonic’s dependencies with: ```sh 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: ```sh 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! [Homebrew]: https://brew.sh ```sh brew install tectonic ``` If you want to compile Tectonic yourself, the following command will install the dependencies: ```sh 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. [pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/ ## Conda If you use [Conda], be aware that you can install Tectonic with it directly, using the [conda-forge] channel! [Conda]: https://docs.conda.io/ [conda-forge]: https://conda-forge.org/ ```sh conda install -c conda-forge tectonic ``` But if you want to compile Tectonic yourself, the following command will install the dependencies: ```sh 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](./cargo-vcpkg-dep-install.md). But for the record, to install Tectonic’s dependencies through vcpkg directly, you should probably run: [vcpkg]: https://vcpkg.readthedocs.io/ ```sh vcpkg install fontconfig freetype "harfbuzz[graphite2]" icu ``` --- ### Src/Howto/Build Tectonic/Index # How To: Build Tectonic This document lays out the options available for building the Tectonic [Rust crate][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. [rust-crate]: https://doc.rust-lang.org/rust-by-example/crates.html [executable]: https://en.wikipedia.org/wiki/Executable For this reason, if you just want to *run* Tectonic, we recommend that you start by [installing][install] a pre-built version if possible. Using a pre-compiled binary will save you time and, possibly, headaches. [install]: ../installation/index.md ## 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](https://www.rust-lang.org/tools/install). You do *not* necessarily need to download a copy of the Tectonic source code, if the [cargo install] command will meet your needs. [cargo install]: https://doc.rust-lang.org/cargo/commands/cargo-install.html ## 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](https://fontconfig.org/) for discovering system fonts (except on macOS) - [freetype2](https://www.freetype.org/) for parsing font files - [graphite2](https://graphite.sil.org/) for shaping certain unusual scripts - [Harfbuzz](https://harfbuzz.github.io/) for text shaping - [ICU4C](http://site.icu-project.org/home) for Unicode data and algorithms - [libpng](http://www.libpng.org/) for parsing PNG images - [OpenSSL](https://www.openssl.org/) 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](https://zlib.net/) for compression algorithms [Harfbuzz]: https://harfbuzz.github.io/ [rust-native-tls]: https://github.com/sfackler/rust-native-tls/#readme 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][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][external-dep-install] 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][cargo-vcpkg-dep-install] to learn how to do that. [external-dep-install]: ./external-dep-install.md [vcpkg]: https://vcpkg.readthedocs.io [cargo-vcpkg-dep-install]: ./cargo-vcpkg-dep-install.md 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][cargo-vcpkg-dep-install] or separately. Activate this mode by setting the environment variable `TECTONIC_DEP_BACKEND` to the value `vcpkg`. [pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/ 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][cargo-features] to control build options. Tectonic offers the following features: [cargo-features]: https://doc.rust-lang.org/cargo/reference/features.html - **`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. [curl]: https://docs.rs/curl/ [reqwest]: https://docs.rs/reqwest/ [native-tls]: https://github.com/sfackler/rust-native-tls 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][proc-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. [serde]: https://crates.io/crates/serde [proc-macro]: https://doc.rust-lang.org/reference/procedural-macros.html 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: ```sh cargo install tectonic ``` inserting any feature flags after the `install`. To install the latest version from Git, do the same but use: ```sh 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: ```sh cargo build ``` once again adding any feature flags and ensuring that any necessary build environment variables are set up properly. Read [The Cargo Book][cargo-book] for vastly more information about where you can go from there. [cargo-book]: https://doc.rust-lang.org/cargo/index.html --- ### Src/Howto/Auctex Setup/Index # How To: Use Tectonic with AucTeX This section is a guide aimed at [GNU Emacs](https://www.gnu.org/software/emacs/) users for setting up [AucTeX](https://www.gnu.org/software/auctex/) with Tectonic as the TeX/LaTeX distribution. ## Basic Prerequisites To follow this section you will need Tectonic and GNU Emacs installed on your system. Additionally, you will require the AucTeX emacs package to be installed before following along. > Note: This section makes use of the [V2 tectonic CLI](../../ref/v2cli.md), > invoked using the `tectonic -X` flag or `nextonic` command alias. ## Setup All the code displayed in this section should go into your `init.el` file (or equivalent, such as `config.el` if you are using [Doomemacs](https://github.com/doomemacs/)). First, load the AucTeX package. ```lisp (require 'latex) ``` You will need to set the default TeX engine AucTeX uses to figure out the build commands to use Tectonic instead of traditional TeX distributions. Therefore we have to modify the `TeX-engine-alist` variable. * The first element of the list is the symbol that AucTeX recognizes. * The second element is a string with the name of the TeX distribution. * The third element is the shell command for compiling plain TeX documents. * The fourth element is the shell command for compiling LaTeX documents. Here we are assuming the user is using a Tectonic project (generated using `tectonic -X new `). * The last element is the shell command for compiling ConTeXt documents, left unconfigured for now. ```lisp (setq TeX-engine-alist '((default "Tectonic" "tectonic -X compile -f plain %T" "tectonic -X watch" nil))) ``` Next, modify the `LaTeX-command-style` so that AucTex doesn’t add extra options to it that Tectonic does not recognize. We simply set it to the `%(latex)` expansion (from `TeX-expand-list-builtin`), removing any other extra options. ```lisp (setq LaTeX-command-style '(("" "%(latex)"))) ``` We need to set the `TeX-check-TeX` variable to `nil` since AucTeX will try to find a traditional distribution like `TeXLive` or others, and will fail since Tectonic doesn’t meet its criteria. Additionally, we should also set `TeX-process-asynchronous` to `t`, so that running Tectonic in watch mode doesn’t hang up Emacs. We’ll also just ensure that the `TeX-engine` is set to `default`. ```lisp (setq TeX-process-asynchronous t TeX-check-TeX nil TeX-engine 'default) ``` Finally, modify the `TeX-command-list` to use the appropriate commands and not pass in extra metadata and options to Tectonic that cause it to error out. This needs to be done in place. ```lisp (let ((tex-list (assoc "TeX" TeX-command-list)) (latex-list (assoc "LaTeX" TeX-command-list))) (setf (cadr tex-list) "%(tex)" (cadr latex-list) "%l")) ``` And that is all! You should now be able to 1. Compile plain TeX files. 2. Build Tectonic LaTeX projects in watch mode. ## Additional Configuration and Usage Suggestions ### Compile LaTeX outside a Tectonic project To do this, you can simply invoke `M-x TeX-command-master` and select the `Other` option, passing in the compile command `tectonic -X compile -f latex `. > **Caution**: Compiling a document with multiple LaTeX files in this manner > isn’t extensively tested, as using a Tectonic project is the better way in > that case. Any bug reports are welcome. ### Live PDF Preview in Tectonic projects AucTeX expects the output PDF after compiling to be in the same directory as the input file. So it will error out when that is not the case, since Tectonic places the output in a build directory. This behavior can be controlled by using the `TeX-output-dir` variable on a per project basis. This configuration assumes you are using `project.el`, although porting this code to `projectile.el` should be trivial. ```lisp (add-hook 'after-change-major-mode-hook (lambda () (when-let ((project (project-current)) (proot (project-root project))) (when (file-exists-p (expand-file-name "Tectonic.toml" proot)) (setq-local TeX-output-dir (expand-file-name "build/index" proot)))))) ``` We are basically looking for `Tectonic.toml` file in the project root, and if it exists, setting the `TeX-output-dir` to the appropriate path to the build directory. You may replace the `"build/index"` path with wherever your PDF file is placed after it is generated by Tectonic. --- ### Src/Getting Started/First Document # Getting Started: Build Your First Document Now that [you’ve installed Tectonic][install], let’s create and build your first [document]. [install]: ./install.md [document]: ../ref/documents.md **Important:** *From here on out, this [Getting Started][gs-index] guide will use what we call the ["V2" interface][v2cli] to the Tectonic program. The V2 interface coexists with, but has a fairly different approach than, the ["V1" interface][v1cli]. 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`.* [gs-index]: ./index.md [v2cli]: ../ref/v2cli.md [v1cli]: ../ref/v1cli.md ## Create a new document The Tectonic [V2 interface][v2cli] 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`][cli-new] subcommand that looks like this: ```sh tectonic -X new myfirstdoc ``` [git]: https://git-scm.com/ [cargo]: https://doc.rust-lang.org/cargo/ [cli-new]: ../v2cli/new.md This will create a new [Tectonic workspace][workspace] directory named `myfirstdoc` containing a file `Tectonic.toml` and a sub-directory named `src`. Enter this new directory in your command prompt. [workspace]: ../ref/workspaces.md ```sh cd myfirstdoc ``` **Note:** *The `-X` flag activates the V2 interface. Don’t forget it! Eventually it will become unnecessary and you’ll just be able to write `tectonic new`, but that changeover hasn’t happened yet.* If you’ve got an existing TeX file, you can process it in one-off fashion with: ```sh tectonic -X compile myfile.tex ``` See [the `tectonic -X compile` documentation][cli-compile] for all of the options. [cli-compile]: ../v2cli/compile.md ## Building your document To compile your document, run: ```sh 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](#cache) these files and avoid downloading them again. Test it out by running the build again: ```sh 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: ```sh 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][v2cli-ref] to find the exact cache location on your machine or take a look [at the implementation][user-cache-impl]. 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. [v2cli-ref]: ../ref/v2cli.md [user-cache-impl]: https://docs.rs/tectonic_io_base/latest/tectonic_io_base/app_dirs/fn.ensure_user_cache_dir.html --- ### Src/Getting Started/Index # 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](./install.md) 2. [Build your first document](./first-document.md) 3. [Use a Unicode font](./unicode.md) --- ### Src/Getting Started/Install # Getting Started: Install Tectonic Let’s start out by making sure that Tectonic is installed on your system. Even this step will be very different than what you might be used to with other TeX systems. To install a normal TeX system such as [TeXLive], you normally need to download gigabytes of support files and set them up in a complex directory hierarchy. Tectonic, on the other hand, is distributed as a single executable file. That one file not only combines the functionality of many standard TeX programs, but it also can download the many necessary support files on the fly. This makes Tectonic super easy to install. [TeXLive]: https://www.tug.org/texlive/acquire-netinstall.html The quickest way to get started is to use your terminal. On a computer running a Unix-like operating system, including macOS, just run the following command in your terminal: ```sh curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net |sh ``` This will download the `tectonic` program and place it into the directory where you ran the command. On Windows, copy-paste this into a PowerShell window, which will unpack `tectonic.exe` for you: ```ps1 [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 iex ((New-Object System.Net.WebClient).DownloadString('https://drop-ps1.fullyjustified.net')) ``` No matter your operating system, you should move the unpacked file into a directory in your executable search path so that you can run Tectonic from any working directory. For the time being, the download script doesn’t do this because it can be tricky to automatically determine what the best installation destination would be. Alternatively, you can [install a packaged version of Tectonic][inst-packaged] if one is available. For detailed instructions and additional installation options, go to the [How To Install Tectonic][inst-ref] guide. [inst-packaged]: ../installation/index.md#pre-built-binary-packages [inst-ref]: ../installation/index.md You’ll know that you’re set up when you can go to your computer’s command prompt and run: ```sh tectonic --help ``` and the result is that you get a printout of information about different options and arguments that you can pass to the Tectonic program. (From now on we’ll use a convention of a leading `$` to indicate a command that you should run at your computer’s command prompt. You don’t type the dollar sign itself.) To be explicit, *Tectonic does not invoke an external `latex` program, and Tectonic is not a "wrapper" for (La)TeX.* Tectonic *is* the LaTeX program. This is essential. [The goals of the Tectonic project][goals] 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. [goals]: ../introduction/index.md#the-goals-of-tectonic --- ### Src/Getting Started/Unicode # Getting Started: Use a Unicode Font You’ve [created your first Tectonic document][first-document]. Great! Now, let’s start exploring the ways in which Tectonic helps you create modern [technical documents][tech-docs]. [first-document]: ./first-document.md [tech-docs]: ../introduction/index.md#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][gs-index] guide uses what we call the ["V2" interface][v2cli] to the Tectonic command-line tool. The V2 interface coexists with, but has a fairly different approach than, the ["V1"interface][v1cli]. 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`.* [gs-index]: ./index.md [v2cli]: ../ref/v2cli.md [v1cli]: ../ref/v1cli.md ## Unicode When TeX was first developed [more than 40 years ago][tex-history], 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. [tex-history]: https://en.wikipedia.org/wiki/TeX#History [Unicode]: https://home.unicode.org/ 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. [XeTeX]: http://xetex.sourceforge.net/ ## 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. [OpenType]: https://en.wikipedia.org/wiki/OpenType [PDF]: https://en.wikipedia.org/wiki/PDF [HTML]: https://en.wikipedia.org/wiki/HTML 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][pagella] (derived from [Palatino]), edit your `src/_preamble.tex` file and add the following lines after the `\documentclass` command: [pagella]: https://www.fontsquirrel.com/fonts/tex-gyre-pagella [Palatino]: https://en.wikipedia.org/wiki/Palatino ```tex \usepackage{fontspec} \setmainfont{texgyrepagella}[ Extension = .otf, UprightFont = *-regular, BoldFont = *-bold, ItalicFont = *-italic, BoldItalicFont = *-bolditalic, ] ``` Now rebuild your document: ```sh tectonic -X build ``` You’ll probably see Tectonic download some files: namely, the new font files that you have started using. Tectonic’s ability to fetch such files on the fly is why its installation is so much easier than a traditional TeX engine. If you open up your rebuilt document, it will be using your new font, although the difference can be difficult to detect with such a small amount of sample text. ## Unicode Input Text Tectonic’s support for Unicode broadens its *output* capabilities through the use of modern fonts. But that’s not all: Unicode also broadens the *inputs* that Tectonic accepts. With Tectonic, you can type non-English characters directly into your input TeX files, which are parsed assuming the virtually-universal [UTF-8 Unicode text encoding][utf8]. For instance, you can open up your `src/index.tex` file and copy-paste in the following [verse][bateau] with accented characters: ```tex Ô que ma quille éclate! Ô que j’aille à la mer! ``` [utf8]: https://en.wikipedia.org/wiki/UTF-8 [bateau]: https://en.wikipedia.org/wiki/Le_Bateau_ivre Rebuild your document and see your new text in the output: ```sh tectonic -X build ``` *Whatever*, you might say. *I know how to get these accented characters with TeX commands:* ```tex \^O que ma quille \'eclate! \^O que j'aille \`a la mer! ``` Fair enough. But now try typing in [Bashô’s "old pond" haiku][old-pond]: ```tex 古池や蛙飛び込む水の音 ふるいけやかわずとびこむみずのおと ``` We’ll wait. [old-pond]: https://www.japantimes.co.jp/news/2019/10/19/national/history/frog-jump-bashos-pond/ (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.) --- ### Src/Installation/Index # How To: Install Tectonic One of the big advantages that Tectonic offers compared to the traditional TeX stack is that all of Tectonic’s functionality is delivered in a single executable file — not the usual tree of thousands of interlocking data files and binary tools. You have several options for obtaining the Tectonic executable. The best choice depends on your computing environment and your needs. - **For the fastest and easiest installation, [copy-paste a command into your terminal](#copy-paste-a-terminal-command)** that will automatically download the right Tectonic program for your computer - [Direct download](#direct-download) a Tectonic release - [Pre-built binary packages](#pre-built-binary-packages) for your favorite operating system or package manager - [Compile it yourself](#compile-tectonic-yourself) The [copy-paste method](#copy-paste-a-terminal-command) should cover most use cases, but if you want better integration with your operating system or computing environment, [packaged versions](#pre-built-binary-packages) might make more sense. There should be no need to compile Tectonic yourself unless you want to, or you’re hoping to run it on an unusual platform. ## Copy-paste a terminal command This is generally the easiest way to get Tectonic onto your computer. On a computer running a Unix-like operating system, including macOS, just run the following command in your terminal: ```sh curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net |sh ``` This will download the `tectonic` program and place it into the directory where you ran the command. On Windows, you can do the same in a PowerShell window, which will unpack `tectonic.exe` for you: ```ps1 [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 iex ((New-Object System.Net.WebClient).DownloadString('https://drop-ps1.fullyjustified.net')) ``` No matter your operating system, you should probably move the unpacked file into a directory in your executable search path so that you can run Tectonic from any working directory. For the time being, the download script doesn’t do this because it can be tricky to automatically determine what the best installation destination would be. ## Direct download You can [download the latest release of Tectonic here][gh-latest] 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. [gh-latest]: https://tectonic-typesetting.github.io/latest.html For instance, on most Linux systems, you’ll want to download the file with the name looking like `tectonic--x86_64-unknown-linux-gnu.tar.gz`. This tarball will unpack to a single file, `tectonic`, which is the Tectonic executable. ## Pre-built binary packages Tectonic may be available in precompiled packages offered by either your operating system or standalone package managers. Check out [the Tectonic source repository][repo] for an up-to-date listing. [repo]: https://github.com/tectonic-typesetting/tectonic/#readme In most cases, the package name will be `tectonic` and will provide a command-line tool also named `tectonic`. ### Pre-built packages for (Ana)conda Tectonic is available for the [Conda package manager][conda], 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. [conda]: https://docs.conda.io/ If you don’t already have Conda installed, we recommend that you [install the "Miniconda" package][miniconda] provided by [Anaconda, Inc.][anaconda]. Once complete, the command `conda` will now be available in your terminal. [miniconda]: https://docs.conda.io/en/latest/miniconda.html [anaconda]: https://www.anaconda.com/ Once the `conda` command is available, you can install Tectonic and its support libraries using [conda-forge](http://conda-forge.github.io/), a community-led Conda packaging project. To install Tectonic you must activate conda-forge, which can be done temporarily like so: ```sh conda install -c conda-forge tectonic ``` ### Arch Linux For users of [Arch Linux], there are two Tectonic packages available: [tectonic][arch-tectonic] from the official repositories, which can be installed with ```sh sudo pacman -S tectonic ``` and [tectonic-git][arch-tectonic-git] from the [AUR]. [Arch Linux]: https://archlinux.org/ [arch-tectonic]: https://archlinux.org/packages/extra/x86_64/tectonic/ [AUR]: https://aur.archlinux.org/ [arch-tectonic-git]: https://aur.archlinux.org/packages/tectonic-git ### Homebrew There is a `tectonic` package in [Homebrew](https://brew.sh/). If you already have Homebrew installed, installing Tectonic should be as simple as: ```sh brew install tectonic ``` We also have instructions about [installing Tectonic’s dependencies using Homebrew][homebrew-deps] if you’d like to compile Tectonic yourself on your Homebrew-based computer. [homebrew-deps]: /howto/build-tectonic/external-dep-install.md#homebrew-on-macos ### MacPorts There is a `tectonic` port in [MacPorts](https://www.macports.org/). If you already have MacPorts installed, installing Tectonic should be as simple as: ```sh sudo port install tectonic ``` ### nix or nixOS If you’re using [nix], you can imperatively install [`tectonic`][nix-tectonic] with: ```sh nix-env -f '' -iA tectonic ``` in your shell. You can also create a temporary environment using [`nix-shell`](https://nixos.org/nix/manual/#sec-nix-shell): ```sh nix-shell '' -A tectonic ``` [nix]: https://nixos.org/ [nix-tectonic]: https://nixos.org/nixos/packages.html#tectonic ### Void Linux Void Linux has a `tectonic` package in the [void-packages] repository. To install it, run: ```sh sudo xbps-install -S tectonic ``` [void-packages]: https://github.com/void-linux/void-packages/blob/master/srcpkgs/tectonic/template ## 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: ```sh 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][howto-build] guide. [howto-build]: ../howto/build-tectonic/index.md --- ### Src/Introduction/Index # Introduction This book describes the Tectonic typesetting system. The goal of the Tectonic project is to empower people to create beautiful, effective technical documents. ## Technical documents What do we mean by "technical documents"? While the Tectonic project seeks to cast its net as widely as possible, common examples might be software manuals, scientific papers, or analytical reports. What features do such documents include that traditional authoring frameworks have trouble supporting? - **Mathematics**. Any kind of mathematical typesetting is challenging. *Beautiful* mathematical typesetting is *extremely hard* and requires deep integration with the overall typesetting system. - **Abundant cross-references**. Technical documents often involve extensive internal and external cross-references (links), and managing such links is a nightmare without extremely good tooling support. - **Rich content**. Technical documents also generally include a great deal of rich content beyond their text, such as figures, tables, and code. In the best documents, this content is seamlessly integrated into the document presentation, with precise author control over that presentation. - **Integrated computation**. In the 21st century, it is finally possible to integrate computation — runnable code samples, interactive graphics, live-updating data, and so on — into documents, and it is becoming clear that this new capability is not just evolutionary, but revolutionary. - **Hackability**. Finally, we also believe that technical documents should ideally be "hackable," meaning that people should be able to see how they work "under the hood" and use them as a basis for their own creations. ## Tectonic and TeX At the core of Tectonic is a modernized, complete, self-contained [TeX]/[LaTeX] engine, powered by [XeTeX] and [TeXLive]. [TeX]: https://en.wikipedia.org/wiki/TeX [LaTeX]: https://www.latex-project.org/ [XeTeX]: http://xetex.sourceforge.net/ [TeXLive]: https://www.tug.org/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. [bibtex]: http://www.bibtex.org/ 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. --- ### Src/Lang Impl/Index # The Tectonic Implementation of the TeX Language TODO: links to TeX language guides TODO: document customizations, e.g. `\TectonicCodaTokens`. --- ### Src/Ref/Documents # Documents ***This concept only applies to Tectonic’s [V2 interface][v2cli-ref]. It is not relevant to [the original ("V1") interface][v1cli-ref].*** [v2cli-ref]: ./v2cli.md [v1cli-ref]: ./v1cli.md 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][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. [tectonic-toml]: ./tectonic-toml.md [workspace]: ./workspaces.md The TeX sources are stored in a `src` subdirectory of the document root. Fresh workspaces will contain a file named `main.tex`, but this may be configured in [Tectonic.toml][tectonic-toml]. The [`build` command][cli-build] will process these files in the order they're provided in the `inputs` array. [cli-build]: ../v2cli/build.md ## Build structure Build outputs are placed in the document’s build directory. By default, this is a `build` subdirectory of the document root. --- ### Src/Ref/Tectonic Toml # The `Tectonic.toml` File **Starting with [the V2 interface][v2]**, the `Tectonic.toml` file defines a Tectonic document. [v2]: ./v2cli.md ## Contents The `Tectonic.toml` file is written in the [TOML] format. Allowed items in the file are detailed below. [TOML]: https://toml.io/ ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Src/Ref/V1cli # "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](./v2cli.md) 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. [cargo]: https://doc.rust-lang.org/cargo/ [Tectonic.toml]: ./tectonic-toml.md [rustc]: https://doc.rust-lang.org/rustc/command-line-arguments.html ## 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](./v2cli.md). ## Basic usage The V1 interface takes an input TeX file and compiles it. Basic usage is often as simple as: ```sh 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. | Short | Full | Explanation | |:------|:-------------------------------|:-------------------------------------------------------------------------------------------------------| | `-b` | `--bundle ` | Use this bundle instead of the default | | `-c` | `--chatter ` | How much chatter to print when running [default: `default`] [possible values: `default`, `minimal`] | | | `--color ` | Enable/disable colorful log output [default: `auto`] [possible values: `always`, `auto`, `never`] | | `-f` | `--format ` | The name of the "format" file used to initialize the TeX engine [default: `latex`] | | `-h` | `--help` | Prints help information | | | `--hide ...` | Tell the engine that no file at `` exists, if it tries to read it | | `-k` | `--keep-intermediates` | Keep the intermediate files generated during processing | | | `--keep-logs` | Keep the log files generated during processing | | | `--makefile-rules ` | Write Makefile-format rules expressing the dependencies of this run to `` | | `-C` | `--only-cached` | Use only resource files cached locally | | `-o` | `--outdir ` | The directory in which to place output files [default: the directory containing ``] | | | `--outfmt ` | The kind of output to generate [default: `pdf`] [possible values: `pdf`, `html`, `xdv`, `aux`, `fmt`] | | | `--pass ` | Which engines to run [default: `default`] [possible values: `default`, `tex`, `bibtex_first`] | | `-p` | `--print` | Print the engine’s chatter during processing | | `-r` | `--reruns ` | Rerun the TeX engine exactly this many times after the first | | | `--synctex` | Generate SyncTeX data | | | `--untrusted` | Input is untrusted — disable all known-insecure features | | `-V` | `--version` | Prints version information | | `-Z` | `-Z