LuaTeX: инструкция от гика, возможности движка, форматы, автоматизация и ограничения

↓Скачать LuaTeX

LuaTeX — не редактор с окнами и панелями, а программируемый движок набора документов. Он развивает идеи pdfTeX, встраивает интерпретатор Lua, принимает Unicode-текст, работает с современными шрифтами и формирует PDF либо DVI. Это определяет и сильные стороны продукта, и его порог входа: LuaTeX особенно ценен там, где стандартных макросов TeX недостаточно и требуется вмешаться в обработку текста, шрифтов, узлов документа, поиска файлов или вывода. Для обычного автора LaTeX-документа важна ещё одна деталь: современная команда lualatex в TeX Live и MiKTeX использует LuaHBTeX, а не исходный бинарник luatex. Поэтому этот обзор посвящён именно LuaTeX как движку и отдельно отмечает места, где рядом находятся LuaHBTeX, LuaLaTeX и другие родственные инструменты.

Что такое LuaTeX и кто его разрабатывает

LuaTeX — расширенная версия TeX, выросшая из pdfTeX и получившая встроенный Lua. Основная идея проекта состоит не в добавлении очередного слоя макросов, а в том, чтобы открыть внутренние этапы TeX для программирования. Lua-код может запускаться прямо во время набора, получать доступ к структурам движка, работать с узлами, участвовать в поиске файлов, подменять отдельные этапы обработки и формировать дополнительные данные.

Основными авторами расширений LuaTeX являются Taco Hoekwater, Hartmut Henkel, Hans Hagen и Luigi Scarso. Сам проект объединяет части TeX, e-TeX, Omega/Aleph, pdfTeX, Kpathsea, Lua, MetaPost и ряда вспомогательных библиотек. Это важно для понимания продукта: LuaTeX не является самостоятельным текстовым процессором в стиле Word и не поставляет собственную среду создания проектов. Он является исполняемым движком внутри TeX-экосистемы и обычно устанавливается вместе с TeX Live, MacTeX или MiKTeX.

LuaTeX относится к классу TeX-движков. Лицензия — GNU GPL версии 2 или новее. Платных редакций, подписки и отдельной коммерческой лицензии для обычного запуска движка нет. Аккаунт для локального набора не требуется.

Основные параметры LuaTeX

Параметр	Значение
Тип	TeX-движок с встроенным Lua
Разработчики	LuaTeX Team; основные авторы расширений — Taco Hoekwater, Hartmut Henkel, Hans Hagen, Luigi Scarso
Актуальный статус	Активно поддерживается; в TeX Live 2026 исходный LuaTeX выпущен как 1.24.0
Распространение	TeX Live, MacTeX, MiKTeX, исходный код проекта
Интерфейс	Командная строка, TeX-файлы, Lua-файлы, журнал выполнения; собственного GUI нет
Язык интерфейса	Имена параметров CLI и диагностические сообщения движка — на английском; локализуемого собственного GUI нет
Основной ввод	TeX-текст; текстовый ввод и вывод движка обрабатываются как Unicode
Шрифты	Поддержка OpenType и TrueType на уровне движка; также традиционные TeX-шрифты
Графика в PDF-режиме	PDF, JPG, JBIG2, PNG; EPS и обычный PostScript напрямую не включаются
Вывод	PDF или DVI
Автоматизация	Lua, callbacks, командные параметры, режим texlua, файл зависимостей .fls через recorder
Сеть	Для локального набора не нужна; Lua socket в актуальной TeX Live-сборке отключён по умолчанию из соображений безопасности
Облако, мобильное приложение, ИИ	Собственных облачной службы, мобильного клиента и ИИ-модуля у движка нет
Лицензия	GNU GPL 2 или новее
Цена	Лицензионная плата за LuaTeX отсутствует

Версия зависит от дистрибутива. TeX Live 2026 содержит LuaTeX 1.24.0. Пакет MiKTeX для Windows x64, опубликованный 14 мая 2026 года, имеет версию 1.25.7 и включает LuaTeX и LuaHBTeX. Поэтому для воспроизводимости документа нужно фиксировать не только название LuaTeX, но и дистрибутив, его выпуск, версию движка и набор TeX-пакетов.

Платформы, распространение и текущее состояние

На практике LuaTeX устанавливают не как одиночное приложение, а как часть TeX-дистрибутива. TeX Live 2026 предоставляет TeX-систему для GNU/Linux и других Unix-платформ, macOS и Windows. Для Windows в TeX Live 2026 поддерживаются Windows 10 и более новые версии. На macOS рекомендуемая упаковка TeX Live — MacTeX; MacTeX 2026 поддерживает macOS 11 Big Sur и новее на Intel и Apple silicon. MiKTeX также распространяется для Windows, macOS и нескольких Linux-систем.

Для Linux полезно сначала разобраться с общими принципами установки приложений и пакетных систем — на GeekHow есть отдельный материал о том, как устанавливать приложения в Linux. В случае LuaTeX это особенно уместно: системный пакет, TeX Live из собственного установщика и MiKTeX могут жить в разных каталогах и обновляться разными средствами. Смешивание нескольких TeX-дистрибутивов в PATH часто приводит к тому, что запускается не та версия движка, которую ожидает автор проекта.

LuaTeX продолжает развиваться. В TeX Live 2026 для версии 1.24.0 добавлялись исправления и изменения, а годовой выпуск TeX Live содержит отдельный раздел с нововведениями LuaTeX. Проект не находится в режиме снятой поддержки или архивного продукта.

При этом роль исходного LuaTeX в повседневном LaTeX изменилась. Начиная с TeX Live 2020 и соответствующих выпусков MiKTeX, команда lualatex использует LuaHBTeX. LuaHBTeX основан на LuaTeX и добавляет встроенный HarfBuzz для сложного формирования глифов. Поэтому пользователь, который запускает lualatex, работает с близким, но не идентичным движком. Команда luatex остаётся отдельной и в TeX Live 2026 сообщает баннер LuaTeX 1.24.0.

Интерфейс: терминал, исходник, журнал и результат

У LuaTeX нет собственного окна проекта, панели инструментов, дерева документов или встроенного предпросмотра PDF. Его интерфейс состоит из нескольких рабочих зон, каждая из которых представлена файлом или потоком командной строки. Это делает движок удобным для автоматизации, но означает, что редактирование исходника и просмотр результата выполняются во внешних программах.

Командная строка

Основная точка входа — исполняемый файл luatex. Команда принимает параметры, имя TeX-файла, имя формата и дополнительные данные. Без аргументов движок переходит в интерактивный режим и показывает приглашение TeX. Для обычной сборки указывается файл: движок читает его, ищет связанные ресурсы, пишет сообщения в терминал и создаёт итоговые файлы.

Исходный TeX-файл

Главным документом служит текстовый файл с расширением .tex. LuaTeX нативно читает текст как Unicode. Однако способность распознать символ и способность вывести его подходящим глифом — разные вещи: для набора конкретных письменностей нужен шрифт, содержащий требуемые символы, и соответствующая конфигурация формата или шрифтового загрузчика.

Lua-код

Lua может находиться прямо внутри TeX через примитив \directlua либо в отдельных .lua-файлах. Встроенный интерпретатор позволяет выполнять вычисления, строить таблицы данных, менять текст до дальнейшей обработки, регистрировать callbacks, обращаться к библиотекам LuaTeX и взаимодействовать с внутренними структурами движка. Для крупного Lua-кода отдельный файл легче версионировать и проверять, чем длинная вставка внутри TeX.

Консоль и .log

Сообщения о найденных файлах, предупреждения, ошибки и статистика попадают в терминал и в файл с расширением .log. При диагностике важно начинать с первой содержательной ошибки: более поздние сообщения нередко являются следствием первого сбоя. На Linux общие принципы чтения журналов и поиска нужных строк дополнительно разобраны в материале GeekHow про log-файлы Linux.

PDF, DVI и вспомогательные файлы

По умолчанию luatex формирует PDF. Движок также умеет выводить DVI. Имя итогового файла обычно наследуется от jobname, который по умолчанию связан с именем исходника. Параллельно создаётся журнал .log, а при включённом recorder — .fls со списком открытых входных и выходных файлов. Эти данные полезны для сборочных систем и анализа зависимостей.

Архитектура и основные функции

Встроенный Lua

Главное отличие LuaTeX от pdfTeX — встроенный Lua 5.3 в обычных актуальных сборках. Lua-код выполняется внутри процесса TeX, поэтому не нужен отдельный межпроцессный обмен для каждой операции. Через библиотеку tex Lua может передавать текст обратно в TeX, через texio — писать диагностические сообщения, а через другие пространства имён обращаться к узлам, шрифтам, токенам, PDF-механизмам и настройкам движка.

Связка двух языков позволяет разделить задачи. TeX остаётся сильным в макрорасширении и наборе, а Lua берёт на себя обработку строк, таблиц, файлов, вычисления и программную логику. При этом Lua-код не превращает LuaTeX в универсальную среду разработки: его основное назначение по-прежнему связано с подготовкой и обработкой TeX-документа.

Callbacks

Callbacks — точки входа, в которых LuaTeX вызывает зарегистрированную Lua-функцию в определённый момент внутренней обработки. Часть callbacks дополняет штатное поведение, часть способна заменить конкретный этап. LuaTeX предоставляет callbacks для поиска и чтения файлов, предварительной обработки входных строк, шрифтовых операций, работы с узлами и других частей конвейера.

Это один из наиболее сильных и одновременно рискованных механизмов LuaTeX. Код callback получает данные на низком уровне, а движок ожидает корректный результат определённого типа. Ошибка в возвращаемой структуре способна испортить дальнейший набор или завершить процесс. Поэтому callbacks лучше держать короткими, документировать их назначение и проверять на минимальном файле.

Узлы документа

После токенизации и макрообработки многие элементы документа представлены внутренними узлами: глифами, клеем, kern, списками, правилами, whatsit-объектами и другими структурами. LuaTeX открывает эти данные Lua-коду. Это позволяет создавать обработчики, которые невозможно выразить обычными высокоуровневыми макросами без значительных обходных решений.

Работа с узлами нужна авторам пакетов, нестандартных шрифтовых систем и сложных движков набора. Для обычного документа это не обязательный уровень. Ошибка при обходе или модификации связного списка узлов способна привести к повреждённой структуре, поэтому низкоуровневые преобразования требуют особенно аккуратной проверки.

Unicode

LuaTeX обрабатывает текстовый ввод и вывод как Unicode. Это устраняет базовое 8-битное ограничение классического TeX и pdfTeX на уровне движка. Однако Unicode-ввод не означает автоматического выбора шрифта, правил переноса, направления письма или языковой типографики. Эти задачи решаются форматом и пакетами поверх движка.

OpenType и TrueType

Движок поддерживает современные OpenType и TrueType шрифты, включая математические шрифты. В LuaTeX архитектура работы со шрифтами сильно программируема: Lua участвует в загрузке и обработке данных. Именно поэтому на практике пользователи часто работают не с сырым luatex, а с готовым форматом и пакетами, которые настраивают шрифтовый слой.

LuaHBTeX идёт дальше исходного LuaTeX, добавляя HarfBuzz как встроенный модуль. Для сложных письменностей и современного LuaLaTeX это существенное отличие. Наличие слова LuaTeX в PDF Producer не означает, что документ был обработан исходным luatex: баннер LuaHBTeX и команда запуска дают более точный ответ.

Прямой PDF и DVI

LuaTeX создаёт PDF напрямую и также поддерживает DVI. PDF-режим удобен для обычного финального документа: не требуется отдельный переход от DVI к PDF. DVI остаётся полезным для процессов, где результат должен пройти через отдельный драйвер или существующий DVI-конвейер.

Графика

В PDF-режиме движок нативно работает с PDF, JPEG, JBIG2 и PNG как с включаемой графикой. PostScript и EPS напрямую не поддерживаются, поэтому такой ресурс нужно предварительно преобразовать в поддерживаемый формат. MetaPost занимает особое место: LuaTeX включает библиотеку MPlib, а TeX-экосистема предоставляет инструменты, которые используют её для встроенной обработки MetaPost-графики.

Поиск файлов через Kpathsea

LuaTeX в стандартных TeX Live-сборках использует Kpathsea для поиска TeX-файлов, форматов, шрифтов и других ресурсов. Расположение файла не обязано совпадать с текущим каталогом: поиск идёт по конфигурации TeX-деревьев и переменным среды. Это удобно в большой установке, но при конфликте нескольких TeX-дистрибутивов затрудняет диагностику. Утилита kpsewhich помогает увидеть, какой файл реально будет найден.

texlua и texluac

Тот же набор бинарников может работать как Lua-интерпретатор texlua и компилятор байткода texluac. В режиме texlua доступна среда Lua, связанная с TeX Live, что удобно для служебных сценариев, которые должны использовать TeX-деревья и библиотеки. Это не отдельный графический продукт, а другой режим того же семейства исполняемых файлов.

Автоматизация сборки

LuaTeX хорошо вписывается в Make, shell-скрипты, CI и другие сборочные системы. Для машинной сборки важны код возврата, режим остановки на первой ошибке, каталог вывода, recorder и предсказуемая версия дистрибутива. Встроенной облачной очереди задач у LuaTeX нет: автоматизация строится вокруг локального CLI или внешней инфраструктуры.

Жизненный цикл продукта

Публичная история LuaTeX показывает длительное движение от экспериментального движка к стабильной части TeX-экосистемы. Первая публичная beta была представлена на конференции TUG 2007. Версия 1.00 вышла в 2016 году и стала рубежом, после которого основные интерфейсы проекта рассматриваются как стабильные.

В 2020 году произошло важное изменение не самого LuaTeX, а его роли в LaTeX: LuaLaTeX в TeX Live был переведён на LuaHBTeX. LuaHBTeX сохраняет основу LuaTeX, но добавляет HarfBuzz. Это разделило два сценария: исходный luatex продолжает существовать как программируемый движок, а массовый LuaLaTeX использует его HarfBuzz-вариант.

В TeX Live 2026 LuaTeX имеет версию 1.24.0. В выпуск вошли изменения движка и исправления, а исходники продолжают синхронизироваться с TeX Live. Следовательно, LuaTeX в 2026 году — не музейная ветка и не снятый с поддержки предшественник LuaHBTeX, а действующий компонент семейства TeX.

Карта форматов и совместимости

Тип данных	Поддержка	Практический смысл	Ограничение
.tex	Основной текстовый ввод	Исходник TeX с макросами и вызовами Lua	Набор зависит от выбранного формата, пакетов и шрифтов
.lua	Исполняется встроенным Lua	Внешняя программная логика и служебные модули	Код получает права процесса и должен считаться исполняемым содержимым
OpenType, TrueType	Поддерживаются движком	Современные текстовые и математические шрифты	Высокоуровневый выбор и формирование текста зависят от формата и шрифтового слоя
PDF	Прямой вывод; включаемая графика в PDF-режиме	Готовый документ и векторные иллюстрации	LuaTeX не является редактором уже готового PDF
DVI	Поддерживается как вывод	Совместимость с отдельными DVI-процессами	Нужен дальнейший драйвер для PDF или другого конечного формата
PNG, JPG, JBIG2	Нативное включение в PDF-режиме	Растровые иллюстрации	Качество определяется исходным изображением
EPS, PostScript	Не включаются напрямую как обычная графика	Требуют предварительного преобразования	Добавляется отдельный этап конвертации
.log	Журнал сборки	Диагностика ошибок, предупреждений и загруженных ресурсов	Не является переносимым исходником документа
.fls	Создаётся с recorder	Список фактически открытых входных и выходных файлов	Появляется только при включении режима

Главная граница совместимости проходит не по расширению .tex, а по используемым примитивам и пакетам. Документ, написанный для классического pdfTeX, часто запускается на LuaTeX благодаря общей основе TeX, но низкоуровневые pdfTeX-примитивы, кодировки и шрифтовые решения могут требовать адаптации. Документ, рассчитанный на LuaHBTeX и HarfBuzz, тоже нельзя автоматически считать эквивалентным документу для исходного luatex.

Требования, производительность, интернет и безопасность

Системные требования

LuaTeX наследует практические требования от выбранного TeX-дистрибутива. TeX Live 2026 поддерживает Windows 10 и новее, GNU/Linux и другие Unix-платформы; MacTeX 2026 рассчитан на macOS 11 и новее и работает нативно на Intel и Apple silicon. MiKTeX распространяется для Windows, macOS и выбранных Linux-дистрибутивов. Сам движок запускается локально из командной строки и не требует браузерного интерфейса.

Производительность без вымышленных замеров

Время сборки зависит от объёма TeX-кода, числа проходов, шрифтов, изображений, пакетов и Lua-обработчиков. Lua-callback, который проходит по каждому узлу, способен заметно увеличить работу движка, тогда как простой \directlua с небольшим вычислением почти не меняет архитектуру сборки. LuaJITTeX существует как вариант с LuaJIT, но наличие JIT само по себе не гарантирует ускорение любого документа.

В совместимых сборках LuaTeX параметр draftmode отключает запись PDF и чтение включаемых изображений. Этот режим сокращает работу, не связанную с финальным выводом, но не заменяет окончательную сборку: проблемы с изображениями и результирующим PDF в нём не проверяются.

Зависимость от интернета

Сам набор локального документа не требует постоянного подключения. Интернет обычно нужен для первоначальной установки дистрибутива, обновлений и получения отсутствующих пакетов. MiKTeX умеет автоматически устанавливать недостающие пакеты из сети; TeX Live обычно устанавливает выбранную схему заранее и обновляется через собственные средства.

У актуального LuaTeX в TeX Live Lua socket отключён по умолчанию по соображениям безопасности. Это показывает важное отличие от обычного облачного сервиса: сетевой обмен не является базовой частью работы движка. Сеть появляется только через явно разрешённые механизмы, пользовательский Lua-код или внешние инструменты.

Безопасность

TeX-файл с Lua-кодом следует рассматривать как исполняемый документ. \directlua способен запускать Lua-функции, читать данные и взаимодействовать с файловой системой в рамках доступных API. Кроме того, TeX-системы имеют механизм shell escape для запуска внешних программ. В TeX Live произвольный shell escape ограничен по умолчанию, а полное разрешение внешних команд предназначено только для доверенных документов.

В актуальном LuaTeX параметр safer отключает большинство Lua-функций, которые изменяют файлы или запускают программы. По умолчанию этот режим выключен, поскольку нарушает работу многих документов. Поэтому безопасная стратегия строится не на одном флаге, а на сочетании доверенного исходника, ограниченных прав пользователя, контролируемого окружения и выключенного полного shell escape.

Приватность

При стандартной локальной сборке исходный .tex, изображения, шрифты и Lua-файлы обрабатываются на компьютере пользователя. Сам LuaTeX не требует загрузки документа в облако и не связан с аккаунтом. Передача данных наружу появляется только при использовании сетевых библиотек, внешних программ, сетевого хранилища или сторонней онлайн-среды, то есть за пределами базового локального режима.

Цена, лицензирование и редакции

LuaTeX распространяется как свободное ПО под GNU GPL 2 или новее. Платной Pro-редакции, подписки, пробного периода и ограничения по числу документов нет. Пользователь может устанавливать движок как часть TeX Live, MacTeX или MiKTeX и запускать его локально без аккаунта.

Рядом существуют связанные бинарники, которые нельзя считать платными редакциями одного продукта. LuaHBTeX — вариант LuaTeX с HarfBuzz; LuaJITTeX использует LuaJIT; texlua запускает встроенную Lua-среду как интерпретатор. Они решают разные технические задачи и могут поставляться тем же дистрибутивом.

Фактическая стоимость владения связана не с лицензией LuaTeX, а с окружением: размером TeX-дистрибутива, хранением шрифтов и проектов, CI-инфраструктурой, временем на поддержку собственных callbacks и совместимостью пакетов. Эти затраты зависят от сценария и не являются тарифами LuaTeX.

Как пользоваться программой — советы гика

Ниже собраны операции, которые относятся именно к исходному LuaTeX и его CLI. Высокоуровневые команды LaTeX для выбора шрифтов, библиографии и классов документов зависят от формата; перенос таких шагов сюда под видом функций luatex смешал бы движок с LuaLaTeX/LuaHBTeX. Поэтому практическая часть сосредоточена на PDF/DVI-выводе, Lua, callbacks, узлах, Kpathsea, recorder и автоматизации — механизмах самого LuaTeX.

Настройки после установки: проверить, какой движок запускается

Цель. Убедиться, что команда luatex указывает на ожидаемый LuaTeX, а не на другой бинарник из старой или параллельной TeX-установки.

Подготовка. Откройте терминал или командную строку, доступную в вашей ОС. TeX Live, MacTeX либо MiKTeX уже должны быть установлены и добавлены в PATH.

1. Введите luatex —version.
2. Проверьте строку с названием движка и номером версии. Для TeX Live 2026 ожидается LuaTeX 1.24.0.
3. Если на компьютере несколько TeX-систем, используйте системное средство поиска исполняемого файла, чтобы определить путь к luatex и сопоставить его с нужным дистрибутивом.

Проверка результата. Команда завершается без запуска набора и показывает версию. Типичная ошибка. Терминал сообщает, что luatex не найден, либо показывает старую версию из другого каталога. Безопасный откат. Не удаляйте TeX-деревья вручную; верните прежний PATH или исправьте порядок каталогов через штатные настройки дистрибутива.

Собрать минимальный TeX-файл в PDF

Цель. Проверить базовый конвейер от текстового файла до PDF без LaTeX и сторонних пакетов.

Подготовка. Создайте в отдельном каталоге файл hello.tex в UTF-8. Для первой проверки используйте простой ASCII-текст, чтобы не смешивать работу движка и настройку шрифта.

1. Запишите в hello.tex текст Hello from LuaTeX!\par\bye.
2. Сохраните файл и откройте терминал в том же каталоге.
3. Выполните luatex hello.tex.
4. Дождитесь строки Output written on hello.pdf и возврата к приглашению командной строки.
5. Откройте hello.pdf во внешнем PDF-просмотрщике.

Проверка результата. В каталоге должны появиться hello.pdf и hello.log, а в PDF — заданная строка. Типичная ошибка. LuaTeX не находит файл или останавливается на TeX-ошибке. Безопасный откат. Оставьте исходник неизменным, удалите только созданные hello.pdf и hello.log и повторите сборку после исправления первой ошибки в журнале.

Получить DVI вместо PDF

Цель. Использовать LuaTeX в процессе, который ожидает DVI.

Подготовка. Возьмите минимальный hello.tex из предыдущего примера.

1. В терминале выполните luatex —output-format=dvi hello.tex.
2. Проверьте, что команда завершилась без ошибки.
3. Найдите hello.dvi рядом с журналом.
4. Перед дальнейшей публикацией обработайте DVI подходящим драйвером своего TeX-процесса.

Важный параметр. output-format принимает pdf или dvi. Проверка результата. Создан именно .dvi, а не .pdf. Типичная ошибка. Следующий инструмент процесса не принимает DVI, созданный текущей конфигурацией. Безопасный откат. Вернитесь к обычной команде luatex hello.tex и сохраните PDF-ветку как рабочую до выяснения требований драйвера.

Выполнить Lua-код через directlua

Цель. Проверить встроенный Lua без внешнего .lua-файла.

Подготовка. Создайте файл directlua.tex.

1. Запишите в него \directlua{tex.print(«Text generated by Lua»)}, затем \par\bye.
2. Сохраните файл в UTF-8.
3. Выполните luatex directlua.tex.
4. Откройте directlua.pdf.

Важный параметр. tex.print передаёт текст из Lua обратно во вход TeX. Проверка результата. В PDF присутствует строка Text generated by Lua. Типичная ошибка. Lua-синтаксис или кавычки внутри \directlua нарушены. Безопасный откат. Замените содержимое \directlua на минимальное tex.print, соберите файл, затем возвращайте Lua-логику небольшими фрагментами.

Вынести Lua-логику в отдельный файл

Цель. Разделить TeX-разметку и более объёмный Lua-код.

Подготовка. В одном каталоге создайте script.lua и external.tex.

1. В script.lua запишите tex.print(«Loaded from Lua file»).
2. В external.tex запишите \directlua{dofile(«script.lua»)}\par\bye.
3. Выполните luatex external.tex.
4. Откройте external.pdf и проверьте текст.

Проверка результата. Lua-файл найден, исполнен, строка появилась в PDF. Типичная ошибка. script.lua не находится из-за рабочего каталога или ошибочного имени. Безопасный откат. Верните script.lua в каталог исходника и используйте простое имя без изменения глобальных путей TeX.

Подключить callback предварительной обработки строки

Цель. Показать механизм, который меняет входную строку до дальнейшей обработки TeX.

Подготовка. Создайте отдельный тестовый файл callback.tex, не используйте ценный исходник: callback затрагивает весь последующий вход.

1. В начале файла зарегистрируйте через \directlua функцию callback.register(«process_input_buffer», function(line) return (line:gsub(«TOKEN», «changed»)) end).
2. После блока Lua добавьте строку TOKEN\par и завершите файл командой \bye.
3. Выполните luatex callback.tex.
4. Откройте PDF и сравните вывод с исходной строкой.

Проверка результата. В PDF выводится changed вместо TOKEN. Типичная ошибка. callback возвращает неподходящее значение или Lua-функция содержит ошибку. Безопасный откат. Удалите регистрацию callback целиком и убедитесь, что исходный TeX снова собирается штатно; затем возвращайте обработчик только в отдельный минимальный пример.

Просмотреть список узлов абзаца без изменения документа

Цель. Увидеть, что Lua получает внутренний список узлов TeX, не меняя содержимое и порядок узлов.

Подготовка. Создайте отдельный файл nodes.tex с коротким тестовым абзацем. Используйте диагностический callback только в копии проекта.

1. В начале файла добавьте \directlua{callback.register(«pre_linebreak_filter», function(head) local count=0; for n in node.traverse(head) do count=count+1 end; texio.write_nl(«term and log», «NODECOUNT=»..count); return true end)}.
2. После блока Lua добавьте Hello node list\par\bye.
3. Выполните luatex nodes.tex.
4. Найдите строку NODECOUNT в терминале или nodes.log.
5. Откройте nodes.pdf и убедитесь, что текст абзаца не был изменён диагностикой.

Важные параметры. pre_linebreak_filter получает head списка перед разбиением абзаца на строки; node.traverse обходит узлы, а возврат true оставляет список для штатной дальнейшей обработки. Проверка результата. журнал содержит числовой NODECOUNT, PDF собран без подмены текста. Типичная ошибка. обработчик не возвращает допустимое значение или Lua-код содержит синтаксическую ошибку. Безопасный откат. удалите регистрацию callback целиком и повторите сборку исходного тестового абзаца.

Собрать файлы в отдельный каталог и записать зависимости

Цель. Отделить исходники от результатов и получить машинно читаемый перечень использованных файлов.

Подготовка. Создайте каталог build рядом с hello.tex.

1. Выполните luatex —output-directory=build —recorder hello.tex.
2. Проверьте содержимое build.
3. Найдите hello.pdf, hello.log и hello.fls.
4. Откройте .fls обычным текстовым редактором и убедитесь, что в нём перечислены входные и выходные файлы.

Важные параметры. output-directory меняет каталог вывода, recorder создаёт .fls. Проверка результата. исходный каталог остаётся чище, а .fls отражает зависимости. Типичная ошибка. build не существует или недоступен для записи. Безопасный откат. запустите luatex без output-directory и не меняйте глобальные переменные TeX, пока права на каталог не исправлены.

Настроить поведение для автоматической сборки

Цель. Сделать ошибку заметной для CI или другого автоматического процесса без интерактивного ожидания.

Подготовка. Используйте копию проекта и сохраните рабочий обычный режим сборки.

1. Запустите luatex —halt-on-error —interaction=nonstopmode hello.tex.
2. Проверьте код завершения внешним средством сборки.
3. При ошибке первым делом откройте .log и исправьте первую содержательную проблему.
4. После успешного автоматического прогона выполните обычную финальную сборку и откройте PDF.

Важные параметры. halt-on-error завершает процесс при первой ошибке, nonstopmode исключает обычный интерактивный диалог. Проверка результата. автоматизация получает ненулевой код при ошибке и не зависает на приглашении TeX. Типичная ошибка. подавление диалога ошибочно принимают за подавление самой проблемы. Безопасный откат. повторите запуск без interaction=nonstopmode, чтобы увидеть интерактивный контекст, но не изменяйте исходник автоматически.

Найти ресурс TeX через Kpathsea из Lua

Цель. Определить фактический путь к файлу в TeX-дереве тем же механизмом поиска, который использует окружение LuaTeX.

Подготовка. Создайте файл findfile.lua. Этот пример ничего не меняет в TeX-дереве и только печатает найденный путь.

1. В findfile.lua запишите kpse.set_program_name(«luatex»).
2. Следующей строкой добавьте local f = kpse.find_file(«plain.tex»).
3. Завершите скрипт строкой print(f or «not found»).
4. Выполните texlua findfile.lua.
5. Сопоставьте выведенный путь с TeX-дистрибутивом, который должен обслуживать проект.

Важный параметр. перед kpse.find_file в самостоятельном texlua-скрипте задаётся имя программы через kpse.set_program_name, чтобы инициализировать поиск Kpathsea для нужного окружения. Проверка результата. вместо not found выводится полный путь к plain.tex. Типичная ошибка. вызов kpse.find_file выполняется до инициализации Kpathsea. Безопасный откат. удалите тестовый findfile.lua; конфигурационные файлы TeX и переменные окружения этим примером не изменяются.

Запустить Lua-скрипт через texlua

Цель. Использовать Lua-среду TeX без набора документа.

Подготовка. Создайте файл tool.lua со строкой print(«texlua works»).

1. В терминале выполните texlua tool.lua.
2. Убедитесь, что в консоли появилась строка texlua works.
3. Для скриптов, которым нужны ресурсы TeX-дерева, добавляйте только документированные вызовы соответствующих библиотек.

Проверка результата. скрипт завершается без создания PDF и печатает строку в терминал. Типичная ошибка. texlua из другого TeX-дистрибутива использует другое окружение поиска. Безопасный откат. вернитесь к проверке путей и версии, не копируйте библиотечные файлы между TeX-деревьями вручную.

Сквозной сценарий: исходник, Lua, сборка, проверка и сохранение

Цель. Пройти полный путь от подготовки каталога до проверенного PDF с отдельной Lua-логикой и журналом зависимостей.

Подготовка. Создайте новый каталог проекта, внутри — main.tex, helper.lua и подкаталог build. Не используйте для первого прогона сложные пакеты и сторонние шрифты.

1. В helper.lua запишите tex.print(«Generated by helper.lua»).
2. В main.tex добавьте \directlua{dofile(«helper.lua»)}\par\bye.
3. Проверьте движок командой luatex —version.
4. Запустите luatex —halt-on-error —output-directory=build —recorder main.tex.
5. Если процесс завершился успешно, откройте build/main.log и убедитесь, что нет TeX-ошибки.
6. Откройте build/main.fls и проверьте, что main.tex указан среди входных файлов; при обычном чтении helper.lua через dofile он также фиксируется как входной ресурс.
7. Откройте build/main.pdf во внешнем просмотрщике и проверьте текст Generated by helper.lua.
8. Сохраните main.tex, helper.lua и сведения о версии TeX-дистрибутива в системе контроля версий; PDF храните по правилам проекта.

Проверка результата. исходник, Lua-модуль, журнал и PDF согласованы, а финальный файл открывается отдельно от терминала. Типичная ошибка. сборка проходит из другого рабочего каталога и не находит helper.lua. Безопасный откат. вернитесь в каталог проекта, используйте прежние относительные пути и повторите сборку без изменения глобальной конфигурации Kpathsea.

Плюсы

• Встроенный Lua даёт программный доступ к этапам, которые в классическом TeX закрыты или требуют сложных макросных обходов.
• Нативный Unicode-ввод снимает базовое 8-битное ограничение pdfTeX.
• Движок поддерживает OpenType и TrueType, включая современные математические шрифты.
• PDF создаётся напрямую, при этом остаётся DVI-режим для совместимости со старыми процессами.
• Callbacks позволяют перехватывать поиск файлов, входные строки и внутреннюю обработку на определённых стадиях.
• Низкоуровневый доступ к узлам полезен для авторов пакетов, шрифтовых систем и нестандартных алгоритмов набора.
• CLI, коды возврата, recorder и Lua хорошо подходят для воспроизводимой автоматизации.
• Нет лицензии по подписке, ограничений по числу документов или обязательной учётной записи.
• Локальный режим не требует загрузки исходников в облако.

Минусы

• Собственного графического редактора и предпросмотра нет; нужны внешний редактор и PDF/DVI-просмотрщик.
• Порог освоения выше, чем у обычного LaTeX-редактора: для глубокого использования нужны TeX, Lua и понимание внутреннего конвейера.
• Низкоуровневые callbacks и работа с узлами легко нарушают корректность документа при ошибке в Lua-коде.
• Команда lualatex сегодня обычно запускает LuaHBTeX, поэтому название экосистемы способно запутать пользователя, который ожидает исходный luatex.
• Поддержка Unicode на уровне входа не заменяет настройку шрифта, языковых правил и формирования сложных письменностей.
• EPS и PostScript не включаются напрямую как обычная графика в PDF-режиме.
• Номер версии и состав окружения зависят от TeX-дистрибутива, что требует фиксировать среду для воспроизводимой сборки.
• TeX-файл с directlua фактически является исполняемым содержимым и требует того же уровня доверия, что скрипт.

Кому подойдёт

• Авторам TeX-пакетов, которым нужен доступ к узлам, токенам, поиску файлов и другим внутренним механизмам.
• Разработчикам издательских процессов, где набор должен включать вычисления и обработку данных на Lua.
• Пользователям ConTeXt- и Plain TeX-подобных процессов, в которых исходный LuaTeX выбран осознанно.
• Командам, собирающим документы в CI и желающим контролировать версии, зависимости и коды возврата.
• Исследовательским и типографским проектам, где возможностей pdfTeX недостаточно, а прямое программирование движка оправдано.

Кому не подойдёт

• Пользователю, которому нужен визуальный WYSIWYG-редактор с кнопками форматирования и готовым предпросмотром.
• Новичку, который хочет просто собрать стандартный LaTeX-документ с системными шрифтами: для такого сценария современный LuaLaTeX через LuaHBTeX обычно понятнее.
• Проекту, где запрещено исполнение любых встроенных скриптов и требуется максимально узкий статический конвейер.
• Работе, в которой конечный файл нужно вручную редактировать как PDF: LuaTeX создаёт PDF, но не является PDF-редактором. Для последующей ручной правки полезнее отдельный редактор PDF.
• Мобильному сценарию, где нужен самостоятельный официальный клиент для телефона или планшета: у LuaTeX такого клиента нет.

Сравнение с другими аналогами

Движок	Задача	Платформа	Порог освоения	Форматы и шрифты	Автоматизация	Оплата	Главное ограничение	Подходящий сценарий
LuaTeX	Программируемый TeX с Lua	Через TeX Live, MacTeX, MiKTeX на настольных ОС	Высокий при работе с callbacks и узлами	Unicode, OTF/TTF, PDF/DVI, PDF/JPG/JBIG2/PNG	Lua, callbacks, CLI, recorder	Свободное ПО	Нет GUI; исходный luatex не равен современному lualatex	Низкоуровневое управление набором и собственная логика
LuaHBTeX	LuaTeX с встроенным HarfBuzz	TeX Live и MiKTeX на поддерживаемых настольных ОС	Средний для обычного LuaLaTeX, высокий для низкого уровня	Unicode, современные шрифты, HarfBuzz; LuaTeX-основа	Lua и TeX-механизмы; используется lualatex	Свободное ПО в составе дистрибутивов	Поведение формирования глифов отличается от исходного luatex	Современный LuaLaTeX и сложные письменности
pdfTeX	Классический прямой PDF-набор	TeX Live, MacTeX, MiKTeX	Ниже для старых LaTeX-проектов	PDF/DVI; традиционная 8-битная модель движка	CLI и TeX-макросы, без встроенного Lua	Свободное ПО	Нет нативной Unicode-модели и системных OpenType-возможностей LuaTeX/XeTeX	Стабильные наследованные проекты pdfLaTeX
XeTeX	Unicode и современные шрифтовые технологии без Lua-программирования движка	TeX Live и MiKTeX	Средний	Unicode, OpenType, TrueType, AAT; промежуточный XDV с последующим PDF	CLI и TeX-макросы	Свободное ПО под X11 License	Нет встроенного Lua и LuaTeX callbacks	Документы с современными шрифтами, где не нужен Lua-уровень
Tectonic	Самодостаточная современная сборка TeX/LaTeX	Готовые сборки и пакеты для Windows, macOS, Linux	Ниже для типовой командной сборки	Unicode и OpenType благодаря XeTeX-основе; выход PDF	Автоматически повторяет TeX/BibTeX и загружает недостающие ресурсы из bundle	MIT; без подписки	Не предоставляет LuaTeX-совместимый низкоуровневый Lua-механизм	Компактный CLI, воспроизводимые bundle-сборки и CI

Выбор определяется не «какой TeX новее», а уровнем контроля. pdfTeX разумен для устоявшихся проектов без требования к нативным системным шрифтам. XeTeX проще, когда основная цель — Unicode и современные шрифты без Lua-программирования. LuaHBTeX — естественный путь для современного LuaLaTeX. Tectonic уменьшает объём ручного обслуживания окружения. Исходный LuaTeX остаётся самым интересным там, где важны callbacks, узлы и собственная логика внутри движка.

Типичные проблемы и диагностика

luatex не найден в командной строке

Симптом. Оболочка сообщает, что команда luatex отсутствует. Причина. TeX-дистрибутив не установлен либо каталог его бинарников не находится в PATH. Диагностика. Проверьте наличие TeX Live, MacTeX или MiKTeX штатным менеджером и выясните каталог бинарников. Исправление. Добавьте каталог через штатную настройку дистрибутива или переустановите выбранную TeX-систему. Проверка. luatex —version выводит баннер и завершается.

Запускается не та версия LuaTeX

Симптом. Проект собирается иначе, чем на другом компьютере, а luatex —version показывает неожиданный год или номер. Причина. В PATH раньше находится бинарник от другой TeX-установки. Диагностика. Определите полный путь исполняемого файла системной командой поиска и сопоставьте его с каталогом TeX Live или MiKTeX. Исправление. Измените порядок PATH или отключите лишнюю установку штатным способом. Проверка. путь и версия соответствуют выбранной среде.

TeX-файл найден, но внешний Lua-файл отсутствует

Симптом. dofile сообщает, что script.lua не открывается. Причина. рабочий каталог отличается от каталога проекта либо имя файла задано неверно. Диагностика. Сравните текущий каталог терминала, местоположение .tex и .lua и строку dofile. Исправление. Запускайте сборку из каталога проекта либо используйте корректный относительный путь. Проверка. Lua-файл выполняется и сообщение об открытии исчезает.

Unicode-символ читается, но не выводится правильным глифом

Симптом. В исходнике есть нужный символ, но PDF содержит отсутствующий знак или неправильный вывод. Причина. Нативный Unicode-ввод не гарантирует, что активный шрифт содержит нужный глиф и что формат настроил его использование. Диагностика. Проверьте выбранный шрифт и его покрытие, затем отделите проблему шрифта от Lua-кода на минимальном документе. Исправление. Подключите подходящий шрифт средствами выбранного формата. Проверка. символ выводится из нужного шрифта без предупреждения об отсутствии глифа.

Документ для lualatex ведёт себя иначе при запуске luatex

Симптом. LaTeX-документ не собирается напрямую командой luatex либо типографика отличается. Причина. lualatex — формат LaTeX, а в современных TeX Live и MiKTeX он работает через LuaHBTeX; исходный luatex без соответствующего формата — другая конфигурация. Диагностика. Сравните баннеры luatex и lualatex и проверьте, какой формат нужен документу. Исправление. Для LuaLaTeX-документа используйте lualatex; исходный luatex оставляйте для специально подготовленного Plain/форматного процесса. Проверка. команда соответствует формату исходника, а журнал показывает ожидаемый движок.

Callback ломает документ после регистрации

Симптом. До подключения callback файл собирался, после — появляются ошибки или повреждённый вывод. Причина. Callback возвратил данные неподходящего типа, изменил структуру или заменил стандартное поведение некорректно. Диагностика. Отключите callback и повторите сборку, затем оставьте минимальную функцию, которая возвращает вход без изменений. Исправление. Возвращайте строго документированный тип и добавляйте преобразование постепенно. Проверка. минимальный callback и затем полный обработчик дают валидный PDF без новых ошибок.

EPS или PostScript не включается в PDF-режиме

Симптом. Сборка не принимает графический ресурс EPS/PS как обычное включаемое изображение. Причина. LuaTeX в PDF-режиме нативно включает PDF, JPG, JBIG2 и PNG, а не общий PostScript/EPS. Диагностика. Проверьте реальное расширение и формат файла. Исправление. Предварительно преобразуйте графику в PDF или другой поддерживаемый формат штатным инструментом TeX-процесса. Проверка. конвертированный файл включается и отображается в итоговом PDF.

Автоматическая сборка зависает на вопросе TeX

Симптом. CI или скрипт перестаёт продвигаться после ошибки и ждёт ввода. Причина. По умолчанию TeX использует интерактивный errorstopmode. Диагностика. В логе перед остановкой виден вопросительный prompt или сообщение об ошибке. Исправление. Для машинной сборки используйте nonstopmode вместе с halt-on-error. Проверка. процесс завершается кодом ошибки и не ждёт клавиатурного ввода.

Выходные файлы не появляются в заданном каталоге

Симптом. После output-directory PDF или log отсутствуют в build. Причина. каталог не существует, недоступен для записи или команда использует другой синтаксис конкретной сборки. Диагностика. Проверьте существование каталога, права и luatex —help. Исправление. Создайте каталог и предоставьте текущему пользователю право записи; используйте форму параметра, которую показывает сборка. Проверка. PDF, log и другие результаты появляются в указанном месте.

Файл собирается локально, но падает на другом компьютере

Симптом. Один и тот же исходник даёт разные ошибки в двух средах. Причина. Отличаются версия LuaTeX, TeX-дистрибутив, пакеты, шрифты, Lua-модули или пути поиска. Диагностика. Сравните luatex —version, .log и .fls; обратите внимание на фактически загруженные файлы и их каталоги. Исправление. Синхронизируйте дистрибутив и зависимости, храните локальные Lua/TeX-файлы вместе с проектом и фиксируйте версию среды. Проверка. .log и .fls показывают сопоставимый набор ресурсов, а PDF собирается в обеих средах.

FAQ

LuaTeX и LuaLaTeX — одно и то же?

Нет. LuaTeX — движок. LuaLaTeX — формат LaTeX, работающий на LuaTeX-совместимом движке; в актуальных TeX Live и MiKTeX команда lualatex использует LuaHBTeX. Поэтому при отладке всегда полезно смотреть баннер конкретной команды.

Можно ли использовать LuaTeX как обычный Lua-интерпретатор?

Да. Режим texlua запускает встроенную Lua-среду без набора TeX-документа. Для байткода существует texluac. Эти режимы удобны для служебных инструментов вокруг TeX-дерева.

Нужен ли интернет для каждого запуска?

Нет. Локальная сборка работает без постоянного подключения. Сеть требуется TeX-дистрибутиву при установке или обновлении, а MiKTeX также может получать отсутствующие пакеты автоматически.

Можно ли открыть готовый PDF и отредактировать его в LuaTeX?

LuaTeX не является PDF-редактором. Он создаёт PDF из TeX-исходника и может включать PDF как графический ресурс. Для изменения уже готового PDF нужен другой класс программ; при обмене с офисными документами пригодится и отдельная инструкция GeekHow по конвертации PDF в Google Docs.

Почему PDF Producer может содержать LuaTeX, хотя запускался LuaHBTeX?

LuaHBTeX основан на LuaTeX и добавляет встроенный HarfBuzz-модуль. В TeX Live 2026 такие сборки могут сохранять LuaTeX в поле Producer, поэтому для точной идентификации лучше ориентироваться на полный баннер движка и команду запуска, а не только на метаданные PDF.

Является ли LuaTeX облачным сервисом?

Нет. Это локальный движок командной строки. Он может использоваться внутри сторонней облачной среды, но облачный аккаунт, синхронизация проектов и серверная очередь не являются функциями самого LuaTeX.

Подходит ли LuaTeX для генерации документов из данных?

Да, именно встроенный Lua делает такой сценарий естественным. Lua может читать и преобразовывать данные, вычислять значения и передавать подготовленный текст в TeX. При работе с внешними файлами нужно учитывать кодировку, права доступа и воспроизводимость путей.

Можно ли заменить LuaTeX на XeTeX без правок?

Для документа, который использует только общий слой LaTeX, миграция иногда невелика, но Lua-код, callbacks и LuaTeX-специфичные примитивы в XeTeX отсутствуют. XeTeX выбирают ради Unicode и современных шрифтов, а не как совместимую среду для программирования LuaTeX.

Как получить документ в PDF из обычного офисного редактора без TeX?

LuaTeX в таком сценарии избыточен. Если исходник уже находится в Google Docs, прямой путь описан в материале GeekHow о сохранении Google Docs в PDF. LuaTeX имеет смысл тогда, когда нужен TeX-конвейер, строгая типографика или программируемая обработка.

Итог

LuaTeX стоит выбирать не ради «ещё одного способа получить PDF», а ради программируемости TeX-движка. Для низкоуровневой обработки текста, собственных callbacks, работы с узлами, Lua-вычислений и автоматизированного издательского процесса он даёт уровень контроля, которого нет у pdfTeX и XeTeX. Цена этого контроля — отсутствие собственного GUI, более высокий порог освоения и необходимость относиться к Lua-коду как к исполняемому содержимому.

Для обычного современного LaTeX с системными шрифтами разумнее начинать с LuaLaTeX, то есть в актуальной среде с LuaHBTeX. Для стабильного наследованного проекта без Unicode-требований часто достаточно pdfTeX. Для Unicode и OpenType без Lua-уровня подходит XeTeX. Для компактного CLI и автоматического получения поддерживающих файлов интересен Tectonic. Исходный LuaTeX остаётся целевым выбором там, где сам механизм набора должен стать программируемой частью проекта.