Топаз 5.20.1 — текущий продукт. Текущий режим языка — topaz-5.20.
Исходный код 5.20.1 открыт на github.com/studiohaze/topaz. Официальные релизы выходят на topaz.ooo и в npm.
Проверьте установку командой:
topaz version --verboseЭта команда выводит сведения об идентичности компилятора, режима языка, среды выполнения и генератора Rust. При сообщении о проблеме с установкой приложите полный вывод.
Выбор компилятора
Топаз использует Rust Stage 0 по умолчанию для каждой команды, использующей
компилятор. Установленный Stage 2 self-компилятор остается доступным при его
явном выборе с помощью --compiler self на допустимых маршрутах текущего режима:
topaz check app/main.tpz
topaz check app/main.tpz --compiler self
topaz test --root app --locked --compiler self
topaz emit app/main.tpz --compiler self
topaz emit app/main.tpz --target python --compiler self --out-dir python-source
topaz build app/main.tpz --compiler self --out-dir app-product
topaz build app/main.tpz --target web --compiler self --out-dir web-product
topaz dev --root web-app --locked --compiler self
topaz fmt app/main.tpz --compiler self
topaz lsp --compiler self
topaz doc --root app --locked --compiler self --out-dir api-docs
topaz compiler observe app/main.tpz --compiler self --out-dir observation
topaz check app/main.tpz --compiler rust
topaz compiler status --jsonПропущенный выбор означает, что при отсутствии флага --compiler Топаз по
умолчанию выполняет Rust Stage 0. Явный self указывает --compiler self для
вызова установленного Stage 2 self-компилятора на допустимых маршрутах текущего
режима. Выполнение происходит выбранным компилятором, без автоматического повтора
или скрытого отката. Явный self поддерживает parse, dump-ast, check,
текущие профили, отчёты об экспорте, run, test, bench, заблокированные
пакеты, compiler observe, проверенный вывод Rust и Python, нативные и Web-сборки,
Web/service dev, форматирование, LSP и документацию пакета. Один процесс LSP
сохраняет один выбор компилятора; после его изменения перезапустите сеанс редактора.
Флаг --verbose для команды, использующей компилятор, показывает, являлся ли
разрешённый выбор явным, текущим значением по умолчанию или режимом
совместимости.
Намерение выбора компилятора сохраняется до определения фактического режима
языка. Для пакетной команды CLI сначала читает и проверяет только корневой
topaz.toml. Разрешение зависимостей, проверка файла блокировки, чтение
исходных файлов, работа с кэшем и формирование результата выполняются позже.
Пакет со старым режимом языка использует Rust при пропущенном выборе или
явном rust, а явный self отклоняется до дальнейшей обработки. Поэтому выбор
по умолчанию для текущего режима и объявленный выбор совместимости с Rust
остаются раздельно отслеживаемыми.
Установленный процесс один раз проверяет и декодирует точный неизменяемый образ самокомпилируемого компилятора, после чего подготовленная программа совместно используется рабочими потоками self-компилятора и LSP. Ключ кэша включает идентичность образа, набора исходных файлов, схемы, шаблона среды выполнения и набора инструментов. Любое расхождение останавливает self-компиляцию. Исходные файлы цели, диагностика, сгенерированный код и управляемые результаты по-прежнему вычисляются для каждого запроса и не переиспользуются как подготовленное состояние компилятора. Подготовка укладывается в задокументированные пределы холодного запуска, LSP и памяти.
compiler status --json — машиночитаемый источник сведений об установленном
производителе, идентичности образа программы и набора исходных файлов,
поддерживаемых и отклоняемых маршрутах, решении при пропущенном выборе для
каждого маршрута, выборе по умолчанию, совместимости, восстановлении и запрете
скрытого отката. Управляемые артефакты также сообщают, являлся ли выбор явным,
текущим значением по умолчанию или режимом совместимости.
Граница восстановления установленного продукта
В установленном продукте проверки пакетов, тесты, сборки и запуск без исходного
кода используют значение по умолчанию Rust Stage 0. Явный self остается доступным
для отдельного выбора путем указания --compiler self на допустимых маршрутах
текущего режима. Повторная сборка одного управляемого каталога через Rust и self
атомарно заменяет происхождение.
С тем же установленным выбором по умолчанию двухмодульное учебное приложение проходит проверку, выбранный тест и нативную релизную сборку, а затем запускается без исходников. Полевой реестр закрывает только решённые проблемы продукта. Широкие проверки компилятора и интеграций остаются за кандидатом.
Установленные маршруты Stage 1 и Stage 2 создают из нового исходника отдельные свежие проверенные наблюдения. Явный self может затем собрать новый нативный продукт, который запускается без исходников.
Точный npm-продукт содержит оба варианта компилятора в одном исполняемом файле и не требует checkout репозитория. Продукт, собранный любым вариантом, запускается после удаления исходников Топаза. Если установленный образ самокомпилируемого компилятора отсутствует или повреждён, запрос self завершается ошибкой, не повторяет работу через Rust и не переиспользует его результат. Повторяйте исходную команду с --compiler rust только при явном выборе восстановления. Rust остаётся независимо доступен, а опубликованный комплект восстановления Stage 0 служит отдельным путём офлайн-реконструкции, а не автоматическим откатом.
Установленный self-компилятор теперь владеет полным версионированным продуктом компиляции текущего режима: упорядоченными модулями, токенами и AST, разрешением имён и экспортами, типизированной профильной диагностикой, пониженным представлением и требованиями среды выполнения, а также созданным Rust точным происхождением вызова и результата. Адаптер среды лишь проверяет и декодирует эти факты, не воссоздавая отсутствующие решения компилятора. Для допущенных команд общие пакетные и исполняющие компоненты потребляют один и тот же проверенный продукт.
Вывод Rust через self сохраняет таблицу IR фиксированной точки и добавляет только обычный фасад приложения. Таблицу исполняет общая целевая среда без образов компилятора. Она не может запускать парсер, разрешитель, проверку, понижение или генератор Rust. Манифест нативного артефакта фиксирует выбранный компилятор, производителя, наборы исходников компилятора и цели, продукт компиляции, хеш созданного исходника и targetCompilerFallback: false.
Доступные пути продукта
- CLI форматирует, проверяет, тестирует, запускает, генерирует исходный код и собирает файлы либо пакеты.
- Платформенная сборка создаёт исполняемый файл для текущей системы.
- Python-сборка создаёт
program.pyиtopaz_py_rt.py. Для их выполнения требуется Python 3.11 или новее. - Raw Web и Web Worker создают WASM-пакеты для существующей среды выполнения JavaScript.
- Web Application создаёт полноценный управляемый статический продукт для браузера.
- HTTP-сервис создаёт управляемый платформенный процесс HTTP/1.1 с фиксированными параметрами приёма соединений, запросов, очереди, времени выполнения, логирования и завершения.
- Пакетные команды используют манифесты, lock-файлы, зависимости по пути и проверенные зависимости, сохранённые вместе с проектом.
topaz lispex embed runвыполняет один запрос Лиспекса через точный вычислитель внутри установленного бинарного файла.topaz lispex embed info --jsonвыводит сведения об идентичности компонента, профиля, контракта, среды выполнения и политики без fallback.- Браузерная песочница предоставляет проверку и выполнение через интерпретатор без установки CLI Топаза.
Запуск вычислителя Лиспекса
Продукт принимает четыре именованных обычных файла или пути. Каталог результатов не должен существовать заранее:
topaz lispex embed run \
--source rule.lspx \
--input value.lpxvalue \
--limits limits.json \
--output lispex-resultУспешно завершённое вычисление записывает result.lpxvalue и report.json.
При детерминированной семантической ошибке или исчерпании лимита записывается только
report.json. При отказе запроса, нарушении контракта или ошибке движка
каталог не создаётся. Предварительный результат и транскрипт не пересекают
границу.
Вычислитель, профиль, политика среды выполнения и допуск зафиксированы в установленном продукте. Выбор вычислителя или профиля, загрузка sidecar, callback, импорт и fallback отсутствуют. Отчёт фиксирует выполнение и допуск Топаза, а переносимые ядра в формате Лиспекса создаёт API артефактов приложения. Подробности описаны в разделе Вычислитель Лиспекса и LIT.
Топаз предоставляет API полного текущего профиля std.lispex через
интерпретатор и все пять нативных релизных платформ. Процесс работы с
манифестом, lock-файлом, сборкой, артефактом и повтором описан в
разделе Запуск правил Лиспекса.
Маршруты generated-python, raw-web, worker-web, managed-web,
http-service, no-capability и mcp-empty-component-set отклоняют эту
возможность до записи артефакта или выполнения. Fallback отсутствует.
Наблюдения за компилятором
Снять наблюдение установленного компилятора
Установленный CLI позволяет записать текущий проверяемый конвейер компилятора вплоть до сгенерированного исходного кода Rust в единый канонический управляемый пакет:
topaz compiler observe --root my-app --locked --out-dir compiler-observation
topaz compiler validate compiler-observationРезультат следует размещать вне my-app. В противном случае при следующем наблюдении управляемый каталог результата может войти в состав фактов о каталогах пакета. Пакет содержит точные байты исходных файлов, набор исходных текстов, исходные и выровненные токены, AST, сведения о разрешении имён, структурированные типы, вызовы, захваты замыканий, пониженное представление без исходного текста, операции среды выполнения, сгенерированный код Rust, диагностику, запрос, ответ и происхождение. Обеспечивайте его защиту так же, как и для исходного пакета.
Проверить пакет наблюдения
Команда validate работает только на чтение. Она проверяет каноническую кодировку, схемы, порядок, перекрёстные ссылки, полноту, размеры и хеши без повторной компиляции и чтения исходного дерева файлов. В сведениях о происхождении производителем указан Rust Stage 0. Это описывает конкретный маршрут наблюдения, но не определяет язык реализации остальных этапов компилятора.
Понять границу сравнения
Граница сравнения раздельно оценивает семантические наблюдения, диагностику, сгенерированный исходный код, поведение созданного продукта и происхождение. Rust Stage 0 и Stage 1 Preview дают совпадающие результаты на заявленных многомодульном и отклоняемом диагностическом примерах. Для заявленного продукта сравнения скомпонованный и интерпретируемый маршруты Stage 1 формируют идентичный исходный код Rust, тогда как сгенерированный код Stage 0 и Stage 1 различается. Скомпилированный продукт Stage 1 выводит ровно 42. Неверная идентичность производителя или повреждённый управляемый продукт Stage 1 отклоняются без повторной компиляции целевого объекта через Stage 0.
Сравнить без клонирования репозитория
Установленный продукт позволяет выполнить точное сравнение без наличия рабочей копии репозитория:
topaz compiler observe main.tpz --terminal rust-source --out-dir rust-observation
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate rust-observation
topaz compiler validate stage1-observation
topaz compiler compare --layer semantic rust-observation stage1-observationПосле записи двух управляемых наблюдений операции проверки и сравнения больше не обращаются к исходному файлу программы. Если Stage 1 отклоняет запрос или завершается с ошибкой, резервное наблюдение не создаётся. Команда лишь выводит отдельную команду восстановления compiler observe, никогда не выполняя её неявно. Для явного выбора Rust Stage 0 следует указать --compiler rust в обычной команде check или сборки.
Выбрать границу сравнения
Два полных наблюдения можно сравнить на рубеже, соответствующем решаемой задаче:
topaz compiler compare --layer semantic observation-a observation-b
topaz compiler compare --layer generated-source observation-a observation-b
topaz compiler compare --layer provenance observation-a observation-b
topaz compiler compare --layer native-binary program-a program-bКоманда выводит одну каноническую запись JSON в пределах документированного лимита размера и завершается с ошибкой при расхождении в выбранном слое. Семантическое сравнение прекращается на первом отличающемся этапе компилятора. Сгенерированный исходный код и происхождение сравниваются независимо, поэтому смена производителя не меняет результат сравнения семантики языка.
Ограничения, важные для выбора
Все цели используют общий синтаксический анализ, разрешение модулей и статическую проверку, но операции, зависящие от среды, доступны не везде. Цель, которая не может сохранить операцию, должна отклонить её до записи продукта. В частности, сгенерированный Python отклоняет программу до записи артефакта, если она использует сжатие DEFLATE с фиксированными кодами Хаффмана, фиксированный zlib, вспомогательную функцию RS(255,223), функции преобразования toFloat и toIntRadix, методы Regex find и findAll или любой член Date, BigInt и Decimal. Отказ сообщается диагностикой TPZ6PY0001 с указанием позиции в исходном коде, а точный список членов приведён на странице бэкенд Python. Перед выбором цели для двоичных медиа, календарных дат и чисел произвольной точности проверьте страницы бэкендов.
HTTP-продукт реализует управляемый HTTP/1.1 с фиксированными настройками слушателя, запросов, очереди, дедлайна, журналирования и завершения. TLS, HTTP/2, WebSocket, исходящие сетевые запросы, неявные полномочия окружения, общее изменяемое состояние Топаза и универсальный веб-фреймворк находятся вне этого продукта.
Web Application использует объявленные возможности браузера. Raw Web и Worker требуют хост JavaScript. Playground запускает исходный код в браузере; развёртывание проверяется сгенерированным продуктом вне рабочего пространства исходного кода.
Порядок выполнения параллельных задач не определён. Объединяйте задачи перед упорядоченным выводом.
Установленный вычислитель обрабатывает topaz lispex embed, а выбор цели Топаза остаётся отдельной поверхностью. --target lispex отклоняется до записи артефакта. LIT — поверхность тестирования и интеграции Лиспекса из одной линии исходного кода, отделённая от установленного вычислителя и выходных бэкендов.
Рекомендуемый порядок
Начните с fmt --check, check и test. Используйте run для приложения командной строки и dev для веб-приложения или HTTP-сервиса. Соберите только необходимую цель и скопируйте весь её управляемый каталог.