Проверьте, какой компилятор Топаза установлен, и выберите среду для запуска программы. В подробных разделах ниже показано, как сохранить и прочитать записи компиляции для поиска ошибок компилятора.
Проверка установки
Установите CLI Топаза, затем выполните команду в терминале.
topaz version --verboseВывод содержит версию компилятора, режим языка, версию среды выполнения и бэкенд Rust. Эти две строки показывают режим языка и бэкенд.
Language mode: topaz-5.20
Rust backend: rust (CDR-006)Rust backend означает, что при нативной сборке создаётся код Rust. Компилятор по умолчанию написан на Топазе. При сообщении о проблеме установки приложите полный вывод. Если терминал не находит topaz, откройте его заново и проверьте каталог установки в PATH.
Сейчас доступен Топаз 5.20.4. Текущий режим языка имеет имя topaz-5.20. Официальные релизы доступны на topaz.ooo и в npm. Исходный код размещён на topaz.ooo/dl.
Пакет npm содержит компилятор в одном исполняемом файле и не требует клона репозитория. Исполняемый файл хранит исходный код для приложений Лиспекс и образ программы компилятора в сжатом виде и распаковывает каждый из них, когда команда впервые его использует. Собранные продукты работают после удаления исходного кода Топаза. При несовпадении встроенных идентификаторов компилятора команда останавливается до компиляции и сообщает об ошибке. Переустановите Топаз, чтобы восстановить установку.
Выбор среды выполнения
| Задача | Продукт и требования |
|---|---|
| Проверить и запустить локальный код | CLI проверяет файлы и многофайловые пакеты, затем запускает их через интерпретатор |
| Выпустить программу для компьютера или сервера | --target native собирает исполняемый файл для платформы через Rust и Cargo |
| Вызывать Топаз из JavaScript | --target web собирает пакет WASM для существующей среды JavaScript |
| Выполнять вызовы в браузерном Worker | --target web-worker добавляет модули запросов и ответов Worker |
| Попробовать код без установки CLI | Браузерная песочница проверяет и интерпретирует исходный код |
Для сборки WASM также нужна цель Rust wasm32-unknown-unknown. Выберите цель и полный пример в разделе Интерпретатор и бэкенды. При развёртывании копируйте весь каталог результатов сборки.
Все цели используют общие разбор синтаксиса, разрешение модулей и проверку типов. Поддержка операций среды зависит от цели. Неподдерживаемая операция вызывает ошибку с позицией в исходном коде до записи продукта. Исправьте операцию или выберите среду, которая её поддерживает. Порядок выполнения параллельных задач не задан. Дождитесь их завершения перед упорядоченным выводом.
Запуск правил Лиспекса
Встроенный вычислитель выполняет один запрос командой topaz lispex embed run. В разделе Вычислитель Лиспекса и LIT приведены три входных файла, команда и поля отчёта. Завершённое вычисление записывает result.lpxvalue и report.json. При ошибке правила или исчерпании ресурсов записывается report.json. При отклонении запроса или ошибке движка каталог результатов не создаётся.
Установленный продукт фиксирует вычислитель, профиль, правила использования ресурсов и проверки входных данных. Он не загружает другой вычислитель и не использует обратные вызовы, импорт или fallback. Отчёт CLI описывает выполнение в Топазе. API артефактов приложения создаёт переносимые записи в формате Лиспекса.
Для вызова правил из приложения Топаза используйте API std.lispex с зафиксированными зависимостями. Он работает в интерпретаторе и на всех пяти нативных релизных платформах. Запуск правил Лиспекса описывает манифест, lock-файл, сборку, сохранение результатов и повторный запуск. raw-web, worker-web, no-capability и mcp-empty-component-set отклоняют эти вызовы до записи результатов или выполнения. --target lispex также отклоняется до записи результатов. LIT служит программой для интеграционных тестов Лиспекса и отделён от встроенного вычислителя и целей сборки.
Чтение статуса компилятора
topaz compiler status --jsonКоманда выводит JSON и завершается с кодом 0. Здесь показаны поля, определяющие компилятор по умолчанию и эталонный компилятор.
{
"schema": "topaz.compiler-support/v5",
"languageMode": "topaz-5.20",
"defaultCompiler": "self",
"referenceCompiler": "rust",
"silentFallback": false
}self выбирает компилятор, написанный на Топазе. По умолчанию его используют parse, check, test, run, bench, emit, build, fmt, lsp, doc и compiler observe. При ошибке компилятора команда останавливается без переключения на Rust.
В массиве compilers найдите объект, у которого selector равен self. Его поля и отдельный массив routes читаются следующим образом.
| Поле | Что проверить |
|---|---|
status, executionKind | Исправный нативный компилятор сообщает supported и native |
sourceSetId, runtimeSourceSetId | Идентификаторы исходных файлов компилятора и среды выполнения |
nativeLinkId, generatedRustSha256 | Идентификаторы скомпонованного компилятора и сгенерированного кода Rust |
target | Платформа установленного компилятора |
routes[].command | Команда, описанная в списке |
routes[].self, routes[].condition | Поддержка команды и условия её использования |
routes[].omitted | Компилятор, используемый без --compiler |
Сохранение наблюдения компилятора
Наблюдение компилятора записывает обработку одного входа вплоть до сгенерированного Rust. Оно помогает исследовать различия результатов компиляции. В каталоге есть исходный код, поэтому защищайте его так же, как исходный проект.
Создайте пустой рабочий каталог. Сохраните в нём следующий файл main.tpz.
print("ready")Выполните команды из этого каталога. Пути с ../ размещают результаты рядом с каталогом исходного кода. Выберите ещё не использованные каталоги. Вывод внутри корня исходного кода отклоняется, поскольку следующее наблюдение могло бы включить собственные файлы.
topaz compiler observe main.tpz --out-dir ../topaz-observation
topaz compiler validate ../topaz-observationОбе команды завершаются с кодом 0 и последовательно выводят эти строки.
../topaz-observation: compiler-observation-ok
../topaz-observation: compiler-observation-validКаталог содержит sources/, topaz-observation.json, provenance.json и записи каждого этапа компиляции. validate читает его без изменения файлов, повторной компиляции или обращения к исходному дереву. Команда проверяет кодирование, схемы, порядок, ссылки, обязательные записи, размеры и хеши. При ошибке проверки сохраните сообщение и создайте новое наблюдение из исходного кода.
Чтение записей компиляции
Установленный исполняемый файл содержит нативный компилятор, сгенерированный из исходного кода Топаза. Перед компиляцией адаптер проверяет встроенные идентификаторы исходников и среды выполнения. Несовпадение останавливает команду. Исходники целевой программы, диагностика, сгенерированный код и выходные файлы вычисляются заново для каждого запроса.
Результат компиляции имеет версию и содержит упорядоченные модули, токены, синтаксическое дерево, разрешённые имена и экспорты, типы и диагностику профиля. Профиль задаёт поддерживаемые функции и правила выполнения. Результат также хранит внутреннее преобразование кода (lowering), необходимые операции среды выполнения, сгенерированный Rust, идентификаторы запроса и результата. Адаптер проверяет и декодирует эти записи. Отсутствующие решения компилятора вызывают отказ.
Манифест нативной сборки записывает компилятор и производителя, наборы исходных файлов компилятора и цели, результат компиляции и хеш сгенерированного кода. Набор исходных файлов включает файлы одной компиляции.
Неподвижная точка и сведения о производителе
Откройте ../topaz-observation/provenance.json, чтобы узнать, какой компилятор и какие входные данные создали результат. Следующие поля описывают разные проверки.
{
"engine": "topaz-native-k",
"generatedSourceFixedPoint": "established",
"nativeBinaryReproducibility": "not-run",
"semanticFixedPoint": "not-established"
}generatedSourceFixedPoint показывает, дали ли последовательные этапы компиляции собственного кода одинаковые байты сгенерированного Rust. Это неподвижная точка сгенерированного кода. nativeBinaryReproducibility описывает сравнение байтов исполняемого файла. semanticFixedPoint относится к промежуточным записям компилятора. Читайте каждое значение отдельно. Эти поля находятся в файле происхождения наблюдения. Идентификаторы компоновки и исходников установленного компилятора, а также поддерживаемые команды смотрите в JSON статуса выше.
Сравнение с эталонным компилятором
Установленный исполняемый файл также содержит эталонный компилятор на Rust для проверки. Из того же каталога создайте им наблюдение неизменённого main.tpz.
topaz compiler observe main.tpz --compiler rust --out-dir ../reference-observation
topaz compiler compare --layer semantic ../topaz-observation ../reference-observationПервая команда создаёт ../reference-observation и выводит ../reference-observation: compiler-observation-ok. Вторая выводит JSON. equal сообщает результат сравнения, firstFailingPhase указывает первый различающийся этап, а mismatches перечисляет различия записей. При совпадении код завершения равен 0, при различии он равен 1.
Если одинаковый вход даёт разные записи компиляторов, сохраните оба каталога и JSON-отчёт для исследования дефекта компилятора. --compiler rust выбирают для проверки. После ошибки self команды не повторяют компиляцию эталонным компилятором. Язык и совместимость объясняет слои сравнения и показывает, как изменение входа отражается в JSON.