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_serve", "latex_serve_web")

Rules¶

latex_cache_snapshot
latex_document
latex_library
latex_pkg
latex_serve
latex_serve_web
latex_test

Providers¶

LatexInfo

latex_cache_snapshot¶

load("@rules_latex//latex:defs.bzl", "latex_cache_snapshot")

latex_cache_snapshot(name, deps, srcs, biber, 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`
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, 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`
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_serve_web` for click-to-source reverse-sync in the browser. 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_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_serve¶

load("@rules_latex//latex:defs.bzl", "latex_serve")

latex_serve(name, document, open_pdf, poll_interval_ms)

Watch a latex_document's sources and rebuild on every save.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
document	The latex_document (or any rule providing LatexInfo) to watch and rebuild.	Label	required
open_pdf	If True, open the built PDF in the system's default viewer after the first successful build.	Boolean	optional	`True`
poll_interval_ms	How often the watcher checks for source-file changes, in milliseconds. Polling-based to avoid third-party dependencies; bumping this trades latency for CPU.	Integer	optional	`250`

latex_serve_web¶

load("@rules_latex//latex:defs.bzl", "latex_serve_web")

latex_serve_web(name, debounce_max_ms, debounce_ms, document, open_on_start, poll_interval_ms, port)

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 automatically once the server starts. When the launching terminal belongs to a VS Code-family editor (VS Code, Cursor, VSCodium â detected via TERM_PROGRAM), the preview is opened as a Simple Browser tab in that editor via its CLI (`code --open-url`, `cursor --open-url`, `codium --open-url`). Otherwise it falls back to the system default web browser. JetBrains IDEs and other terminals without a Simple Browser equivalent fall back to the web-browser path. The plain http URL is always printed regardless, so users can copy/paste manually.	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`

latex_test¶

load("@rules_latex//latex:defs.bzl", "latex_test")

latex_test(name, deps, srcs, biber, biber_strategy, cache, 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`
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

Name	Description
srcs	depset[File]: transitive set of LaTeX source files (.tex, .sty, .cls, .bib, images, etc.) that documents depending on this target need to see.
search_paths	depset[string]: directories (relative to the Bazel execroot) that downstream tectonic invocations should add to TEXINPUTS/BIBINPUTS/BSTINPUTS.
offline_strategy	string: which offline-mode strategy the target resolved to. One of "user_cache" (explicit `cache = "..."` attr), "bundle" (toolchain-level tectonic.bundle()), or "implicit" (implicit populate-cache pipeline). Set only by `latex_document`; other rules that provide `LatexInfo` (`latex_library`, `latex_pkg`) leave it as the empty string. Consumed by `latex_serve_web` to decide whether to interpose a persistent serve-time cache snapshot via the `//latex:_serve_cache_override` build setting.