# Компіляція

Компілюйте проєкти LaTeX, Typst і Markdown, обирайте параметри компіляції для кожного рушія, читайте журнали й керуйте завантаженням пакунків поза мережею.

Новий проєкт LaTeX створюється на стандартному рушії компіляції із **Налаштування → Рушії → LaTeX**. Одразу після встановлення це **Tectonic**, рушій на основі XeTeX, що постачається разом із Oleafly. Ви можете також використовувати `latexmk`, коли проєкту потрібен традиційний інструментарій TeX, для одного проєкту або як типовий вибір. Проєкти Typst компілюються вбудованим Typst або іншою версією, яку зафіксував проєкт, а проєкти Markdown проходять через Pandoc і Tectonic. Компілятор LaTeX і версія Typst належать проєкту, тож зміна одного проєкту не впливає на інші.

## Запуск компіляції

![Скористайтеся «Скомпілювати знову» на панелі інструментів проєкту; стрілка поруч відкриває параметри компіляції.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵ (Ctrl+Enter), будь-де.
- Кнопка **Скомпілювати** у верхньому правому куті панелі інструментів. Після першого результату вона зветься **Скомпілювати знову**.
- **Скомпілювати знову** в палітрі команд ⌘K.
- Відкриття проєкту в поданні з панеллю PDF автоматично компілює один раз, тож ви одразу потрапляєте на свіжий перегляд.
- `oleafly build` у терміналі або скрипті. Див. [Інструмент командного рядка](/docs/cli/).

Компіляція завжди спочатку зберігає активний файл, тож PDF відповідає тому, що ви бачите. Якщо ви в поданні лише з редактором, компіляція показує розділене подання, щоб ви могли стежити за результатом.

## Параметри компіляції

Стрілка поруч із **Скомпілювати знову** відкриває параметри компіляції. Меню показує лише ті параметри, які щось дають для рушія проєкту.

| Група | LaTeX із Tectonic | LaTeX із `latexmk` | 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 Oleafly перекомпілює приблизно через 2,5 секунди після того, як ви перестали вводити текст. Спрацьовують лише справжні правки. Перемикання вкладок або відкриття файлів — ні.

У проєкті Typst автокомпіляція — це живий перегляд. Oleafly тримає запущеним один процес Typst, відкритий файл зберігається сам за мить після того, як ви перестали вводити текст, і PDF оновлюється на тій самій позиції прокручування. Див. [Живий перегляд з автокомпіляцією](/docs/typst/#live-preview-with-auto-compile).

Компіляції ніколи не накопичуються. Якщо ви редагуєте, поки триває автоматична компіляція, Oleafly зупиняє її і починає заново з вашим найновішим текстом, тож PDF наздоганяє швидше. Компіляції дають завершитися, коли її запустили ви або агент, коли вона завантажує пакунки, коли вона майже завершена або коли вона сама є перезапуском. У таких випадках у чергу ставиться рівно одна наступна компіляція, тож остаточний 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 у журналі також копіює все.
- **Очистити** поруч із **Копіювати журнал** ховає журнал і його помилки до наступної компіляції. Файли збірки залишаються, а наступна компіляція створює новий журнал.

Довгі журнали відкриваються одразу, навіть зі 100 000 рядків, і прокручуються без порожніх ділянок.

Помилки компіляції також стають хвилястими підкресленнями в редакторі через [конвеєр лінтера](/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 також потребує Perl для запуску `latexmk`; див. [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**, якщо надаєте перевагу спершу пошуку або керуванню пакунками вручну.

## Обмеження і запобіжники

- Для кожного проєкту одночасно виконується лише одна компіляція, у черзі, де виграє найновіший запит: новіші запити витісняють застарілі, тож перемикання проєктів посеред збірки ніколи не показує чужий PDF, і шторм компіляцій не утворюється, поки ви вводите текст.
- Витіснену збірку або збірку, що перевищила час, справді скасовано: Oleafly завершує усе дерево процесів компілятора, на кожній платформі, замість того щоб лишити його працювати у фоні.
- Компіляцію, що триває довше за 5 хвилин, зупиняють, а не дають їй крутитися вічно. Поки Tectonic ще завантажує пакунки, кожне завантаження пересуває ліміт далі, загалом до 30 хвилин. Markdown у PDF отримує 15 хвилин, а Quarto і Calepin — годину.
- Результати мають ідентичність, прив’язану до запиту, тож застарілий PDF від запізнілого завершення відхиляється, а не показується.

## Типові збої, швидкі виправлення

- **«Немає пакунка» в Режимі офлайн**: виберіть **Вимкнути й скомпілювати** у повідомленні або вимкніть Режим офлайн на одну компіляцію, щоб завантажити пакунок у кеш, і знову увімкніть.
- **«Цьому компілятору потрібен робочий дистрибутив TeX»**: pdfLaTeX та інші компілятори `latexmk` потребують TeX на цьому комп’ютері, тож вибір одного з них без TeX відкриває цей діалог. Виберіть **Завантажити і використати TinyTeX** або **Повернутися до Tectonic**, щоб повернутися до вбудованого рушія. Якщо компіляція вже завершилася невдачею з цієї причини, перегляд пропонує **Завантажити і використати TinyTeX** та **Використати Tectonic**. Див. [Коли TeX не встановлено](/docs/latex-engines/#when-no-tex-is-installed).
- **«latexmk потрібен Perl»** у MiKTeX: встановіть Strawberry Perl або TinyTeX, який постачається з власним. Див. [MiKTeX і Perl](/docs/latex-engines/#miktex-and-perl).
- **Відсутній файл у збірці `latexmk`**: скористайтеся **Знайти і встановити**. Якщо пошук не дав результату, знайдіть ім’я файла або пакунка у списку **Пакунки** в розділі **Налаштування → Рушії → LaTeX**. У Debian, Ubuntu або Fedora встановіть його через `apt` або `dnf`. Пакунками MiKTeX керують у MiKTeX Console.
- **upLaTeX або pLaTeX не встановлено**: виберіть **Встановити підтримку японської мови (близько 450 МБ)**, коли це пропонується, або виконайте команду, яку називає повідомлення. Див. [Японські документи](/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 установіть **Режим компіляції** на **Швидкий**.
- **Рисунок EPS, примусовий драйвер `pdftex` або відсутній файл пакета в Tectonic**: відкриється діалог рушія. Якщо він не відкрився або ви його закрили, виберіть **Вибрати рушій**. [Коли Tectonic не вистачає](/docs/latex-engines/#when-tectonic-isnt-enough) пояснює, де ця кнопка в кожному вигляді. Виберіть варіант із позначкою **Рекомендовано**: ваш системний LaTeX, коли Oleafly знаходить робочий дистрибутив TeX, або **Завантажити і використати 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** збираються в PDF через керований Pandoc, де рушієм PDF є Tectonic.
- **Проєкти Quarto** перетворюють файли `.qmd` і `.Rmd` за допомогою Quarto на PDF або вебсторінку. Див. [Quarto](/docs/engines/#quarto).
- **Проєкти Calepin** запускають код у документі Typst за допомогою Calepin, а потім збирають PDF вбудованим Typst. Див. [Calepin](/docs/engines/#calepin). Жоден із цих рушіїв не запускає код проєкту, доки ви [не дозволите це](/docs/engines/#allow-code-in-a-project).
- **Мічені доступні PDF** використовують LuaLaTeX через системну установку TeX або керований Oleafly TinyTeX. Див. [Рушії 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) у меню збереження перегляду.
