Build & Kompilierung

Übersicht über das Build-System

TeX64 verwendet die latexmk-Engine, um Ihre LaTeX-Dokumente zu kompilieren. latexmk verwaltet automatisch die Zwischenschritte, die für komplexe Dokumente mit Bibliographien, Indizes und Querverweisen erforderlich sind.

Alle Builds laufen lokal auf Ihrem Rechner – keine Internetverbindung erforderlich. TeX64 funktioniert vollständig offline und schützt Ihre Sicherheit und Privatsphäre. Der Kompilierungsprozess ist schnell und transparent.

Plattformhinweis: TeX64 wird derzeit für macOS (Apple Silicon und Intel) ausgeliefert, und auch die Verwaltung der TeX-Distribution erfolgt dort. Versionen für Windows und Linux sind geplant, aber noch nicht verfügbar. Die nachfolgenden macOS-Tastenkürzel und Einrichtungsschritte sind der heute unterstützte Weg; etwaige Windows/Linux-Entsprechungen gelten, sobald diese Versionen erscheinen.

Build starten

Einen Build zu starten ist unkompliziert. Sie haben mehrere Optionen:

  • Symbolleisten-Schaltfläche — Klicken Sie auf die Build-Schaltfläche (Wiedergabesymbol) in der Symbolleiste. Cmd+B ist im Editor für \textbf{} reserviert.
  • Clean Build — Öffnen Sie Settings > Build Profile und klicken Sie auf Clean. Verwenden Sie Clean -C, wenn auch erzeugte Ausgabedateien entfernt werden sollen.

Sobald der Build erfolgreich abgeschlossen ist, aktualisiert sich die PDF-Vorschau automatisch.

Build-Prozess

Während eines Builds verwaltet latexmk automatisch:

  • Mehrere Kompilierungsdurchläufe — LaTeX läuft in der Regel 2–3 Mal, um Querverweise aufzulösen
  • BibTeX/Biber — Verarbeitet Bibliographie-Einträge automatisch
  • Indexerzeugung — Führt makeindex oder xindy für Indexeinträge aus
  • Querverweise — Stellt sicher, dass \ref, \cite, \pageref und ähnliche Befehle korrekt aufgelöst werden
  • Änderungserkennung — Überspringt das Neubauen, wenn sich Dateien nicht geändert haben, und spart so Zeit

Die Build-Ausgabe erscheint während der Kompilierung im Log-Panel. Sie sehen den Fortschritt in Echtzeit und genau, was latexmk gerade tut.

Auswahl der Hauptdatei

Bei Projekten mit mehreren .tex-Dateien erkennt TeX64, welche Datei Ihr Haupt- (Root-)Dokument ist. Dazu sucht es nach dem Befehl \documentclass, der nur in der Hauptdatei vorkommt.

In den meisten Fällen funktioniert die automatische Erkennung perfekt. Wenn Sie jedoch eine komplexe Projektstruktur mit mehreren \documentclass-Deklarationen haben, können Sie die Hauptdatei in den Projekteinstellungen manuell überschreiben.

TeX64 kompiliert immer ausgehend von der Hauptdatei. Alle anderen Dateien sollten über \input- oder \include-Befehle in der Hauptdatei eingebunden werden.

Tipp: Bei „file not found"-Fehlern prüfen Sie, ob die richtige Hauptdatei ausgewählt ist. TeX64 zeigt die aktuelle Hauptdatei in der Statusleiste unten an.

Build-Profile

Mit TeX64 können Sie mehrere Build-Profile konfigurieren, jedes mit einer eigenen LaTeX-Engine und individuellen Einstellungen. Das ist nützlich, wenn Sie Ihr Dokument mit verschiedenen Engines testen möchten.

Profile werden in Ihren Projekteinstellungen erstellt und verwaltet. Jedes Profil hat einen Namen, eine Engine-Auswahl und optionale benutzerdefinierte Flags.

Profile sind in folgenden Szenarien nützlich:

  • Ein Dokument mit verschiedenen Engines testen (z. B. pdflatex vs. xelatex)
  • Separate Build-Konfigurationen für Produktions- und Entwurfsmodus pflegen
  • Benutzerdefinierte Engine-Optionen für Präsentationen oder Sonderformate verwenden

Unterstützte Engines

TeX64 unterstützt diese wichtigen LaTeX-Engines:

pdflatex

pdflatex ist die etablierteste und am weitesten verbreitete Engine. Sie ist mit nahezu allen LaTeX-Paketen und Vorlagen kompatibel und damit ideal für Standarddokumente. Sie erzeugt direkt PDF-Ausgaben und ist schnell.

Am besten geeignet für: Wissenschaftliche Arbeiten, technische Berichte, Bücher und die meisten Standarddokumente. Wenn Sie unsicher sind, welche Engine Sie verwenden sollen, ist pdflatex die sichere Wahl.

xelatex

xelatex bietet native Unicode- und Systemschriftunterstützung und ist damit ideal für nicht-lateinische Schriften wie Chinesisch, Japanisch, Arabisch und andere. Sie können jede auf Ihrem Rechner installierte Systemschrift verwenden.

Am besten geeignet für: Mehrsprachige Dokumente, nicht-lateinische Schriften und alle Projekte, die Systemschriften erfordern. Wenn Sie mit Japanisch, Chinesisch oder anderen komplexen Schriftsystemen arbeiten, ist xelatex die richtige Wahl.

lualatex

lualatex ist eine moderne Engine, die Lua-Skripting mit fortschrittlicher Schriftverarbeitung verbindet. Sie unterstützt OpenType-Schriften nativ und ermöglicht ausgefeilte typografische Steuerung.

Am besten geeignet für: Projekte, die fortgeschrittenes Skripting, komplexe Typografie oder moderne Schrifttechnologien erfordern. Verbindet die Vorteile von xelatex mit der Erweiterbarkeit von Lua.

Benutzerdefinierte latexmk-Flags

Fortgeschrittene Nutzer können benutzerdefinierte latexmk-Flags hinzufügen, um das Build-Verhalten fein abzustimmen. Diese Flags werden in den Projekteinstellungen konfiguriert.

Häufig genutzte Flags sind:

  • -shell-escape — Aktiviert \write18, um externe Programme aus LaTeX auszuführen (erforderlich für Pakete wie Minted)
  • -interaction=nonstopmode — Setzt die Kompilierung auch bei Fehlern fort (nützlich, um mehrere Probleme auf einmal zu prüfen)
  • -output-directory= — Gibt ein benutzerdefiniertes Ausgabeverzeichnis für PDF und Zwischendateien an
  • -pdf — Erzwingt den PDF-Ausgabemodus
Warnung: Benutzerdefinierte Flags sind eine fortgeschrittene Funktion. Konsultieren Sie vor deren Verwendung immer das latexmk-Handbuch oder die TeX-Dokumentation, da falsche Einstellungen zu Build-Fehlern führen können.

Kompilierungs-Log

Das Kompilierungs-Log zeigt die vollständige Ausgabe des LaTeX-Compilers und von latexmk an. TeX64 analysiert diese Ausgabe und hebt Fehler und Warnungen farbcodiert hervor.

  • Fehler — Rot hervorgehoben. Sie verhindern eine erfolgreiche Kompilierung.
  • Warnungen — Gelb oder orange hervorgehoben. Sie verhindern die Kompilierung nicht, können aber die Ausgabequalität beeinflussen.
  • Nachrichten — Grau dargestellt. Diese informieren über den Build-Prozess.

Klicken Sie auf eine Fehlermeldung oder Warnung im Log, um direkt zur betreffenden Zeile im Quellcode zu springen. Datei und Zeilennummer werden hervorgehoben, was die Fehlersuche beschleunigt.

Fehleranalyse

TeX64 parst LaTeX-Fehler automatisch, um die richtige Datei und Zeilennummer zu identifizieren.

Gängige Fehlermuster sind:

  • Undefined control sequence — Ein Befehl ist nicht definiert oder enthält einen Tippfehler
  • Missing \endcsname inserted — Meist verursacht durch nicht passende Klammern
  • File not found — Eine über \input oder \include eingebundene Datei existiert nicht
  • Package not found — Ein mit \usepackage angegebenes Paket ist nicht installiert
  • Runaway argument — Meist verursacht durch eine nicht geschlossene Klammer in einem Befehlsargument

LaTeX erzeugt häufig kaskadierende Fehler, daher ist es entscheidend, den ersten Fehler zu finden. Wenn Sie den ersten Fehler im Log beheben, lösen sich oft viele Folgefehler von selbst.

KI-gestütztes Debugging

Der KI-Assistent von TeX64 kann Ihr Kompilierungs-Log analysieren und Fehlerbehebungen vorschlagen. Das ist besonders bei kryptischen LaTeX-Fehlermeldungen hilfreich.

So nutzen Sie das KI-Debugging nach einem fehlgeschlagenen Build:

  1. Klicken Sie im Kompilierungs-Log-Panel auf die Schaltfläche „Ask AI"
  2. TeX64 sendet den vollständigen Fehlerkontext an die KI
  3. Die KI schlägt mögliche Ursachen und Lösungen vor

KI-Vorschläge sind ein hilfreicher Ausgangspunkt, aber nicht immer korrekt. Sie sind besonders nützlich, wenn Sie keine tiefen TeX-Kenntnisse besitzen.

Umgebungsdiagnose

Beim Start prüft TeX64, ob alle erforderlichen Tools auf Ihrem System verfügbar sind. Geprüft werden:

  • latexmk — Die LaTeX-Build-Automatisierungs-Engine (erforderlich)
  • TeX distribution — TeX Live, MacTeX, MiKTeX oder eine andere TeX-Distribution (erforderlich)
  • latexindent — Tool zur Code-Formatierung (optional, aber empfohlen)
  • synctex — Synchronisierung zwischen Quelle und PDF (optional, aber empfohlen)

Fehlt ein erforderliches Tool, warnt TeX64 Sie und gibt Hinweise zur Installation.

Setup-Tipp: TeX64 läuft derzeit auf macOS und verwaltet dort Ihre TeX-Distribution. Installieren Sie MacTeX mit Homebrew: brew install mactex, und starten Sie TeX64 anschließend neu, damit alle Tools erkannt werden. Die vollständige Installation dauert einige Minuten. Versionen für Windows und Linux sind geplant; sobald sie erscheinen, installieren Sie TeX Live über den Paketmanager Ihres Systems.

Clean Build

Ein Clean Build entfernt alle Zwischendateien und baut anschließend das gesamte Dokument neu auf.

Ein Clean Build entfernt:

  • .aux — Hilfsdateien (Querverweise usw.)
  • .log — Build-Logs
  • .toc — Inhaltsverzeichnis-Dateien
  • .lof, .lot — Abbildungs-/Tabellenverzeichnisse
  • .bbl, .blg — Bibliographie-Dateien
  • .fdb_latexmk — latexmk-Dateiabhängigkeits-Datenbank

Verwenden Sie einen Clean Build, wenn:

  • Der Build in einem seltsamen Zustand festhängt und normale Builds das Problem nicht beheben
  • Nach größeren strukturellen Änderungen (z. B. Hinzufügen oder Entfernen von Kapiteln)
  • Sie Caching-Probleme bei Querverweisen oder der Nummerierung vermuten
  • Nach Änderungen an Projekteinstellungen oder Engine-Optionen

Inkrementelle Kompilierung

Standardmäßig verwendet TeX64 eine inkrementelle Kompilierung. latexmk verfolgt, welche Dateien sich geändert haben, und führt nur die nötigen Kompilierungsschritte erneut aus.

Das beschleunigt Builds nach kleinen Änderungen erheblich. latexmk verfolgt Abhängigkeiten intern und führt nur dann einen vollständigen Rebuild durch, wenn dies wirklich nötig ist.

Falls die inkrementelle Kompilierung Änderungen zu übersehen scheint, erzwingen Sie mit einem Clean Build einen vollständigen Rebuild.

Build-Fehlerbehebung

Wenn Ihr Build fehlschlägt, prüfen Sie diese häufigen Probleme:

„Root File Not Found"

  • Prüfen Sie, ob die richtige Hauptdatei eingestellt ist. Mehrdateienprojekte müssen aus der Datei kompiliert werden, die \documentclass enthält.
  • Stellen Sie sicher, dass die Hauptdatei noch existiert und nicht gelöscht oder verschoben wurde.

Kryptische Fehlermeldungen

  • Prüfen Sie im Kompilierungs-Log die eigentlichen Fehlermeldungen. Scrollen Sie zum ersten – nicht zum letzten – Fehler. Wenn Sie das erste Problem beheben, lösen sich oft viele Folgefehler.
  • Nutzen Sie das KI-Debugging von TeX64, um komplexe Fehlermeldungen zu analysieren.

Paket-Fehler

  • Stellen Sie sicher, dass alle benötigten Pakete mit \usepackage geladen werden.
  • TeX64 zeigt an, welches Paket fehlt. Folgen Sie den Anweisungen in der Fehlermeldung, um es zu installieren.
  • Auf macOS mit installiertem MacTeX stehen die meisten Pakete automatisch zur Verfügung.

Speicher- oder Ressourcenprobleme

  • Dokumente mit vielen großen Bildern oder komplexen Grafiken können den Speicher überlasten.
  • Versuchen Sie, Bilder zu komprimieren oder zu verkleinern, um den Ressourcenverbrauch zu reduzieren.
  • Alternativ können Sie große Dokumente in kleinere Teile aufteilen und separat kompilieren.

Langsame Builds

  • Vergewissern Sie sich, dass die inkrementelle Kompilierung funktioniert. Nach größeren Änderungen kann ein Clean Build nötig sein.
  • Komplexe Grafiken und ausgefeilte Layouts können die Build-Zeit deutlich verlängern.
Tipp: Wenn das Problem weiterhin besteht, kopieren Sie das Kompilierungs-Log und suchen Sie auf TeX StackExchange oder in LaTeX-Communities nach dem Fehler. Diese Communities sind sehr aktiv und helfen meist schnell weiter.

Performance-Tipps

Hier sind Strategien, um die Build-Zeit zu reduzieren:

  • Entwurfsmodus — Fügen Sie \documentclass die Option draft hinzu, um die Bildverarbeitung zu überspringen und nur das Layout zu kompilieren
  • Selektive Kompilierung — Verwenden Sie \includeonly, um nur bestimmte Kapitel zu kompilieren
  • Bildoptimierung — Wandeln Sie große Bitmap-Bilder in PDF um oder verkleinern Sie ihre Größe
  • Schriftauswahl — Computer-Modern-Schriften (Standard) kompilieren schneller als komplexe Systemschriften
  • TikZ/PGFPlots-Optimierung — Komplexe Diagramme vorab in PDF kompilieren und als Bilder einbinden

Die Kombination dieser Techniken kann die Build-Zeit großer Projekte erheblich reduzieren.