# Рушії та пакунки LaTeX

Виберіть Tectonic або компілятор через latexmk, скористайтеся наявним дистрибутивом TeX або встановіть керований Oleafly TinyTeX.

Oleafly постачається з Tectonic і вміє також компілювати через `latexmk`. Меню компілятора проєкту керує щоденними збірками. **Налаштування → Рушії** показує дистрибутиви TeX і пакунки, доступні на вашій машині.

## Tectonic: рушій на кожен день

**Tectonic** — типовий рушій компіляції, доки ви не виберете інший у пункті **Типовий рушій компіляції** в **Налаштування → Рушії → LaTeX**. Він не потребує окремого встановлення, довантажує пакунки за потреби та кешує їх для роботи поза мережею. Він добре пасує більшості проєктів і залишається доступним, навіть коли системного дистрибутива TeX немає. Див. [Типовий рушій для нових проєктів](/docs/engines/#set-a-default-for-new-projects).

Для **тегованих PDF** використовуйте робочий процес LuaLaTeX. Теги описують структуру документа для допоміжних технологій. Огляньте результат у Передперевірці після компіляції.

### Шрифти на вбудованому рушії

Tectonic заснований на XeTeX, який читає файли шрифтів напряму. Oleafly коригує кілька речей, щоб документи, написані для pdfLaTeX, зберігали свої шрифти й текст:

- Times, Helvetica, Courier, Palatino, Bookman, New Century Schoolbook і Avant Garde використовують свої версії TeX Gyre замість того, щоб відкочуватися до Latin Modern.
- `\usepackage[T1]{fontenc}` на цьому рушії ламає набрані наголоси й символи, тож Oleafly тримає документ на тексті Unicode. Якщо шрифт, який використовує документ, існує лише в T1, документ лишається на T1, а компіляція попереджає, що такі символи, як ß, §, «, фігурні лапки та €, можуть надрукуватися неправильно або зникнути. Попередження дає варіант рядка, який завантажує T1 лише під pdfLaTeX:

  ```latex
  \usepackage{iftex}
  \ifPDFTeX
    \usepackage[T1]{fontenc}
  \fi
  ```

- Документ, що задає `\pdfoutput=1`, як просить arXiv, компілюється як є.
- Документ `ctex`, що не задає `fontset`, отримує шрифти Fandol, тож виглядає однаково на кожному комп’ютері. Додайте `fontset=mac` до параметрів класу, щоб використати власні шрифти Mac.
- Шрифти, що постачаються з вбудованим рушієм, шукаються за назвою файла. `\setmainfont{UnBatang}` завершується помилкою, і вона радить написати натомість `UnBatang.ttf`.

Режим офлайн пропускає коригування шрифтів і кодування, тож збірка такого документа поза мережею може виглядати інакше, ніж у мережі.

## latexmk і системний TeX

Виберіть pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX або pLaTeX у меню компілятора проєкту, коли проєкт залежить від традиційного робочого процесу TeX Live або MiKTeX. Oleafly запускає ці компілятори через `latexmk`. **Авто** читає головний файл і обирає один: рядок `% !TeX program = xelatex` угорі має перевагу, далі японські класи, далі пакунки, яким потрібен XeLaTeX або LuaLaTeX, як-от `fontspec`, `ctex`, `xeCJK` чи `luatexko`. Якщо головний файл не вирішує справи, Авто також перевіряє `latexmkrc` у проєкті та файли, які завантажує преамбула. Усе інше використовує pdfLaTeX. Якщо пакунку потрібен інший компілятор, ніж обрав Авто, компіляція пропонує перемкнутися, наприклад кнопкою **Використати XeLaTeX**.

Цей набір інструментів можна забезпечити двома способами:

1. **Використати наявне встановлення.** Oleafly виявляє MacTeX, TeX Live, MiKTeX і TinyTeX у вашій системі. Він шукає в тому самому `PATH`, яким користується ваш термінал, а у Windows ще й у системних та користувацьких налаштуваннях `Path`, тож TeX, встановлений вручну, знаходиться, навіть коли застосунок відкрито з Dock чи меню «Пуск». Системне встановлення має пріоритет над керованою копією Oleafly лише тоді, коли його каталог бінарних файлів містить `latexmk`, pdfLaTeX, XeLaTeX, LuaLaTeX, `kpsewhich` і Biber. Часткове встановлення не може непомітно обійти робочий керований TinyTeX.
2. **Встановити керований TinyTeX.** Завантаження важить близько 250 МБ і не потребує прав адміністратора. Див. [Встановлення й оновлення TinyTeX](#install-and-update-tinytex).

**Керування дистрибутивами TeX** у **Налаштування → Рушії → LaTeX** перелічує кожен дистрибутив, який знайшов Oleafly. **Використовується** позначає той, яким компілює `latexmk`, а бейдж **latexmk** позначає кожен, що може компілювати. Виберіть **Використовувати для компіляції** в іншому рядку, щоб перейти на нього. Вибраний вами рядок тоді показує **Автоматично**, що дає Oleafly знову обирати самому: спершу повний системний TeX, потім TinyTeX.

Якщо TeX установлено в теці, де Oleafly не шукає, натисніть **Вибрати теку TeX** і вкажіть теку з `latexmk` або теку з роком TeX Live над нею, як-от `texlive/2026`. Oleafly знаходить `latexmk` усередині й компілює з цим встановленням, яке список позначає **Використовується**. **Автоматично** скасовує вибір. Якщо в теці немає `latexmk`, повідомлення каже, яку теку вибрати натомість.

`latexmk` — не пісочниця файлової системи. Навіть коли shell-команди заблоковано, TeX може читати файли, доступні вашому обліковому запису. Oleafly також вимикає файли `.latexmkrc` проєкту, користувача й системи, бо це виконуваний код Perl. Використовуйте системний TeX лише для проєктів, яким довіряєте. Імпортований проєкт переходить на системний TeX лише коли ви його виберете — або як типовий рушій компіляції, або з меню компілятора проєкту. Тека, відкрита на місці, лишається на Tectonic, доки ви їй не довірите.

### Коли TeX не встановлено

Вибір pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX, pLaTeX чи Авто на комп’ютері без робочого дистрибутива TeX відкриває діалог із заголовком **Цьому компілятору потрібен робочий дистрибутив TeX**. Він показує три варіанти в такому порядку:

- **Завантажити TinyTeX** із позначкою **Рекомендовано**. **Завантажити і використати TinyTeX** встановлює TinyTeX і компілює проєкт із ним.
- **Використовувати системний LaTeX (latexmk)**, де сказано, що дистрибутив TeX не знайдено або чому той, що є на цьому комп’ютері, не може компілювати. Кнопки в нього немає.
- **Далі використовувати Tectonic**. **Повернутися до Tectonic** повертає проєкт до вбудованого рушія.

Якщо ви спершу компілюєте, перегляд пропонує той самий вихід: **Завантажити і використати TinyTeX**, **Використати Tectonic** і **Відкрити налаштування рушія**. Компіляція, яку ви запускаєте, поки TinyTeX ще завантажується, чекає і стартує сама, коли встановлення завершується.

Та сама пропозиція з’являється, коли дистрибутив TeX є, але в ньому немає `latexmk`. Коли в дистрибутиві бракує `latexmk`, вибраного компілятора чи Biber, повідомлення також називає, що встановити, якщо Oleafly знає дистрибутив, наприклад `sudo tlmgr install latexmk` у MacTeX або `sudo apt install latexmk` в Ubuntu.

У спільному проєкті кнопка називається **Використати Tectonic для всіх**, бо компілятор зберігається в проєкті й змінюється для кожного співавтора. Встановлення TinyTeX змінює лише ваш комп’ютер.

### Встановлення й оновлення TinyTeX

Відкрийте **Налаштування → Рушії → LaTeX** і виберіть **Завантажити TinyTeX (~250 МБ)** у розділі **Керування дистрибутивами TeX** або скористайтеся пропозицією в діалозі компіляції. TinyTeX — це компактний TeX Live, якому не потрібні права адміністратора. Журнальні шаблони можуть згодом додати пакунки, загалом приблизно до 1 ГБ, а Oleafly перед стартом перевіряє, чи є приблизно 2 ГБ вільного місця на диску. TinyTeX встановлюється в `~/.oleafly/tinytex`.

- **Скасувати** зупиняє завантаження і зберігає те, що вже надійшло. Тоді кнопка називається **Продовжити завантаження** і показує вже завантажений обсяг. Вихід з Oleafly під час встановлення так само призупиняє його, і воно триває, коли ви наступного разу відкриєте застосунок.
- Завантаження надходить спершу з дзеркала Oleafly, потім із GitHub. Якщо джерело не відповідає або хвилину не надсилає даних, Oleafly переходить до наступного й продовжує з місця зупинки. **Налаштування → Завантаження → Джерела** змінює, звідки беруться завантаження. Див. [Вкладка «Джерела»](/docs/settings/downloads/#sources-tab).
- Коли керований TinyTeX старіший за випуск, якого чекає ця версія Oleafly, його рядок показує **Оновити**. **Вилучити** видаляє його.

Якщо інший дистрибутив уже **Використовується**, встановлення TinyTeX не перемикає на нього. Виберіть **Використовувати для компіляції** в рядку TinyTeX, коли хочете, щоб він компілював.

У Linux TinyTeX працює на системному Perl. Oleafly перевіряє наявність Perl, перш ніж щось завантажувати. Якщо Perl або один із його стандартних модулів відсутній, повідомлення дає команду для встановлення: `sudo apt install perl`, `sudo dnf install perl` або `sudo pacman -S perl`.

У Windows TeX Live не може працювати з теки, назва якої містить літери з діакритикою чи нелатинські літери. Якщо ваша тека користувача має таку назву, Oleafly натомість кладе TinyTeX у теку під ProgramData. Якщо антивірус тримає файл відкритим, поки TinyTeX переміщується на місце, Oleafly пробує ще раз, а якщо все одно не може завершити, зачекайте хвилину й повторіть встановлення.

### MiKTeX і Perl

`latexmk` у MiKTeX — це скрипт Perl, а MiKTeX не містить Perl. Без Perl «Налаштування» позначають MiKTeX написом **latexmk потрібен Perl**, і Oleafly компілює натомість через TinyTeX, якщо його встановлено. Коли більше нічого використати, компіляція зупиняється і дає три шляхи далі: встановити TinyTeX із **Налаштування → Рушії → LaTeX**, який приносить власний Perl, встановити Strawberry Perl або повернути проєкт на Tectonic.

MiKTeX керує своїми пакунками в MiKTeX Console, тож список **Пакунки** і **Знайти і встановити** до нього не застосовуються. MiKTeX також не перетворює рисунки EPS під час компіляції, тож спершу перетворіть їх на PDF або скористайтеся TinyTeX.

### Японські документи: upLaTeX і pLaTeX

Виберіть **upLaTeX** або **pLaTeX** у розділі **Компілятор (цей проєкт)** для японського документа або залиште компілятор на **Авто**. Авто обирає pLaTeX для `jsarticle`, `jsbook` і `jsreport` (upLaTeX, коли клас має параметр `uplatex`), upLaTeX для класів `uj` і `jlreq`, а LuaLaTeX для `ltjsarticle` та інших документів LuaTeX-ja.

Обидва компілятори потребують японської підтримки TeX Live. Коли її бракує в керованому TinyTeX або в TeX Live, до якого Oleafly може писати, невдала компіляція пропонує **Встановити підтримку японської мови (близько 450 МБ)**. Це встановлює її і компілює знову. На інших установках повідомлення називає команду для вашого дистрибутива, наприклад `sudo apt install texlive-lang-japanese`.

## Коли Tectonic не вистачає

Деякі документи потребують того, чого вбудований рушій Tectonic не робить, як-от рисунків EPS або примусового драйвера `pdftex`. Коли перша компіляція після відкриття проєкту або компіляція, яку ви запускаєте самі, натрапляє на одне з цього, діалог вибору рушія відкривається сам. Коли компіляцію запускає автокомпіляція чи агент, діалог лишається закритим, а натомість з’являється **Вибрати рушій**. Виберіть його, щоб відкрити діалог. Кнопка лишається до наступної компіляції, тож вона також знову відкриває діалог після того, як ви його закрили. Де її шукати, залежить від вигляду:

- Після невдалої компіляції вона праворуч на панелі інструментів перегляду, поки відкрито **Журнали**. Перегляд сам перемикається на **Журнали**, коли компіляція не створила PDF. Якщо PDF усе ще показано, виберіть **Журнали**, щоб побачити кнопку.
- У порожньому перегляді вона поруч із **Скомпілювати ще раз**.
- У вигляді лише редактора, коли PDF у власному вікні або після успішної компіляції, вона ліворуч від **Скомпілювати знову**.

Діалог має заголовок **Ця компіляція потребує більшого, ніж вбудований рушій** і перелічує знайдені проблеми. Першим іде варіант із позначкою **Рекомендовано**:

- **Завантажити TinyTeX** з’являється, коли робочого дистрибутива TeX не встановлено. Його кнопка **Завантажити і використати TinyTeX** встановлює TinyTeX, переводить проєкт на `latexmk` і компілює знову.
- **Використовувати системний LaTeX (latexmk)** має кнопку **Використати системний LaTeX**, яка переводить проєкт на `latexmk` на знайденому Oleafly дистрибутиві TeX. Якщо документу потрібен pdfLaTeX, варіант називається **Використовувати pdfLaTeX із системного LaTeX (latexmk)**, а його кнопка — **Перейти на pdfLaTeX і скомпілювати знову**. Коли TeX не встановлено, цей варіант кнопки не має.
- **Далі використовувати Tectonic** має кнопку **Залишити Tectonic**, яка лишає проєкт на вбудованому рушії. Коли перехід усунув би проблеми, які перелічує діалог, цей варіант каже, що вони не зникнуть.

Після того як ви залишили Tectonic, ті самі проблеми більше не відкривають діалог і не показують **Вибрати рушій** для цього проєкту на цьому комп’ютері. Щоб перейти пізніше, виберіть компілятор у **Компілятор (цей проєкт)**.

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

## Дозволити зовнішні команди

Пакунки, як-от `minted` і PythonTeX, та документи, що використовують `\write18`, запускають інші програми під час компіляції. Oleafly типово це блокує. Коли компіляцію заблоковано або журнал показує, що проєкт потребує цих команд, банер над редактором пропонує **Дозволити зовнішні команди**.

Вбудований рушій теж зберігає це блокування. Tectonic запускається поза текою проєкту, а Biber, що постачається з Oleafly, сприймає налаштування бібліографії документа як звичайний текст і під час компіляції пропускає `biber.conf`.

Дозволяйте зовнішні команди лише для проєкту, файлам якого ви довіряєте, бо тоді LaTeX може запускати будь-яку програму з вашими правами. Дозвіл працює лише із системним LaTeX і лишається на цьому компʼютері. Його ніколи не зберігають у `project.json` і не надсилають у Git, тож співавтор мусить дозволити його на власному компʼютері. У [спільному проєкті](/docs/collaboration/) Oleafly попереджає вас перед увімкненням, бо будь-хто, хто може редагувати проєкт, зміг би запускати програми на вашому компʼютері під час вашої компіляції. Повернення проєкту на Tectonic або його видалення прибирає дозвіл. У теці, відкритій на місці, спершу довірте цій теці. Довіра до теки сама собою не дозволяє зовнішні команди.

Коли рушій наявний, кнопка **Скомпілювати з тегами і перевірити** панелі [Передперевірки](/docs/preflight/) може за один крок створити тегований PDF через LuaLaTeX і одразу перевірити його. Волієте власний набір інструментів? **Підготувати до доступного експорту** в Передперевірці перетворює ваше джерело для тегування, і ви компілюєте його будь-яким LuaLaTeX із TeX Live 2026 або з TeX Live, оновленого у листопаді 2025 року чи пізніше, поза застосунком.

## Символи, яких бракує в PDF

TeX пропускає кожен символ, для якого в його шрифті немає гліфа, і компіляція все одно проходить успішно. Корейський, китайський чи японський абзац може вийти порожнім без жодної помилки. Oleafly читає журнал після кожної компіляції, тож коли символи пропадають, ви отримуєте сповіщення один раз на проєкт, журнал перелічує їх у розділі **Відсутні символи**, а попередження називає кілька з них.

На вбудованому рушії та XeLaTeX попередження також дає налаштування для кожного знайденого письма на основі шрифтів, що постачаються з вбудованим рушієм. Вставте потрібне в преамбулу:

```latex
% Korean
\usepackage[space]{xeCJK}
\setCJKmainfont[AutoFakeBold]{UnBatang.ttf}

% Simplified Chinese
\usepackage{xeCJK}
\setCJKmainfont[AutoFakeBold]{gbsn00lp.ttf}

% Traditional Chinese
\usepackage{xeCJK}
\setCJKmainfont[AutoFakeBold]{bsmi00lp.ttf}

% Japanese
\usepackage{xeCJK}
\setCJKmainfont{ipaexm.ttf}[BoldFont=ipaexg.ttf]
```

Параметр `space` зберігає пробіли між корейськими словами, які звичайний `xeCJK` відкидає.

`CJKutf8` і пакунок `CJK` працюють лише з pdfLaTeX. Проєкт, що завантажує їх на вбудованому рушії, компілюється без китайського, японського чи корейського тексту, тож сповіщення пропонує **Вибрати рушій**, що відкриває перехід на pdfLaTeX. Можна також прибрати пакунок і його середовище `CJK` та скористатися одним із налаштувань вище.

Документ `ctex` на Mac, що використовує власні шрифти Mac, може змусити macOS спитати, чи завантажувати шрифт, і компіляція чекає на вашу відповідь. Дайте відповідь у діалозі й скомпілюйте знову або додайте `fontset=fandol` до параметрів `\documentclass`.

Іншим відсутнім символам, як-от символ чи літера з іншого письма, потрібен шрифт, який їх має. Перемкніться на такий у преамбулі. Для проєктів Typst див. [Символи, що показуються як квадрати](/docs/typst/#characters-that-show-as-boxes).

## Керування пакунками

Під станом рушія розташований список **Пакунки** з фільтром для боку LuaLaTeX, що працює через `tlmgr`:

- Почніть зі списку пропонованих пакунків або введіть щонайменше два символи й виберіть **Шукати в TeX Live**, щоб опитати повний каталог.
- Шукайте за назвою пакунка або за файлом, який він містить. Oleafly показує пакунок TeX Live, якому належить файл, коли назви різняться.
- **Додайте** або **Вилучіть** пакунок одним клацанням. Встановлені рядки показують, чи перебуває пакунок у системному дереві, у вашому особистому дереві чи в обох.
- Перевіряйте бейдж тегування перед доступним експортом: **тегування: обережно** позначає пакунки, що можуть знизити якість тегів, а **ламає тегування** — відомі конфлікти.

Це керування пакунками стосується дистрибутивів TeX Live і TinyTeX, які використовує `latexmk`. Tectonic керує власним кешем пакунків. Для MiKTeX скористайтеся MiKTeX Console.

### Відновлення після відсутнього файла

Пакунок не завжди названий за файлом, згаданим у журналі компіляції. Наприклад, `tikz.sty` встановлює пакунок `pgf`. Встановлення вгаданого пакунка з назвою `tikz` завершилося б помилкою.

Коли компіляція `latexmk` повідомляє про відсутній файл, скористайтеся **Знайти і встановити** в повідомленні. Це охоплює пакунки, класи, стилі бібліографії, файли шрифтів, файли мов babel і бібліотеки TikZ. Oleafly запитує в TeX Live, якому пакунку належить файл, встановлює цей пакунок і компілює знову. Якщо жоден пакунок TeX Live не має цього файла, він, імовірно, прийшов із шаблоном вашого університету чи видавця, тож додайте його до проєкту з оригінального шаблону. Якщо файл мають кілька пакунків, повідомлення перелічує їх, щоб ви вибрали той, що потрібен вашому шаблону. Якщо каталог недоступний або встановлення не виправляє компіляцію, повідомлення каже, що саме трапилося.

Якщо ви пробуєте змінити системне встановлення без дозволу, Oleafly може натомість встановити пакунок у ваше особисте дерево TeX, а якщо дерева ще немає, спершу його налаштовує. Рядок пакунка показує, куди він потрапив. Вилучення пакунка-власника також вилучає інші файли, які він надає, тож прочитайте примітку **Входить до**, перш ніж вилучати.

### Підтримка роботи tlmgr і старіших випусків TeX Live

`tlmgr`, менеджер пакунків TeX Live, може відстати від онлайн-репозиторію TeX Live і тоді відмовляється щось встановлювати, доки не оновить себе. Для TinyTeX, яким керує Oleafly, Oleafly оновлює `tlmgr` і повторює встановлення. На TeX Live чи TinyTeX, які ви встановили самі, повідомлення радить виконати `tlmgr update --self`.

Щойно репозиторій переходить на новий рік TeX Live, старіша установка не може з нього встановлювати. Тоді Oleafly встановлює з остаточного архіву вашого випуску. Якщо архів теж не має пакунка, повідомлення просить оновити TeX Live або скористатися **Оновити** біля керованого TinyTeX у «Налаштуваннях».

### Вибір, звідки беруться пакунки

`tlmgr` встановлює пакунки з репозиторію TeX Live. Керований Oleafly TinyTeX використовує найближче дзеркало CTAN, якщо ви не виберете конкретний репозиторій, як-от дзеркало CTAN вашого університету, у розділі **Репозиторій пакунків TeX** у **Налаштування → Завантаження → Джерела**. TeX Live, який ви встановили самі, зберігає власний репозиторій, доки ви не введете там адресу. Oleafly передає адресу `tlmgr` під час кожного запуску й ніколи не змінює його збережену конфігурацію.

Пошук пакунка, якому потрібно звернутися до репозиторію, на повільному з’єднанні може тривати довго. Oleafly чекає до 10 хвилин, а якщо здається, повідомлення називає репозиторій, на який чекало. Див. [Вкладка «Джерела»](/docs/settings/downloads/#sources-tab).

### TeX Live із дистрибутива Linux

У Debian, Ubuntu і Fedora TeX Live постачається системним менеджером пакунків, тож Oleafly не додає до нього пакунків. Список **Пакунки** радить користуватися `apt` або `dnf`, а для відсутнього файла замість **Знайти і встановити** з’являється сповіщення з підказкою:

- У Debian і Ubuntu знайдіть пакунок через `apt-file search` та ім’я файла або встановіть усе через `sudo apt install texlive-full`.
- У Fedora сповіщення дає команду `sudo dnf install 'tex(file.sty)'` для відсутнього файла.

Коли TeX дистрибутива неповний, сповіщення також пропонує **Завантажити TinyTeX (~250 МБ)**, пакунками якого Oleafly може керувати. У Debian і Ubuntu, якщо ви налаштували особисте дерево через `tlmgr init-usertree`, Oleafly встановлює пакунки в це дерево.

## Додати пакунок із редактора

Виберіть **Пакети LaTeX**, піктограму пакунків на панелі інструментів редактора LaTeX, щоб шукати в CTAN, не полишаючи документа. Кожен результат показує, чи документ уже його завантажує (**У документі**). У проєкті `latexmk` також видно, чи є він у вашому дистрибутиві TeX (**Встановлено**), а **Встановити** додає відсутній через `tlmgr`. Із TeX Live з дистрибутива Linux діалог натомість радить встановлювати пакунки через `apt` або `dnf`.

**Додати до преамбули** записує рядок `\usepackage` у преамбулу. **Параметри** дозволяє спершу додати параметри пакунка, а **Копіювати рядок** натомість копіює рядок. У проєкті Tectonic встановлювати нічого: Tectonic завантажує пакунок при першому використанні в документі.

## Який рушій скомпілював мій PDF?

- **Компілятор (цей проєкт)** у меню компіляції, стрілка поруч із **Скомпілювати знову**, показує компілятор, збережений для поточного проєкту.
- Збірки Tectonic використовують вбудований рушій.
- Збірки pdfLaTeX, XeLaTeX, LuaLaTeX, upLaTeX і pLaTeX використовують `latexmk` і дистрибутив TeX, позначений у «Налаштуваннях» як **Використовується**.
- Тегований експорт Передперевірки використовує LuaLaTeX і записує у звичайне місце збірки.

## Шаблони та пакунки

Шаблони оголошують потрібні їм пакунки, і Tectonic довантажує їх при першій компіляції. Шаблони зі шрифтами за потреби обробляють їх окремо. Див. [Шаблони](/docs/templates/#on-demand-fonts-the-setup-badge).
