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 one-off fashion with:

$ tectonic -X compile myfile.tex

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

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.