---
title: "Building — TeXForge docs | UniverLab"
source: "https://univerlab.org/texforge/docs/building/"
---

[← TeXForge](/texforge/)Documentation

# Building

Last updated 2026 · Sol 224 · 13:07 UTC (2026-08-12T13:07Z)

## `texforge build`

Compiles the project to `<title>.pdf` in the project root:

1.  Copies sources into a temporary build directory (originals are never modified).
2.  Renders embedded [diagram environments](/texforge/docs/diagrams/) to PNG.
3.  Invokes Tectonic on the entry point declared in `project.toml` and places the resulting PDF (named after the document title) in the project root.

On the first run texforge downloads the Tectonic binary into `~/.texforge/bin/` automatically.

## Reproducible builds

By default a build embeds a current timestamp, so the same source produces a different PDF on each run. For anything that compares outputs — visual regression, build caching, meaningful diffs — texforge can pin the build time:

    texforge build --reproducible

This sets `SOURCE_DATE_EPOCH` for the Tectonic invocation. With no explicit value a fixed epoch is used (never “now”); a release can pin its own:

    texforge build --reproducible=1700000000

The same behaviour can be made the default for a project in `project.toml` (see [Configuration](/texforge/docs/configuration/)); the `--reproducible` flag wins when both are present.

**The guarantee, and its limit:** identical source plus an identical Tectonic version yields an identical PDF. A different Tectonic version (or engine updates within it) can still change the output, and the setting does not alter the visible content of a document — it only pins the embedded time.

## Watch mode

`texforge build --watch` watches `.tex` files and rebuilds automatically:

    texforge build --watch            # rebuild after 2s of inactivity (default)
    texforge build --watch --delay 5  # custom debounce delay in seconds

The terminal shows a live session timer, build count and the result of the last build. Press `Ctrl+C` to stop.

## Cleaning

    texforge clean   # remove build artifacts

## Preview

`texforge preview` rasterizes the compiled PDF to PNG pages for quick visual review or for embedding in documentation:

    # Rasterize all pages (writes to ./preview/)
    texforge preview
    
    # Single page
    texforge preview --page 1
    
    # Custom output directory
    texforge preview --out ./previews
    
    # Scale up for higher resolution (default: 1.0 pixel per PDF point)
    texforge preview --scale 2.0

## PDF Inspection

Once built, the PDF can be inspected without re-compiling:

    # Extract text as readers and accessibility tools see it
    texforge pdf text
    
    # Report pages, fonts, whether fonts are embedded, and metadata
    texforge pdf info
    
    # List which section opens each page (for diffing in version control)
    texforge pdf pages
    
    # Verify significant source words survived into the PDF
    # (catches missing fonts, encoding issues, rendering bugs)
    texforge pdf check

## Runtime directory

Texforge keeps its engine and template cache under `~/.texforge/`:

    ~/.texforge/
      bin/
        tectonic            # LaTeX engine (auto-installed on first build)
      templates/
        general/            # cached templates
        apa-general/
        ...

Deleting this directory is safe: everything is re-downloaded on demand.