Build-Werkzeuge

Ein ernsthaftes Dokument fertigzustellen heißt meist, latex zweimal auszuführen, dazwischen biber (Literatur) oder makeindex (Index) und weitere Befehle einzuschieben — alles in der richtigen Reihenfolge und so oft wie nötig. Das von Hand zu wiederholen ist mühsam und fehleranfällig. Genau das automatisieren Build-Werkzeuge. Drei sind verbreitet: latexmk, das die nötigen Läufe selbst erkennt; llmk, dessen Konfiguration in TOML steht; und arara, bei dem die Schritte im Quelltext ausdrücklich angegeben werden.

Warum man ein Build-Werkzeug braucht

Querverweise und Inhaltsverzeichnis werden erst nach mindestens zwei Läufen stabil: der erste schreibt Nummern in .aux, der zweite liest sie zurück. Kommt Literatur hinzu, muss biber oder bibtex dazwischen; für einen Index makeindex; ein Glossar braucht nochmals ein anderes Kommando. Wer Reihenfolge oder Anzahl falsch trifft, erhält verschobene Nummern. Ein Build-Werkzeug führt die nötigen Befehle in richtiger Reihenfolge und so oft wie nötig aus, bis alles stabil ist. Die Rolle der Einzelbefehle erklärt die Seite „Compile commands“.

latexmk — der automatische Standard

latexmk (ein Perl-Skript von John Collins) ist der De-facto-Standard; auch Overleaf verwendet es standardmäßig. Es beobachtet Dateien wie .aux, entscheidet selbst, ob ein weiterer Lauf nötig ist, und ruft biber/bibtex sowie makeindex zum passenden Zeitpunkt auf. Es läuft weiter, bis die Ausgabe stabil ist; praktisch sagt man nur noch „bauen“.

Besonders praktisch ist -pvc (preview continuously): Bei jedem Speichern baut es nur so viel neu wie nötig und aktualisiert den Viewer.

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

Das Verhalten lässt sich in einer .latexmkrc konfigurieren (lokal als latexmkrc/.latexmkrc oder als ~/.latexmkrc). $pdf_mode wählt den Ausgabeweg; in aktuellem latexmk steht 1 für pdfLaTeX, 2 für DVI → dvips → ps2pdf, 3 für DVI → dvipdf, 4 für LuaLaTeX und 5 für XeLaTeX. Für Japanisch ist eine übliche Konfiguration, $latex auf uplatex, $dvipdf auf dvipdfmx zu setzen und mit $pdf_mode = 3 die PDF-Erzeugung über DVI laufen zu lassen.

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

llmk — Konfiguration, die mit dem Dokument reist

llmk (Light LaTeX Make, von Takuto Asakura) beschreibt den Build deklarativ in TOML. Man schreibt entweder ein llmk.toml mit source und den zu verwendenden Befehlen, oder bettet die Einstellungen als Magic Comments in die .tex-Datei ein. Ziel ist Reproduzierbarkeit unabhängig von der Umgebung: dasselbe Ergebnis für jede Person auf jeder Maschine. Weil die Konfiguration mit dem Dokument mitgeht, eignet sich llmk gut für Zusammenarbeit und Weitergabe.

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

Für die Magic-Comment-Form schreibt man TOML zwischen Zeilen aus drei oder mehr +-Zeichen (auch % !TEX- und YaTeX-Direktiven werden gelesen, aber der TOML-Block hat Vorrang):

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

arara — Schritte im Quelltext ausschreiben

arara (Island of TeX, von Paulo Cereda und anderen) verfolgt den Gegenansatz zum Log-Raten: Die Autorin oder der Autor gibt ausdrücklich an, was zu tun ist. Am Anfang der .tex-Datei stehen Direktiven als Kommentare; arara document.tex führt sie von oben nach unten aus, jeweils erst nach erfolgreichem Schritt weiter. Was läuft, ist am Quelltext sofort erkennbar.

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

Jede Direktive verweist auf eine Regel, also eine YAML-Datei, die beschreibt, wie ein Befehl aufzurufen ist. Die Direktive pdflatex nutzt die Regel pdflatex, und Optionen wie { synctex: yes } können mitgegeben werden. Das passt, wenn man die Schritte vollständig kontrollieren oder einen ungewöhnlichen Ablauf exakt reproduzieren will.

Welche Wahl passt

• latexmk — erkennt die nötigen Läufe automatisch; am weitesten verbreitet, mit angenehmer Live-Vorschau über -pvc. Die Standardwahl.
• llmk — deklaratives TOML, das mit dem Dokument ausgeliefert wird; über Maschinen hinweg reproduzierbar. Gut für Zusammenarbeit und Verteilung.
• arara — explizite Schritte im Quelltext; transparent, wenn der Ablauf streng kontrolliert werden soll.

Alle drei sind sicherer und schneller, als (u)platex → dvipdfmx von Hand zu tippen. Bei Unsicherheit beginnt man mit latexmk -pdf -pvc; llmk oder arara werden interessant, wenn portable Konfiguration oder vollständige Explizitheit wichtiger werden.

Der Projektvertrag für Build-Werkzeuge

Ein Build-Werkzeug ist nicht nur ein bequemer Befehlsname, sondern ein Projektvertrag mit Mitwirkenden und CI. Ob .latexmkrc, llmk.toml oder arara-Direktiven: Halten Sie in Dateien fest, welchen Engine das Manuskript verwendet, welches Werkzeug die Bibliografie verarbeitet, ob ein Index gebaut wird und wohin die PDF geschrieben wird. Wird dieser Projektvertrag zuerst festgelegt, lässt sich derselbe Ablauf vor der PDF-Abgabe reproduzieren, selbst wenn der Editor wechselt.

Im Alltag sollten Editor-Schaltflächen und CI denselben Vertrag aufrufen. Wenn Menschen latexmk -pdf main.tex verwenden, CI aber ein separates rohes lualatex ausführt, bleiben Schrift- oder Bibliografiefehler womöglich bis kurz vor der Abgabe verborgen. Legen Sie zuerst einen Befehl fest, der auf der Kommandozeile erfolgreich läuft, und verteilen Sie genau diesen an Editor, Watch-Build und CI.