Build rules
Public API for rules_latex.
Load symbols from here:
load("@rules_latex//latex:defs.bzl",
"latex_document", "latex_library", "latex_pkg",
"latex_test", "latex_cache_snapshot",
"latex_live")
Rules¶
Providers¶
latex_cache_snapshot¶
load("@rules_latex//latex:defs.bzl", "latex_cache_snapshot")
latex_cache_snapshot(name, deps, srcs, biber, ctan_packages, main, output, pkg_files)
Bazel-run target that captures a tectonic cache snapshot.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| deps | Other targets that contribute LaTeX sources. | List of labels | optional | [] |
| srcs | All LaTeX source files needed to compile the document online. The cache snapshot will contain whatever tectonic decides to fetch for this compile, so make sure this list is realistic. | List of labels | required | |
| biber | If True, prime the cache with biber on PATH so the resulting snapshot contains bibliography-related files. Required when consumers compile biblatex documents against this snapshot. | Boolean | optional | False |
| ctan_packages | Names of CTAN packages to download and include in the cache snapshot. Each entry is a CTAN package name (e.g. 'fancyhdr'). Packages are downloaded from CTAN mirrors in TDS format during the snapshot generation. | List of strings | optional | [] |
| main | The top-level .tex file passed to tectonic. Must also appear in srcs. |
Label | required | |
| output | Destination path for the snapshot tarball, relative to the workspace root. | String | required | |
| pkg_files | Map of label-of-input -> staged-relative-path. Overrides the auto-staging path for the listed inputs, letting you place a file anywhere under main.tex's work directory. Typical use: stage a cross-package .bib file as a sibling of main.tex so \addbibresource{refs.bib} works without .. (which tectonic refuses to hand to external tools). |
Dictionary: Label -> String | optional | {} |
latex_document¶
load("@rules_latex//latex:defs.bzl", "latex_document")
latex_document(name, deps, srcs, biber, biber_strategy, cache, ctan_packages, main, outfmt,
pkg_files, reproducible, synctex, tectonic_args)
Compiles a LaTeX source tree using tectonic.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| deps | Other targets that contribute LaTeX sources (typically latex_library or latex_pkg). |
List of labels | optional | [] |
| srcs | All LaTeX source files (.tex, .sty, .cls, .bib, images, etc.) that the document compilation might reference. | List of labels | required | |
| biber | Enable biber bibliography processing. When True, tectonic can shell out to a biber binary at compile time, resolving \\addbibresource/\\bibliography directives via biblatex. The binary comes from the rules_latex toolchain by default; set biber_strategy = "system" to use a system install instead. |
Boolean | optional | False |
| biber_strategy | Which biber binary to use when biber = True. "toolchain" (default) uses the rules_latex-vendored biber 2.17; fails at analysis time on platforms without an upstream prebuilt (currently linux/aarch64). "system" propagates $PATH so a system-installed biber is found; less hermetic, intended as an escape hatch. |
String | optional | "toolchain" |
| cache | Optional cache snapshot tarball (typically produced by latex_cache_snapshot and checked into the repository). When set, the action extracts the snapshot into the compile-time TECTONIC_CACHE_DIR and runs with --only-cached, giving a fully offline, hermetic build without pulling the full ~3 GB tectonic bundle or running an online prime. Takes precedence over the toolchain-level tectonic.bundle() and over the implicit cache pipeline. |
Label | optional | None |
| ctan_packages | Names of CTAN packages to fetch and make available to the document. Each entry is a CTAN package name (e.g. 'fancyhdr'). Packages are downloaded from CTAN mirrors in TDS format during the cache population step and bundled into the offline cache. Requires the implicit cache pipeline (default) or a cache snapshot generated with matching ctan_packages. Not supported when tectonic.bundle() is active (the toolchain-level bundle does not support on-demand CTAN package fetching). |
List of strings | optional | [] |
| main | The top-level .tex file passed to tectonic. Must also appear in srcs. |
Label | required | |
| outfmt | Output format. Passed to tectonic -X compile --outfmt. |
String | optional | "pdf" |
| pkg_files | Override the staged path of specific inputs. Map of label -> relative path under main.tex's work directory. The default main-rooted staging layout puts each src at a sensible place automatically; use pkg_files when the default would force you to write a long or ..-containing path in main.tex. The classic case is a cross-package bib file: declare pkg_files = {"//lib/refs:refs.bib": "refs.bib"} and then write \\addbibresource{refs.bib} in main.tex. |
Dictionary: Label -> String | optional | {} |
| reproducible | When True, run tectonic in deterministic mode and set SOURCE_DATE_EPOCH=0, producing byte-identical output across runs given identical inputs. Off by default to keep PDF metadata (creation date) reflecting the actual build time. Mutually exclusive with synctex. |
Boolean | optional | False |
| synctex | When True, tectonic is invoked with --synctex and the resulting <name>.synctex.gz is exposed as an additional output (also surfaced via the synctex OutputGroup). Consumed by latex_live for reverse-sync lookups (PDF click -> copy <file>:<line> to the clipboard; the browser can't drive your editor, so the click doesn't jump) and forward-sync (editor -> PDF jump, via POST /sync/forward). Mutually exclusive with reproducible because tectonic's deterministic mode disables SyncTeX output. |
Boolean | optional | False |
| tectonic_args | Extra command-line arguments passed to tectonic. Use sparingly; prefer rule-level attributes when possible. | List of strings | optional | [] |
latex_library¶
load("@rules_latex//latex:defs.bzl", "latex_library")
latex_library(name, deps, srcs)
A reusable collection of LaTeX source files.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| deps | Other latex_library / latex_pkg targets this library depends on. | List of labels | optional | [] |
| srcs | LaTeX source files (.tex/.sty/.cls/etc.) exposed by this library. | List of labels | required |
latex_live¶
load("@rules_latex//latex:defs.bzl", "latex_live")
latex_live(name, debounce_max_ms, debounce_ms, document, open_on_start, poll_interval_ms, port,
serve_fast)
Browser-based live-preview server for a latex_document.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| debounce_max_ms | Safety net for the debouncer: never wait more than this many milliseconds before firing a build, even if changes keep arriving. Without this cap, a user typing continuously into an editor with fast-autosave-on-every-keystroke would never see a rebuild. 1500 ms matches the upper bound where a user typically expects 'okay, something should happen now'. | Integer | optional | 1500 |
| debounce_ms | How many milliseconds of source-idle to require after a detected change before triggering a rebuild. Coalesces bursts of writes (e.g. format-on-save then user-save, or editors that write multiple files near-simultaneously) into a single build. Set to 0 to disable debouncing (rebuild on every poll-detected change; reproduces pre-v0.3.3 behaviour). The default of 250 ms is invisible to the user because the build itself takes longer than the debounce window. | Integer | optional | 250 |
| document | The latex_document (or any rule providing LatexInfo) to watch and rebuild. | Label | required | |
| open_on_start | If True, open the preview in the system default web browser once the server starts. The plain http URL is always printed regardless, so you can open it however you prefer. | Boolean | optional | False |
| poll_interval_ms | How often the watcher checks for source-file changes, in milliseconds. The watcher is a polling loop (no third-party watchdog/inotify dependency), so this is the amortised cost of one stat() per watched file per interval. 80 ms keeps perceived save-to-preview latency under 100 ms while staying cheap. Independent of debounce_ms: the poll interval is how fast we notice a change; the debounce window is how long we wait after a change before triggering a build. |
Integer | optional | 80 |
| port | TCP port to bind the preview server to (localhost-only). | Integer | optional | 8765 |
| serve_fast | Opt-in latency optimisation (default False). When True, the watcher replays the compiled action's invocation directly via tectonic_compile.py on each content edit instead of shelling out to bazel build, skipping Bazel analysis + sandbox setup (~50% of warm-rebuild latency). The first build, and any fast build that hits a missing cached resource, still go through bazel build, so the canonical build path is never bypassed for anything but content recompiles. Requires the watched target to be a real latex_document. The compile runs un-sandboxed but stages only the document's declared inputs, so it stays consistent with bazel build / CI. See DESIGN.md §4.7.4. |
Boolean | optional | False |
latex_pkg¶
load("@rules_latex//latex:defs.bzl", "latex_pkg")
latex_pkg(name, srcs)
A bundle of resource files (images, bib, fonts) consumed by documents.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| srcs | Resource files exposed by this package. | List of labels | required |
latex_test¶
load("@rules_latex//latex:defs.bzl", "latex_test")
latex_test(name, deps, srcs, biber, biber_strategy, cache, ctan_packages, forbidden_patterns,
forbidden_patterns_replace, main, outfmt, pkg_files, required_patterns)
Compiles a LaTeX document and asserts on the resulting log.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| deps | Other targets that contribute LaTeX sources (typically latex_library or latex_pkg). |
List of labels | optional | [] |
| srcs | All LaTeX source files needed to compile the document. | List of labels | required | |
| biber | Enable biber bibliography processing for the test compile, mirroring the same-named attribute on latex_document. When True, the toolchain biber binary is staged onto PATH so tectonic's biblatex subprocess can resolve it. | Boolean | optional | False |
| biber_strategy | Which biber binary to use when biber = True. "toolchain" (default) uses the rules_latex-vendored biber; "system" uses whatever biber is on $PATH when the test runs. |
String | optional | "toolchain" |
| cache | Optional cache snapshot tarball (typically produced by latex_cache_snapshot). When set, the test extracts the snapshot and runs tectonic with --only-cached, giving a fully offline test that doesn't need internet to run. Takes precedence over the toolchain-level bundle. |
Label | optional | None |
| ctan_packages | Names of CTAN packages to fetch and make available to the document. Each entry is a CTAN package name (e.g. 'fancyhdr'). Packages are downloaded from CTAN mirrors in TDS format during the test's inline cache population step. | List of strings | optional | [] |
| forbidden_patterns | Substrings whose presence in the tectonic log file fails the test. Appended to a sensible default list (LaTeX Error, Undefined control sequence, Emergency stop, Fatal error). Set forbidden_patterns_replace = True to discard the defaults entirely. |
List of strings | optional | [] |
| forbidden_patterns_replace | If True, forbidden_patterns replaces the default list instead of extending it. |
Boolean | optional | False |
| main | The top-level .tex file passed to tectonic. Must also appear in srcs. |
Label | required | |
| outfmt | Output format. Passed to tectonic's --outfmt. | String | optional | "pdf" |
| pkg_files | Same semantics as latex_document.pkg_files. Override the staged path of specific inputs. |
Dictionary: Label -> String | optional | {} |
| required_patterns | Substrings that MUST appear in the tectonic log file. Useful for asserting a particular package was loaded or a specific shipout happened. | List of strings | optional | [] |
LatexInfo¶
load("@rules_latex//latex:defs.bzl", "LatexInfo")
LatexInfo(srcs, search_paths, offline_strategy)
Information about a LaTeX source set or compiled document.
FIELDS