Build tools

Finishing one real document usually means running latex twice, with biber (bibliography) and makeindex in between — several commands in the right order, the right number of times. Doing that by hand is tedious and error-prone, so you reach for a build tool. Three are common: latexmk, which works out the passes for you; llmk, which you configure in TOML; and arara, where you spell the steps out in the source.

Why you need a build tool

Settling cross-references and the table of contents takes at least two compiles (the first writes numbers into .aux, the second reads them back). Add a bibliography and you must slot in biber or bibtex; add an index and you need makeindex; a glossary needs yet another command — and getting the order or count wrong leaves numbers out of sync. A build tool runs the needed commands in the right order, as many times as needed, repeating until things stabilize. For what each individual command does, see “Compile commands.”

latexmk — the automatic standard

latexmk (a Perl script by John Collins) is the de facto standard — it is what Overleaf runs by default. It watches files like .aux to decide for itself whether another pass is needed, and calls biber/bibtex and makeindex at the right moments. It keeps going until the output stabilizes, so in effect you just say “build.”

The standout is -pvc (preview continuously): every time you save, it rebuilds just as much as needed and refreshes the viewer.

latexmk -pdf -pvc document.tex   # 保存のたび自動ビルド / rebuild on every save
latexmk -c                       # 補助ファイルを掃除 / clean aux files

You configure its behavior in a .latexmkrc file (a local latexmkrc/.latexmkrc, or ~/.latexmkrc). $pdf_mode picks the output route; in current latexmk, 1 means pdfLaTeX, 2 means DVI → dvips → ps2pdf, 3 means DVI → dvipdf, 4 means LuaLaTeX, and 5 means XeLaTeX. For Japanese, the usual setup points $latex at uplatex, $dvipdf at dvipdfmx, and uses $pdf_mode = 3 to route PDF creation through DVI conversion.

# .latexmkrc
$pdf_mode = 1;   # 1 = pdflatex
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';

llmk — config that travels with the document

llmk (Light LaTeX Make, by Takuto Asakura) lets you declare the build in TOML. You either write an llmk.toml with a source key (and which commands to use), or embed the same settings as magic comments in the .tex. The goal is reproducibility independent of the machine — the same result for anyone, anywhere. Because the config travels with the document, it suits collaboration and distribution.

# llmk.toml
latex  = "lualatex"
source = "main.tex"

For the magic-comment form, you write TOML between lines of three-or-more + characters (it also reads % !TEX-style and YaTeX directives, but the TOML block wins):

% +++
% latex = "uplatex"
% dvipdf = "dvipdfmx"
% +++
\documentclass{ujarticle}

arara — spell the steps out in the source

arara (Island of TeX, by Paulo Cereda and others) takes the opposite tack from log-guessing: you state explicitly what to do. You list directives as comments at the top of the .tex, then run arara document.tex, and it executes them top to bottom (each step must succeed before the next). What runs is obvious from the source alone.

% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex: { synctex: yes }
\documentclass{article}

Each directive maps to a rule — a YAML file describing how to call a command. The pdflatex directive maps to the pdflatex rule, and you can pass options like { synctex: yes }. It suits cases where you want full control of the steps, or need to reproduce an unusual workflow exactly.

Which to choose

• latexmk — figures out the passes automatically; the most popular, with a comfortable -pvc live preview. The default pick.
• llmk — declarative TOML that ships with the document; reproducible across machines. Good for collaboration and distribution.
• arara — explicit steps in the source; transparent, for when you want tight control of the workflow.

All three beat typing (u)platex → dvipdfmx by hand. Start with latexmk -pdf -pvc if unsure, and reach for llmk or arara when you want portable config or fully explicit steps.

The project contract for build tools

A build tool is not just a convenient command name; it is a project contract with collaborators and CI. Whether you choose .latexmkrc, llmk.toml, or arara directives, record in files which engine the manuscript uses, which tool handles the bibliography, whether an index is made, and where the PDF is written. Writing this project contract first makes the final submission reproducible even if the editor changes.

In day-to-day use, editor buttons and CI should call the same contract. If humans use latexmk -pdf main.tex but CI runs a separate raw lualatex, font and bibliography failures may stay hidden until submission. Decide one command that succeeds at the command line, then distribute that command to the editor, watch build, and CI.