Компиляция
Компилируйте проекты LaTeX, Typst и Markdown, выбирайте параметры компиляции для каждого движка, читайте журналы и управляйте загрузкой пакетов без сети.
Новый проект LaTeX начинается с движка компиляции по умолчанию из Настройки → Движки → LaTeX. Из коробки это Tectonic, движок на базе XeTeX, который поставляется вместе с Oleafly. Можно также использовать latexmk, если проекту нужен традиционный инструментарий TeX — для одного проекта или в качестве значения по умолчанию. Проекты Typst компилируются встроенным Typst или другой версией, закреплённой в проекте, а проекты Markdown проходят через Pandoc и Tectonic. Компилятор LaTeX и версия Typst принадлежат проекту, поэтому изменение одного проекта не влияет на остальные.
Запуск компиляции
Заголовок раздела «Запуск компиляции»
- ⌘↵ (Ctrl+Enter), в любом месте.
- Кнопка Скомпилировать в правом верхнем углу панели инструментов. Как только у проекта появляется результат, она называется Скомпилировать заново.
- Скомпилировать заново в палитре команд ⌘K.
- Открытие проекта в представлении с панелью PDF автоматически запускает одну компиляцию, так что вы сразу попадаете на свежий предпросмотр.
oleafly buildв терминале или в скрипте. См. Инструмент командной строки.
Компиляция всегда сначала сохраняет активный файл, поэтому PDF соответствует тому, что вы видите. Если вы в режиме только редактора, компиляция включает разделённое представление, чтобы вы могли следить за результатом.
Параметры компиляции
Заголовок раздела «Параметры компиляции»Стрелка рядом с Скомпилировать заново открывает параметры компиляции. В меню показаны только те параметры, которые что-то дают для движка проекта.
| Группа | LaTeX с Tectonic | LaTeX с latexmk | Typst | Markdown |
|---|---|---|---|---|
| Автокомпиляция | Да | Да | Да | Да |
| Режим компиляции (обычный или быстрый) | Да | Нет | Нет | Нет |
| Проверки синтаксиса | Да | Да | Нет | Нет |
| Компилятор (этот проект) | Да | Да | Нет | Нет |
| Версия Typst, Шрифты, Сборка, Вариант | Нет | Нет | Да | Нет |
| Обработка ошибок компиляции | Да | Да | Нет | Нет |
Остановить компиляцию и Скомпилировать с нуля находятся внизу меню для каждого движка. Группа Вариант появляется, когда у проекта Typst есть варианты сборки.
В разделе Компилятор (этот проект) Tectonic встроен. Автоматически запускает системный TeX через latexmk и выбирает компилятор по исходнику. pdfLaTeX, XeLaTeX и LuaLaTeX закрепляют этот компилятор и тоже работают через latexmk, а upLaTeX и pLaTeX компилируют японские документы. Любой вариант, кроме Tectonic, требует дистрибутива TeX. Если на этом компьютере его нет, при выборе такого варианта Oleafly предлагает установить TinyTeX. См. Когда TeX не установлен. Группы для Typst описаны в разделе Проекты Typst.
Автокомпиляция
Заголовок раздела «Автокомпиляция»В параметрах компиляции переведите Автокомпиляцию в положение Включена или выполните команду Включить автокомпиляцию из палитры ⌘K. По умолчанию она выключена, действует на все проекты, и те же элементы управления отключают её обратно.
В проекте LaTeX или Markdown Oleafly перекомпилирует его примерно через 2,5 секунды после того, как вы перестанете печатать. Её запускают только реальные правки. Переключение вкладок или открытие файлов — нет.
В проекте Typst автокомпиляция — это живой предпросмотр. Oleafly держит запущенным один процесс Typst, открытый файл сохраняется сам через мгновение после того, как вы перестанете печатать, и PDF обновляется в той же позиции прокрутки. См. Живой предпросмотр с автокомпиляцией.
Компиляции никогда не накапливаются. Если вы правите текст во время автоматической компиляции, Oleafly останавливает её и начинает заново с вашим последним текстом, так что PDF догоняет быстрее. Компиляция даёт завершиться, если её запустили вы или агент, если она скачивает пакеты, если она почти закончена или если она сама является перезапуском. В этих случаях в очередь ставится ровно одна повторная компиляция, поэтому итоговый PDF всё равно отражает ваши последние правки.
Наблюдение за прогрессом
Заголовок раздела «Наблюдение за прогрессом»Во время сборки по верхней части предпросмотра проходит тонкая полоса прогресса, а пока первого PDF ещё нет, панель показывает оценку в процентах. Когда сборка завершается, на панели инструментов появляется индикатор статуса со временем компиляции и значком серьёзности:
- Зелёная галочка: успешная компиляция.
- Янтарный треугольник: компиляция с предупреждениями. PDF всё равно готов.
- Красный крест: компиляция с ошибками.
При успехе предпросмотр автоматически переключается на PDF. Только настоящий сбой (PDF не создан) переключает вас на представление «Журнал».

Чтение журнала
Заголовок раздела «Чтение журнала»
Кнопка Журнал слева на панели предпросмотра переключает между PDF и журналом компиляции, со значком, показывающим число ошибок (красный) или предупреждений (янтарный):
- Разобранный список диагностики сверху: каждая ошибка или предупреждение со своим типом и, когда она известна, ссылкой на строку
l.42. Символы, которые шрифты не смогли показать, собраны в группе Отсутствующие символы. - Ниже — полный исходный журнал компилятора с подсветкой: ошибки полужирным красным, ссылки на строки выделены, вложенность файлов показана отступами.
- Кнопка Копировать журнал забирает всё целиком для отчёта об ошибке или поста на форуме. ⌘A, а затем ⌘C в журнале тоже копирует всё.
- Очистить рядом с Копировать журнал скрывает журнал и его ошибки до следующей компиляции. Файлы сборки остаются, а следующая компиляция пишет новый журнал.
Длинные журналы открываются сразу, даже содержащие 100 000 строк, и прокручиваются без пустых зон.
Ошибки компиляции также становятся волнистыми подчёркиваниями в редакторе через конвейер линтера, а ИИ-ассистент может прочитать тот же журнал своим инструментом get_log, когда вы просите его исправить ошибки.
Ошибки Typst отмечаются в редакторе ровно в том диапазоне, о котором сообщает Typst, с исходной строкой и подсказками самого Typst. Для частых ошибок также даётся простое объяснение, что пошло не так.
Пакеты и офлайн-компиляция
Заголовок раздела «Пакеты и офлайн-компиляция»Tectonic скачивает пакет LaTeX при первом обращении документа к нему, а затем кэширует его локально. Первая компиляция на компьютере к тому же сразу скачивает набор часто используемых пакетов. Эта первая компиляция может быть медленнее и требует подключения к сети. Последующие компиляции используют кэш. Если зеркало пакетов Oleafly не отвечает, компиляция переходит на исходный источник, и журнал сообщает об этом.
Офлайн-режим в настройках (раздел «Общие») или в палитре команд делает это гарантией для Tectonic. Компилятор запускается с --only-cached и никогда не скачивает пакеты. Документ, которому нужен незакэшированный пакет, завершается ошибкой с сообщением, которое по возможности называет файл, а кнопка Выключить и скомпилировать отключает офлайн-режим и запускает компиляцию снова.
Офлайн-режим распространяется и на Typst. Пока он включён, Typst не может скачать пакет, поэтому каждый пакет @preview должен уже быть в кэше или добавлен в папку typst-packages проекта. См. Пакеты из Typst Universe. Проекты Markdown игнорируют офлайн-режим, и журнал сообщает об этом.
latexmk использует дистрибутив TeX, уже установленный на вашем компьютере. Oleafly сначала проверяет системные дистрибутивы, включая MacTeX, TeX Live, MiKTeX и TinyTeX, а в Настройки → Движки → LaTeX тот, которым идёт компиляция, помечен как Используется. Если ни одного нет, приложение может установить собственную копию TinyTeX и управлять ею. Для запуска latexmk MiKTeX нужен ещё и Perl; см. MiKTeX и 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 на этом компьютере, поэтому выбор такого компилятора без него открывает этот диалог. Выберите Скачать и использовать TinyTeX или Вернуться к Tectonic, чтобы вернуться к встроенному движку. Если компиляция уже завершилась неудачей по этой причине, предпросмотр предлагает Скачать и использовать TinyTeX и Использовать Tectonic. См. Когда TeX не установлен. - «latexmk требует Perl» в MiKTeX: установите Strawberry Perl или TinyTeX, у которого свой Perl. См. MiKTeX и Perl.
- Отсутствует файл в сборке
latexmk: используйте Найти и установить. Если поиск не удался, найдите имя файла или пакета в списке Пакеты в Настройки → Движки → LaTeX. В Debian, Ubuntu или Fedora установите его черезaptилиdnf. Пакетами MiKTeX управляют в MiKTeX Console. - upLaTeX или pLaTeX не установлен: выберите Установить поддержку японского (около 450 МБ), когда это предлагается, или выполните команду, которую называет сообщение. См. Японские документы.
- В PDF нет текста, чаще всего корейского, китайского или японского: в шрифте нет глифов для этих символов, и TeX пропускает их без ошибки. Oleafly предупреждает вас, а журнал даёт настройку для вставки. См. Символы, отсутствующие в PDF или Символы, которые выглядят как квадратики для Typst.
- В PDF нет указателя, глоссария или списка обозначений: Tectonic не умеет запускать
makeindex. Переключите проект наlatexmkили собирайте глоссарии через\makenoidxglossaries, для которого внешний инструмент не нужен. Вlatexmkсписки, созданные сxindyили\newglossary, не собираются. - Компиляции не хватило времени: скомпилируйте снова. Если пакеты ещё скачивались, загрузка продолжится с того места, где остановилась. Для длинных черновиков на Tectonic установите Режим компиляции в Быстрый.
- Рисунок EPS, принудительный драйвер
pdftexили отсутствующий файл бандла в Tectonic: открывается диалог выбора движка. Если он не открылся или вы его закрыли, выберите Выбрать движок. Где эта кнопка в каждом виде, сказано в разделе Когда Tectonic не хватает. Выберите вариант с пометкой Рекомендуется: системный LaTeX, если Oleafly находит работающий дистрибутив TeX, или Скачать и использовать TinyTeX, если не находит. Если не хватает пакета, Oleafly после переключения может продолжить его установкой. minted, PythonTeX или\write18заблокированы: если вы доверяете каждому файлу в проекте, выберите Разрешить внешние команды на плашке над редактором. См. Разрешение внешних команд.- Не удалось скачать пакет в Tectonic: проверьте соединение и выберите Скомпилировать снова в сообщении. Oleafly уже пробовал исходный источник после своего зеркала, загрузка продолжится с того места, где остановилась, а если компьютер был офлайн, компиляция сама запустится снова, как только появится соединение.
- «Typst 0.13.1 не установлен»: проект закрепляет версию Typst, которой нет на этом компьютере. Выберите Скачать Typst 0.13.1 в предпросмотре или Использовать Typst и вашу версию по умолчанию, чтобы снять закрепление. См. Когда закреплённая версия отсутствует.
- Предупреждения о неопределённых цитатах или ссылках: Предпроверка точно находит каждую, с файлом и строкой.
- Ошибка, которую не удаётся разобрать: спросите ИИ. «Исправь ошибки LaTeX» запускает цикл из компиляции, чтения журнала, точечной правки и перекомпиляции с выбранной политикой подтверждения.
Другие движки документов
Заголовок раздела «Другие движки документов»Выбор компилятора LaTeX — отдельная от движка документа проекта настройка:
- Проекты Typst компилируются встроенным Typst 0.15.1 или версией, закреплённой в проекте. См. Проекты Typst.
- Проекты Markdown собираются в PDF через управляемый Pandoc с Tectonic в качестве движка PDF.
- Проекты Quarto превращают файлы
.qmdи.Rmdв PDF или веб-страницу с помощью Quarto. См. Quarto. - Проекты Calepin выполняют код в документе Typst с помощью Calepin, а затем собирают PDF встроенным Typst. См. Calepin. Ни один из этих движков не запускает код проекта, пока вы не разрешите это.
- Тегированные доступные PDF создаются через LuaLaTeX с системной установкой TeX или управляемым Oleafly TinyTeX. См. Движки и пакеты LaTeX. Typst 0.14 и новее тегирует каждый PDF без лишних шагов.
Движок выбирается для каждого проекта при его создании, и интерфейс подстраивается под него: действия, которые движок не может поддержать, скрываются, а не остаются и не срабатывают. Чтобы перевести проект LaTeX на Typst, преобразуйте его в новый проект Typst.
Сохраняйте исходник успешной сборки
Заголовок раздела «Сохраняйте исходник успешной сборки»Включите контрольные точки, чтобы сохранять исходник, использованный успешными компиляциями. Можно сравнивать и восстанавливать более раннюю сборку, не меняя ваш ручной процесс работы с Git.
Чтобы хранить в папке проекта сам скомпилированный PDF, включите синхронизацию PDF при компиляции в меню сохранения предпросмотра.