# Kompilieren

LaTeX-, Typst- und Markdown-Projekte kompilieren, Kompilieroptionen je Engine wählen, Protokolle lesen und das Offline-Holen von Paketen steuern.

Ein neues LaTeX-Projekt beginnt mit der Standard-Kompilier-Engine aus **Einstellungen → Engines → LaTeX**. Das ist ab Werk **Tectonic**, eine auf XeTeX basierende Engine, die Oleafly beiliegt. Sie können auch `latexmk` verwenden, wenn ein Projekt eine klassische TeX-Toolchain braucht, für ein einzelnes Projekt oder als Standard. Typst-Projekte kompilieren mit dem eingebauten Typst oder einer Version, die das Projekt fixiert, und Markdown-Projekte laufen über Pandoc und Tectonic. Der LaTeX-Compiler und die Typst-Version gehören zum Projekt; Änderungen an einem Projekt beeinflussen die anderen also nicht.

## Kompilieren starten

![Verwenden Sie Neu kompilieren in der Projekt-Werkzeugleiste; der Pfeil daneben öffnet die Kompilieroptionen.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵ (Ctrl+Enter), überall.
- Die Schaltfläche **Kompilieren** oben rechts in der Werkzeugleiste. Sie heißt **Neu kompilieren**, sobald das Projekt ein Ergebnis hat.
- **Neu kompilieren** in der Befehlspalette mit ⌘K.
- Öffnen Sie ein Projekt in einer Ansicht, die den PDF-Bereich zeigt, wird einmal automatisch kompiliert, sodass Sie auf einer frischen Vorschau landen.
- `oleafly build` in einem Terminal oder einem Skript. Siehe [Befehlszeilenwerkzeug](/docs/cli/).

Beim Kompilieren wird immer zuerst die aktive Datei gespeichert, damit das PDF dem entspricht, was Sie sehen. Sind Sie in der Nur-Editor-Ansicht, blendet das Kompilieren die geteilte Ansicht ein, damit Sie das Ergebnis verfolgen können.

## Kompilieroptionen

Der Pfeil neben **Neu kompilieren** öffnet die Kompilieroptionen. Das Menü zeigt nur die Optionen, die bei der Engine des Projekts etwas bewirken.

| Gruppe | LaTeX mit Tectonic | LaTeX mit `latexmk` | Typst | Markdown |
|---|---|---|---|---|
| **Automatisch kompilieren** | Ja | Ja | Ja | Ja |
| **Kompiliermodus** (Normal oder Schnell) | Ja | Nein | Nein | Nein |
| **Syntaxprüfungen** | Ja | Ja | Nein | Nein |
| **Compiler (dieses Projekt)** | Ja | Ja | Nein | Nein |
| **Typst-Version**, **Schriften**, **Build**, **Variante** | Nein | Nein | Ja | Nein |
| **Umgang mit Kompilierfehlern** | Ja | Ja | Nein | Nein |

**Kompilieren stoppen** und **Von Grund auf neu kompilieren** stehen bei jeder Engine unten im Menü. Die Gruppe **Variante** erscheint, sobald ein Typst-Projekt Kompiliervarianten hat.

Unter **Compiler (dieses Projekt)** ist **Tectonic** eingebaut. **Auto** führt Ihr System-TeX über `latexmk` aus und wählt den Compiler anhand des Quelltexts. **pdfLaTeX**, **XeLaTeX** und **LuaLaTeX** fixieren diesen Compiler und laufen ebenfalls über `latexmk`, und **upLaTeX** und **pLaTeX** kompilieren japanische Dokumente. Jede Wahl außer Tectonic braucht eine TeX-Distribution. Hat dieser Rechner keine, bietet Oleafly an, TinyTeX zu installieren, wenn Sie eine davon wählen. Siehe [Wenn kein TeX installiert ist](/docs/latex-engines/#when-no-tex-is-installed). Die Typst-Gruppen behandelt [Typst-Projekte](/docs/typst/).

## Automatisch kompilieren

Setzen Sie in den Kompilieroptionen **Automatisch kompilieren** auf **Ein**, oder führen Sie **Automatisches Kompilieren einschalten** in der Befehlspalette mit ⌘K aus. Es ist standardmäßig aus, gilt für jedes Projekt, und dieselben Steuerelemente schalten es wieder aus.

In einem LaTeX- oder Markdown-Projekt kompiliert Oleafly neu, etwa 2,5 Sekunden nachdem Sie aufhören zu tippen. Nur echte Bearbeitungen lösen es aus. Reiter wechseln oder Dateien öffnen nicht.

In einem Typst-Projekt ist Automatisch kompilieren die Live-Vorschau. Oleafly hält einen Typst-Prozess laufen, die geöffnete Datei speichert sich, kurz nachdem Sie aufhören zu tippen, von selbst, und das PDF aktualisiert sich an derselben Scroll-Position. Siehe [Live-Vorschau mit Automatisch kompilieren](/docs/typst/#live-preview-with-auto-compile).

Kompilierungen stapeln sich nie. Bearbeiten Sie den Text, während eine automatische Kompilierung läuft, beendet Oleafly sie und beginnt mit Ihrem neuesten Text von vorn, damit das PDF schneller nachzieht. Oleafly lässt eine Kompilierung fertig laufen, wenn Sie oder ein Agent sie gestartet haben, wenn sie gerade Pakete herunterlädt, wenn sie fast fertig ist oder wenn sie selbst ein Neustart ist. In diesen Fällen wird genau eine nachfolgende Kompilierung eingereiht, sodass das endgültige PDF weiterhin Ihre neuesten Bearbeitungen wiedergibt.

## Fortschritt verfolgen

Während eines Builds läuft ein schmaler Fortschrittsbalken oben über die Vorschau, und bevor das erste PDF existiert, zeigt der Bereich eine Schätzung in Prozent. Ist ein Build fertig, zeigt die Werkzeugleiste eine **Statusanzeige** mit der Kompilierzeit und einem Symbol für den Schweregrad:

- Grünes Häkchen: erfolgreich kompiliert.
- Gelbes Dreieck: mit Warnungen kompiliert. Sie erhalten das PDF trotzdem.
- Rotes Kreuz: mit Fehlern kompiliert.

Bei Erfolg wechselt die Vorschau automatisch zum PDF. Nur ein echtes Scheitern (kein PDF erzeugt) bringt Sie in die Protokollansicht.

![Ein fehlgeschlagener Kompiliervorgang, im Editor und im Protokoll markiert, danach behoben und erneut kompiliert.](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## Protokolle lesen

![Protokolle und die Dauer des letzten Builds stehen links in der Werkzeugleiste der Vorschau.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

Die Schaltfläche **Protokolle** links in der Werkzeugleiste der Vorschau wechselt zwischen PDF und Kompilierprotokoll, mit einem Abzeichen, das Fehler (rot) oder Warnungen (gelb) zählt:

- Oben eine ausgewertete **Diagnosenliste**: jeder Fehler und jede Warnung mit seiner Art und, wenn bekannt, dem Zeilenverweis wie `l.42`. Zeichen, die die Schriften nicht darstellen konnten, stehen gruppiert unter **Fehlende Zeichen**.
- Darunter das vollständige rohe Compiler-Protokoll, eingefärbt: Fehler fett rot, Zeilenverweise hervorgehoben, Dateiverschachtelung eingerückt.
- Eine Schaltfläche **Protokoll kopieren** nimmt das Ganze für einen Fehlerbericht oder einen Forenbeitrag mit. ⌘A gefolgt von ⌘C im Protokoll kopiert ebenfalls alles.
- **Leeren** neben **Protokoll kopieren** blendet das Protokoll und seine Fehler bis zur nächsten Kompilierung aus. Ihre Build-Dateien bleiben erhalten, und die nächste Kompilierung schreibt ein frisches Protokoll.

Lange Protokolle öffnen sich sofort, auch welche mit 100.000 Zeilen, und scrollen ohne leere Bereiche.

Kompilierfehler werden über die [Linter-Pipeline](/docs/editor/#the-built-in-latex-linter) außerdem zu Wellenlinien im Editor, und der [KI-Assistent](/docs/ai-chat/) kann dasselbe Protokoll mit seinem Werkzeug `get_log` lesen, wenn Sie ihn bitten, die Fehler zu beheben.

Typst-Fehler werden im Editor genau an dem Span markiert, den Typst meldet, mit der Quelltextzeile und Typsts eigenen Hinweisen. Häufige Fehler erhalten zusätzlich eine schlichte Erklärung, was schiefging.

## Pakete und Offline-Kompilieren

Tectonic lädt ein LaTeX-Paket beim ersten Mal herunter, wenn ein Dokument es braucht, und speichert es dann lokal im Zwischenspeicher. Die erste Kompilierung auf einem Rechner holt außerdem auf einen Schlag eine Reihe häufig genutzter Pakete. Diese erste Kompilierung kann langsamer sein und braucht eine Netzwerkverbindung. Spätere Kompilierungen nutzen den Zwischenspeicher. Fällt Oleaflys Paketspiegel aus, weicht die Kompilierung auf die Upstream-Quelle aus, und das Protokoll sagt das.

Der **Offline-Modus** in den Einstellungen unter Allgemein oder in der Befehlspalette macht daraus für Tectonic eine Garantie. Der Compiler läuft mit `--only-cached` und holt nie ein Paket. Ein Dokument, das ein nicht zwischengespeichertes Paket braucht, scheitert mit einer Meldung, die nach Möglichkeit die Datei nennt, und **Ausschalten und kompilieren** schaltet den Offline-Modus aus und kompiliert erneut.

Der Offline-Modus gilt auch für Typst. Typst kann kein Paket herunterladen, während er an ist, deshalb muss jedes `@preview`-Paket bereits im Zwischenspeicher liegen oder in den Ordner `typst-packages` des Projekts kopiert sein. Siehe [Pakete aus Typst Universe](/docs/typst/#packages-from-typst-universe). Markdown-Projekte ignorieren den Offline-Modus, und das Protokoll sagt das.

`latexmk` nutzt die TeX-Distribution, die auf Ihrem Rechner bereits installiert ist. Oleafly prüft zuerst System-Distributionen, darunter MacTeX, TeX Live, MiKTeX und TinyTeX, und **Einstellungen → Engines → LaTeX** kennzeichnet die, mit der kompiliert wird, als **In Verwendung**. Ist keine vorhanden, kann die App eine eigene TinyTeX-Kopie installieren und verwalten. MiKTeX braucht außerdem Perl, um `latexmk` auszuführen; siehe [MiKTeX und Perl](/docs/latex-engines/#miktex-and-perl). Weil ein System-TeX-Prozess Dateien lesen kann, auf die Ihr Benutzerkonto Zugriff hat, verwenden Sie `latexmk` nur mit Projekten, denen Sie vertrauen.

Findet ein `latexmk`-Build eine Datei wie `.sty`, `.cls`, einen bibliografischen Stil, eine Schriftdatei, eine babel-Sprachdatei, eine TikZ-Bibliothek oder eine andere TeX-Datei nicht, kann Oleafly in der Fehlermeldung **Finden und installieren** anbieten. Dateiname und Paketname sind oft verschieden: `tikz.sty` gehört zum Beispiel zum TeX-Live-Paket `pgf`. Oleafly ermittelt diesen Eigentümer, installiert ihn mit `tlmgr`, frischt die Paketliste auf und kompiliert neu. Unter Debian, Ubuntu und Fedora gehört TeX Live zur Paketverwaltung des Systems, deshalb gibt Oleafly Ihnen stattdessen den Befehl für `apt` oder `dnf`. Nutzen Sie die Liste **Pakete** unter **Einstellungen → Engines → LaTeX**, wenn Sie zuerst suchen oder Pakete von Hand verwalten möchten.

## Grenzen und Sicherheitsventile

- Pro Projekt läuft immer nur eine Kompilierung, in einer Warteschlange, die nur den neuesten Auftrag kennt: Neuere Anforderungen verdrängen veraltete, darum zeigt der Wechsel des Projekts mitten im Build nie das falsche PDF, und ein Kompiliersturm entsteht nie, während Sie tippen.
- Ein verdrängter oder abgelaufener Build wird tatsächlich abgebrochen: Oleafly beendet den ganzen Prozessbaum des Compilers, auf jeder Plattform, statt ihn im Hintergrund weiterlaufen zu lassen.
- Eine Kompilierung, die länger als 5 Minuten läuft, wird beendet, statt endlos weiterzulaufen. Lädt Tectonic noch Pakete herunter, schiebt jeder Download das Limit weiter nach hinten, insgesamt bis zu 30 Minuten. Markdown zu PDF bekommt 15 Minuten, Quarto und Calepin bekommen eine Stunde.
- Ergebnisse tragen eine zur Anfrage gehörende Kennung, deshalb wird ein veraltetes PDF aus einem außer der Reihe eintreffenden Abschluss abgewiesen statt angezeigt.

## Häufige Fehler, schnelle Lösungen

- **„Fehlendes Paket“ im Offline-Modus**: Wählen Sie in der Meldung **Ausschalten und kompilieren**, oder schalten Sie den Offline-Modus für ein Kompilieren aus, um das Paket zu holen und zwischenzuspeichern, und danach wieder ein.
- **„Dieser Compiler braucht eine funktionierende TeX-Distribution“**: pdfLaTeX und die anderen `latexmk`-Compiler brauchen TeX auf diesem Rechner, deshalb öffnet sich dieser Dialog, wenn Sie einen ohne TeX wählen. Wählen Sie **TinyTeX laden und verwenden**, oder **Zurück zu Tectonic wechseln**, um zur eingebauten Engine zurückzukehren. Ist eine Kompilierung aus diesem Grund bereits gescheitert, bietet die Vorschau **TinyTeX laden und verwenden** und **Tectonic verwenden** an. Siehe [Wenn kein TeX installiert ist](/docs/latex-engines/#when-no-tex-is-installed).
- **„latexmk braucht Perl“** bei MiKTeX: Installieren Sie Strawberry Perl oder TinyTeX, das ein eigenes Perl mitbringt. Siehe [MiKTeX und Perl](/docs/latex-engines/#miktex-and-perl).
- **Eine fehlende Datei in einem `latexmk`-Build**: Verwenden Sie **Finden und installieren**. Schlägt die Suche fehl, suchen Sie in der Liste **Pakete** unter **Einstellungen → Engines → LaTeX** nach dem Datei- oder Paketnamen. Unter Debian, Ubuntu oder Fedora installieren Sie es mit `apt` oder `dnf`. MiKTeX-Pakete werden in der MiKTeX Console verwaltet.
- **upLaTeX oder pLaTeX ist nicht installiert**: Wählen Sie **Japanische Unterstützung installieren (rund 450 MB)**, wenn es angeboten wird, oder führen Sie den Befehl aus, den die Meldung nennt. Siehe [Japanische Dokumente](/docs/latex-engines/#japanese-documents-uplatex-and-platex).
- **Im PDF fehlt Text**, oft Koreanisch, Chinesisch oder Japanisch: Die Schrift hat für diese Zeichen keine Glyphen, und TeX lässt sie aus, ohne zu scheitern. Oleafly warnt Sie, und das Protokoll liefert eine Einrichtung zum Einfügen. Siehe [Zeichen fehlen im PDF](/docs/latex-engines/#characters-missing-from-the-pdf), bei Typst [Zeichen, die als Kästchen erscheinen](/docs/typst/#characters-that-show-as-boxes).
- **Ein Index, ein Glossar oder ein Symbolverzeichnis fehlt im PDF**: Tectonic kann `makeindex` nicht ausführen. Stellen Sie das Projekt auf `latexmk` um, oder bauen Sie Glossare mit `\makenoidxglossaries`, das kein externes Werkzeug braucht. Mit `latexmk` werden Listen, die mit `xindy` oder `\newglossary` entstehen, nicht gebaut.
- **Die Kompilierung ist abgelaufen**: Kompilieren Sie erneut. Waren noch Pakete im Download, setzt der Download dort fort, wo er stehen geblieben ist. Stellen Sie bei langen Entwürfen auf Tectonic den **Kompiliermodus** auf **Schnell**.
- **Eine EPS-Abbildung, ein erzwungener `pdftex`-Treiber oder eine fehlende Bündeldatei in Tectonic**: der Engine-Dialog öffnet sich. Tut er das nicht oder haben Sie ihn geschlossen, wählen Sie **Engine wählen**. [Wenn Tectonic nicht reicht](/docs/latex-engines/#when-tectonic-isnt-enough) sagt, wo es in jeder Ansicht liegt. Wählen Sie die Option mit der Markierung **Empfohlen**: Ihr System-LaTeX, wenn Oleafly eine funktionierende TeX-Distribution findet, oder **TinyTeX laden und verwenden**, wenn nicht. Fehlt ein Paket, kann Oleafly nach dem Wechsel mit seinem Installer fortfahren.
- **`minted`, PythonTeX oder `\write18` ist blockiert**: wenn Sie jeder Datei im Projekt vertrauen, wählen Sie **Externe Befehle erlauben** im Banner über dem Editor. Siehe [Externe Befehle erlauben](/docs/latex-engines/#allow-external-commands).
- **Ein Paket-Download ist in Tectonic fehlgeschlagen**: Prüfen Sie die Verbindung und wählen Sie in der Meldung **Erneut kompilieren**. Oleafly hat nach dem Spiegel bereits die Upstream-Quelle versucht, der Download setzt dort fort, wo er stehen geblieben ist, und war der Rechner offline, läuft die Kompilierung von selbst erneut, sobald die Verbindung wieder da ist.
- **„Typst 0.13.1 ist nicht installiert“**: das Projekt fixiert eine Typst-Version, die dieser Rechner nicht hat. Wählen Sie in der Vorschau **Typst 0.13.1 herunterladen**, oder **Typst verwenden** und danach Ihre Standardversion, um die Fixierung aufzuheben. Siehe [Wenn eine fixierte Version fehlt](/docs/typst/#when-a-pinned-version-is-missing).
- **Warnungen zu undefinierten Zitationen oder Verweisen**: [Preflight](/docs/preflight/#six-independent-checks) findet jeden einzelnen, mit Datei und Zeile.
- **Ein Fehler, den Sie nicht deuten können**: fragen Sie die KI. „Beheben Sie die LaTeX-Fehler“ stößt eine Schleife aus Kompilieren, Protokoll lesen, gezielter Korrektur und erneutem Kompilieren an, mit Ihrer gewählten [Freigaberichtlinie](/docs/ai-chat/).

## Andere Dokument-Engines

Die Wahl des LaTeX-Compilers ist getrennt von der Dokument-Engine des Projekts:

- **Typst-Projekte** kompilieren mit dem eingebauten Typst 0.15.1 oder der Version, die das Projekt fixiert. Siehe [Typst-Projekte](/docs/typst/).
- **Markdown-Projekte** bauen über ein verwaltetes Pandoc zum PDF, mit Tectonic als PDF-Engine.
- **Quarto-Projekte** rendern `.qmd`- und `.Rmd`-Dateien mit Quarto, zu einem PDF oder einer Webseite. Siehe [Quarto](/docs/engines/#quarto).
- **Calepin-Projekte** führen den Code in einem Typst-Dokument mit Calepin aus und bauen das PDF dann mit dem eingebauten Typst. Siehe [Calepin](/docs/engines/#calepin). Keine der beiden Engines führt den Code eines Projekts aus, bevor Sie es [erlauben](/docs/engines/#allow-code-in-a-project).
- **Getaggte, barrierefreie PDFs** nutzen LuaLaTeX über eine System-TeX-Installation oder Oleaflys verwaltetes TinyTeX. Siehe [LaTeX-Engines und Pakete](/docs/latex-engines/). Typst 0.14 und neuer taggen jedes PDF ohne zusätzliche Schritte.

Die Engine ist eine Wahl pro Projekt, die beim Anlegen des Projekts getroffen wird, und die Oberfläche passt sich an: Aktionen, die eine Engine nicht unterstützen kann, werden versteckt, statt fehlschlagen zu lassen. Um ein LaTeX-Projekt nach Typst zu bringen, [konvertieren Sie es in ein neues Typst-Projekt](/docs/typst/#convert-a-latex-project-to-typst).

## Den Quelltext hinter einem erfolgreichen Build bewahren

Aktivieren Sie [Checkpoints](/docs/checkpoints/), um den Quelltext erfolgreicher Kompilierungen zu sichern. Sie können einen früheren Build vergleichen und wiederherstellen, ohne Ihren manuellen Git-Workflow zu ändern.

Um das kompilierte PDF selbst im Projektordner zu behalten, schalten Sie [PDF beim Kompilieren synchronisieren](/docs/pdf-preview/#sync-pdf-on-compiles) im Speichermenü der Vorschau ein.
