# コンパイル

LaTeX、Typst、Markdown のプロジェクトをコンパイルし、エンジンごとのコンパイルオプションを選び、ログを読み、オフラインでのパッケージ取得を制御します。

新しい LaTeX プロジェクトは、 **設定 → エンジン → LaTeX**で選んだ既定のコンパイルエンジンで始まります。初期状態では、Oleafly に同梱されている XeTeX ベースのエンジン **Tectonic** です。従来の TeX ツールチェーンが必要なプロジェクトでは、そのプロジェクトだけに、または既定として、`latexmk` を使うこともできます。Typst プロジェクトは、組み込みの Typst か、プロジェクトが固定した別のバージョンでコンパイルされます。Markdown プロジェクトは Pandoc と Tectonic を通ります。LaTeX のコンパイラと Typst のバージョンはプロジェクトごとの設定なので、1 つのプロジェクトを変更しても、ほかのプロジェクトには影響しません。

## コンパイルを開始する

![プロジェクトのツールバーの「再コンパイル」を使います。その横の矢印でコンパイルのオプションが開きます。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵（Ctrl+Enter）。どの画面からでも使えます。
- ツールバー右上の**コンパイル**ボタン。プロジェクトに結果ができると、**再コンパイル**という表示になります。
- ⌘K コマンドパレットの**再コンパイル**。
- PDF パネルが表示されるビューでプロジェクトを開くと、自動で 1 回コンパイルされるので、最新のプレビューが表示されます。
- ターミナルやスクリプトでの `oleafly build`。[コマンドラインツール](/docs/cli/)を参照してください。

コンパイルでは、必ず先にアクティブなファイルが保存されるので、PDF は画面に見えている内容と一致します。エディタのみのビューにいる場合は、コンパイルすると分割ビューが表示され、結果を確認できます。

## コンパイルのオプション

**再コンパイル**の横の矢印で、コンパイルのオプションが開きます。メニューには、そのプロジェクトのエンジンで意味のあるオプションだけが表示されます。

| グループ | Tectonic の LaTeX | `latexmk` の LaTeX | Typst | Markdown |
|---|---|---|---|---|
| **自動コンパイル** | はい | はい | はい | はい |
| **コンパイルモード** (通常または高速) | はい | いいえ | いいえ | いいえ |
| **構文チェック** | はい | はい | いいえ | いいえ |
| **コンパイラ（このプロジェクト）** | はい | はい | いいえ | いいえ |
| **Typst のバージョン** / **フォント** / **ビルド** / **バリアント** | いいえ | いいえ | はい | いいえ |
| **コンパイルエラーの扱い** | はい | はい | いいえ | いいえ |

**コンパイルを停止**と**最初から再コンパイル**は、どのエンジンでもメニューの下部にあります。 **バリアント**グループは、Typst プロジェクトにビルドバリアントができると表示されます。

**コンパイラ（このプロジェクト）** では、 **Tectonic** が組み込みです。 **自動**は、システムの TeX を `latexmk` 経由で実行し、ソースからコンパイラを判断します。 **pdfLaTeX** / **XeLaTeX** / **LuaLaTeX** はそのコンパイラを固定し、こちらも `latexmk` 経由で実行します。また、**upLaTeX** と **pLaTeX** は日本語の文書をコンパイルします。Tectonic 以外のどの選択肢にも TeX ディストリビューションが必要です。このコンピュータにない場合、どれかを選んだときに Oleafly が TinyTeX のインストールを提案します。[TeX が入っていないとき](/docs/latex-engines/#when-no-tex-is-installed)を参照してください。Typst のグループについては [Typst プロジェクト](/docs/typst/)を参照してください。

## 自動コンパイル

コンパイルのオプションで**自動コンパイル**を**オン**にするか、⌘K パレットで**自動コンパイルを有効にする**を実行します。既定ではオフで、すべてのプロジェクトに適用され、同じ操作でオフに戻せます。

LaTeX または Markdown プロジェクトでは、入力を止めて約 2.5 秒後に Oleafly が再コンパイルします。きっかけになるのは実際の編集だけです。タブを切り替えたり、ファイルを開いたりしても、再コンパイルされません。

Typst プロジェクトでは、自動コンパイルがライブプレビューになります。Oleafly は Typst のプロセスを 1 つ動かし続け、開いているファイルは入力を止めた少し後に自動で保存され、PDF は同じスクロール位置のまま更新されます。[自動コンパイルによるライブプレビュー](/docs/typst/#live-preview-with-auto-compile)を参照してください。

コンパイルが積み重なることはありません。自動コンパイルの実行中に編集すると、Oleafly はそれを止めて最新のテキストでやり直すので、PDF が早く追いつきます。次の場合は、コンパイルを最後まで実行させます。あなたやエージェントが開始したコンパイル、パッケージをダウンロードしているコンパイル、ほぼ終わっているコンパイル、それ自体が再開によるコンパイルの場合です。これらの場合は、後続のコンパイルがちょうど 1 つキューに入るので、最終的な PDF には最新の編集が反映されます。

## 進行状況を見る

ビルド中は、プレビューの上端に細い進行状況バーが表示され、最初の PDF ができる前は、パネルにおおよその進捗が割合で表示されます。ビルドが終わると、ツールバーにコンパイル時間と重大度を示すアイコンが付いた**ステータスチップ**が表示されます。

- 緑のチェック：正常にコンパイルされました。
- 琥珀色の三角：警告付きでコンパイルされました。PDF は得られます。
- 赤いバツ：エラー付きでコンパイルされました。

成功すると、プレビューは自動的に PDF に切り替わります。ログビューに切り替わるのは、本当の失敗（PDF ができなかった場合）だけです。

![失敗したコンパイルがエディタとログに表示され、修正して再コンパイルするところ。](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## ログを読む

![プレビューのツールバーの左側に、ログと前回のビルド時間があります。](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

プレビューのツールバー左側の**ログ**ボタンで、PDF とコンパイルログを切り替えられます。バッジにはエラー（赤）または警告（琥珀色）の数が表示されます。

- 上部に、解析された**診断リスト**。エラーや警告ごとに、その種類と、分かる場合は `l.42` のような行の参照が表示されます。フォントが表示できなかった文字は、**欠けている文字**にまとめられます。
- その下に、色分けされたコンパイラの生ログ全体。エラーは太字の赤、行の参照は強調表示、ファイルの入れ子はインデントで表されます。
- **ログをコピー**ボタンで全体をまとめてコピーでき、バグ報告やフォーラムへの投稿に使えます。ログ内で ⌘A のあとに ⌘C を押しても、すべてコピーできます。
- **ログをコピー**の隣の**消去**は、次にコンパイルするまで、ログとそのエラーを非表示にします。ビルドファイルは残り、次のコンパイルで新しいログが作成されます。

長いログも、10 万行あるものでもすぐに開き、空白が出ずにスクロールできます。

コンパイルエラーは、[リンターのパイプライン](/docs/editor/#the-built-in-latex-linter)を通じて、エディタ内で波線にもなります。また、エラーの修正を頼むと、[AI アシスタント](/docs/ai-chat/)が `get_log` ツールで同じログを読めます。

Typst のエラーは、Typst が報告した範囲そのままにエディタ上でマークされ、ソースの行と Typst 自身のヒントも表示されます。よくあるエラーには、何が起きたかを分かりやすく説明した文も付きます。

## パッケージとオフラインコンパイル

Tectonic は、文書が初めて必要とした時点で LaTeX パッケージをダウンロードし、ローカルにキャッシュします。そのコンピュータでの最初のコンパイルでは、よく使われるパッケージもまとめて取得します。その最初のコンパイルは遅くなることがあり、ネットワーク接続が必要です。以降のコンパイルではキャッシュを使います。Oleafly のパッケージミラーが失敗した場合、コンパイルはアップストリームの取得元に切り替わり、ログにもそのことが表示されます。

設定の「一般」またはコマンドパレットにある**オフラインモード**を使うと、Tectonic についてはこれが保証されます。コンパイラは `--only-cached` で実行され、パッケージを取得することは決してありません。キャッシュにないパッケージが必要な文書は、可能な場合はファイル名を示すメッセージで失敗し、**オフにしてコンパイル**を選ぶと、オフラインモードをオフにして再びコンパイルします。

オフラインモードは Typst にも適用されます。オンの間、Typst はパッケージをダウンロードできないため、すべての `@preview` パッケージが、すでにキャッシュにあるか、プロジェクトの `typst-packages` フォルダに取り込まれている必要があります。[Typst Universe のパッケージ](/docs/typst/#packages-from-typst-universe)を参照してください。Markdown プロジェクトはオフラインモードの対象外で、ログにもそのことが表示されます。

`latexmk` は、お使いのマシンにすでにインストールされている TeX ディストリビューションを使います。Oleafly はまず、MacTeX、TeX Live、MiKTeX、TinyTeX などのシステムのディストリビューションを確認し、**設定 → エンジン → LaTeX** では、コンパイルに使っているものに**使用中**と表示されます。どれもない場合は、アプリが独自の TinyTeX を用意して管理できます。MiKTeX で `latexmk` を実行するには Perl も必要です。[MiKTeX と Perl](/docs/latex-engines/#miktex-and-perl)を参照してください。システムの TeX のプロセスは、あなたのユーザーアカウントで読めるファイルを読み取れるため、`latexmk` は信頼できるプロジェクトでのみ使ってください。

`latexmk` のビルドで `.sty`、`.cls`、参考文献スタイル、フォントファイル、babel の言語ファイル、TikZ のライブラリなどの TeX ファイルが見つからない場合、Oleafly はエラーメッセージに**探してインストール**を表示することがあります。ファイル名とパッケージ名は異なることがよくあります。たとえば `tikz.sty` は TeX Live のパッケージ `pgf` に含まれます。Oleafly はその所属パッケージを特定し、`tlmgr` でインストールし、パッケージ一覧を更新して、再コンパイルします。Debian、Ubuntu、Fedora では、TeX Live はシステムのパッケージマネージャが管理しているため、Oleafly は代わりに `apt` か `dnf` のコマンドを示します。先に検索したい場合や、パッケージを手動で管理したい場合は、 **設定 → エンジン → LaTeX** の**パッケージ**の一覧を使ってください。

## 制限と安全装置

- プロジェクトごとに、コンパイルは同時に 1 つだけ実行され、最新のものだけを残すキューで処理されます。新しい要求が古い要求に取って代わるので、ビルド中にプロジェクトを切り替えても間違った PDF が表示されることはなく、入力中にコンパイルが殺到することもありません。
- 新しい要求に取って代わられたビルドやタイムアウトしたビルドは、実際にキャンセルされます。Oleafly は、どのプラットフォームでも、コンパイラのプロセスツリー全体を終了させ、バックグラウンドで動かし続けることはありません。
- 5 分を超えて続くコンパイルは、延々と動き続けるのではなく、停止されます。Tectonic がまだパッケージをダウンロードしている間は、ダウンロードのたびに制限が先へ延び、合計で最大 30 分になります。Markdown から PDF へのビルドは 15 分、Quarto と Calepin は 1 時間です。
- 結果には要求に紐づいた識別子が付くので、順序が入れ替わって終わった古い PDF は、表示されずに拒否されます。

## よくある失敗と簡単な対処

- **オフラインモードでの「パッケージがありません」**：メッセージの**オフにしてコンパイル**を選ぶか、1 回のコンパイルだけオフラインモードをオフにしてパッケージを取得・キャッシュし、その後オンに戻します。
- **「このコンパイラには動作する TeX ディストリビューションが必要です」**：pdfLaTeX などの `latexmk` のコンパイラはこのコンピュータに TeX が必要なので、TeX がない状態で選ぶとこのダイアログが開きます。**TinyTeX をダウンロードして使う**を選ぶか、**Tectonic に戻す**を選んで組み込みのエンジンに戻します。すでにこの理由でコンパイルが失敗している場合、プレビューには**TinyTeX をダウンロードして使う**と **Tectonic を使う**が表示されます。[TeX が入っていないとき](/docs/latex-engines/#when-no-tex-is-installed)を参照してください。
- **MiKTeX での「latexmk には Perl が必要です」**：Strawberry Perl をインストールするか、独自の Perl が付いてくる TinyTeX をインストールします。[MiKTeX と Perl](/docs/latex-engines/#miktex-and-perl)を参照してください。
- **`latexmk` のビルドでファイルが見つからない**：**探してインストール**を使います。検索に失敗した場合は、**設定 → エンジン → LaTeX** の**パッケージ**の一覧で、ファイル名またはパッケージ名を検索します。Debian、Ubuntu、Fedora では、`apt` か `dnf` でインストールします。MiKTeX のパッケージは MiKTeX Console で管理します。
- **upLaTeX や pLaTeX がインストールされていない**：表示されたら**日本語対応をインストール（約 450 MB）**を選ぶか、メッセージに示されたコマンドを実行します。[日本語の文書: upLaTeX と pLaTeX](/docs/latex-engines/#japanese-documents-uplatex-and-platex)を参照してください。
- **PDF からテキストが欠けている**（韓国語、中国語、日本語であることが多い）：フォントにそれらの文字のグリフがなく、TeX は失敗させずに省いています。Oleafly が警告を出し、ログには貼り付けて使える設定が示されます。[PDF から文字が欠けるとき](/docs/latex-engines/#characters-missing-from-the-pdf)を参照してください。Typst については [文字が四角で表示されるとき](/docs/typst/#characters-that-show-as-boxes)を参照してください。
- **索引、用語集、記号一覧が PDF にない**：Tectonic は `makeindex` を実行できません。プロジェクトを `latexmk` に切り替えるか、外部ツールが不要な `\makenoidxglossaries` で用語集を作ります。`latexmk` では、`xindy` や `\newglossary` で作る一覧は作成されません。
- **コンパイルが時間切れになった**：もう一度コンパイルします。パッケージがまだダウンロード中だった場合は、ダウンロードが止まったところから再開されます。Tectonic で長い下書きを扱う場合は、**コンパイルモード**を**高速**にします。
- **Tectonic での EPS 図、強制された `pdftex` ドライバ、見つからないバンドルファイル**：エンジンのダイアログが開きます。開かないとき、または閉じてしまったときは、**エンジンを選択**を選びます。[Tectonic では足りないとき](/docs/latex-engines/#when-tectonic-isnt-enough)に、各ビューでの場所が載っています。**おすすめ**と表示された選択肢を選んでください。Oleafly が動作する TeX ディストリビューションを見つけたときはシステムの LaTeX、見つからないときは **TinyTeX をダウンロードして使う**です。パッケージが見つからない場合は、切り替え後に Oleafly がインストーラーへ進めます。
- **`minted`、PythonTeX、`\write18` がブロックされる**：プロジェクト内のすべてのファイルを信頼できる場合は、エディタ上部のバナーで**外部コマンドを許可**を選びます。[外部コマンドを許可する](/docs/latex-engines/#allow-external-commands)を参照してください。
- **Tectonic でパッケージのダウンロードに失敗した**：接続を確認し、メッセージの**もう一度コンパイル**を選びます。Oleafly はミラーのあとにアップストリームの取得元をすでに試していて、ダウンロードは止まったところから再開されます。コンピュータがオフラインだった場合は、接続が戻ると自動でもう一度コンパイルされます。
- **「Typst 0.13.1 がインストールされていません」**：プロジェクトが、このコンピュータにない Typst のバージョンを固定しています。プレビューで **Typst 0.13.1 をダウンロード**を選ぶか、既定のバージョンの **Typst を使う**を選んで、固定を外します。[固定したバージョンがないとき](/docs/typst/#when-a-pinned-version-is-missing)を参照してください。
- **未定義の引用や参照の警告**：[プリフライト](/docs/preflight/#six-independent-checks)が、ファイルと行を付けてすべて特定します。
- **解釈できないエラー**：AI に頼みます。「LaTeX のエラーを修正して」と頼むと、コンパイル、ログの読み取り、的を絞った編集、再コンパイルというループが実行されます。選択中の[承認ポリシー](/docs/ai-chat/)が適用されます。

## ほかのドキュメントエンジン

LaTeX のコンパイラの選択は、プロジェクトのドキュメントエンジンとは別のものです。

- **Typst プロジェクト**は、組み込みの Typst 0.15.1 か、プロジェクトが固定したバージョンでコンパイルされます。[Typst プロジェクト](/docs/typst/)を参照してください。
- **Markdown プロジェクト**は、管理された Pandoc を使い、PDF エンジンに Tectonic を使って PDF にビルドされます。
- **Quarto プロジェクト**は、`.qmd` と `.Rmd` のファイルを Quarto で PDF またはウェブページにレンダリングします。[Quarto](/docs/engines/#quarto)を参照してください。
- **Calepin プロジェクト**は、Typst の文書内のコードを Calepin で実行してから、組み込みの Typst で PDF をビルドします。[Calepin](/docs/engines/#calepin)を参照してください。どちらのエンジンも、あなたが[許可する](/docs/engines/#allow-code-in-a-project)まで、プロジェクトのコードを実行しません。
- **タグ付きのアクセシブルな PDF** には、システムの TeX、または Oleafly が管理する TinyTeX による LuaLaTeX を使います。[LaTeX のエンジンとパッケージ](/docs/latex-engines/)を参照してください。Typst 0.14 以降は、追加の手順なしにすべての PDF にタグが付きます。

エンジンはプロジェクトを作成するときに決める、プロジェクトごとの選択で、インターフェースもそれに合わせて変わります。エンジンが対応していない操作は、失敗するまま放置されるのではなく、非表示になります。LaTeX プロジェクトを Typst に移すには、[新しい Typst プロジェクトに変換](/docs/typst/#convert-a-latex-project-to-typst)します。

## 成功したビルドのソースを残す

[チェックポイント](/docs/checkpoints/)を有効にすると、コンパイルに成功したときのソースが保存されます。手動の Git のワークフローを変えずに、以前のビルドを比較したり復元したりできます。

コンパイル済みの PDF そのものをプロジェクトフォルダに残すには、プレビューの保存メニューで[コンパイル時に PDF を同期](/docs/pdf-preview/#sync-pdf-on-compiles)をオンにします。
