Перейти к содержимому

Топаз6.0 · До релиза

Загрузка →

Инструменты

Пакеты, файлы фиксации и цели

Describe a package in topaz.toml, bind its inputs in topaz.lock, and select the artifact that build produces.

Package root and entry

A package root contains topaz.toml. Package-mode commands load that file from the selected root, which defaults to the current directory. The manifest is read before the package entry source.

Package loading source

[package] declares the package name, version, language mode, and entry path. The entry is relative to the package root. License metadata is optional. Unknown top-level sections and unknown fields in supported sections are rejected.

Manifest sections source · Package fields source

topaz init --root app creates a native package with a complete entry program. It refuses to overwrite an existing manifest or entry. Use that scaffold as the starting point for the configuration below.

Scaffold source

Configuration example

Complete native package configuration

Фрагмент синтаксиса

topaz.tomlComplete native package configurationОткрыть песочницу →

[package]
name = "reference_app"
version = "0.1.0"
language = "5.21"
entry = "src/main.tpz"
[build]
target = "native"
deterministic = true
[dependencies]
std = { version = "5.21" }

src/main.tpzComplete native package configurationОткрыть песочницу →

import std.io
export function main(args: Array<string>, stdin: string) -> Result<int, string> {
io.writeLine("Hello from Topaz")
Ok(0)
}

Целевой продукт 5.21.3

Ожидаемый результат

Ожидаемый результат

Configuration example. The command references own executable check, initialization, and lock examples.

Place both files under the same package root. Run package-mode commands from that root, or select it with --root.

Dependency identity

Each dependency declaration uses a table. A version dependency has version and may have hash. A path dependency has path and requires hash. The table chooses exactly one of version and path. A bare version string is rejected when the package manifest is loaded.

Dependency declaration source

Registry dependency compilation requires --locked and matching content under vendor/<name>/<version>. The dependency package name and version must agree with the declaration. A local dependency's manifest name must also agree with its declared name.

Package dependency loading source

[exports].module selects the module a dependency exposes as its root. Without that section, its package entry supplies the root. A dependency name that collides with a root module path is rejected. These configuration relationships do not redefine source import syntax.

What topaz.lock binds

topaz.lock records the root package identity and a manifest_hash derived from the manifest text. It also binds declared dependency identities and content hashes. Changing a locked input requires a corresponding lock update.

Lock verification source · Manifest digest source

--locked verifies the existing lock before the applicable package operation continues. Missing, stale, duplicate, or undeclared lock entries are rejected. topaz lock writes the lock for the current manifest. It does not waive a mismatched local dependency hash.

Lock verification also checks declared extern artifacts and replay inputs, plus embedded Lispex source, limits, quotas, and prepared artifacts when present. A matching root manifest hash does not replace those checks.

Select the build artifact

[build].target selects native, web, or web-worker. An omitted build target selects native. Ordinary package loading requires deterministic builds. The separate usage-profile validation path does not enable an unrestricted nondeterministic build.

Build configuration source

For package builds, an explicit command target takes precedence over the manifest target. Without a command target, build uses the manifest. Entry-file builds use their command target or the native default. Web targets cannot be combined with automatic execution through --run.

Package build selection source

The target describes the resulting artifact. It does not select SELF or the reference compiler. emit has a separate Rust-source target and does not produce a final native or web binary.

Embedded Lispex configuration

[lispex] selects a package-owned evaluator profile and declares at least one [[lispex.rule]]. Each rule has a unique name and distinct project-relative source and limits paths. A package containing this section requires locked compilation.

Lispex configuration source · Locked package requirement

An application identifier and its application_quotas file appear together. The application and evaluator profile must be a supported pair. In the current language mode, application configuration also requires the exact standard-library version for that mode.

Application binding source

The Lispex admission contract defines package admission and component identities. The factory contract defines generated calls from the verified lock. Installed profile availability requires distribution evidence.

Lispex lock verification follows the package admission and generated factory contracts. Changing a locked input requires a matching lock update.

Additional package inputs

[capabilities.fs] declares project-relative read and write roots. [extern] declares externally implemented modules and their associated inputs. An extern module cannot occupy a root path already used by a local module or dependency.

Capability and export declarations · Extern module collision source

The complete external ABI and host sandbox behavior belong to their own reference contracts. This page records their effect on package identity and lock verification.

Pending contracts

One registry materialization command

Правилоtopaz.tools.registry-command.rule

One registry materialization command

Use topaz vendor --from <registry> for registry dependency materialization. topaz fetch is rejected during command validation.

The vendor command without --from checks existing vendored content and updates the lock. Supplying --from also copies the selected registry content.

Причина

Both reviewed command names materialize the same dependencies in the vendor directory and write the same lock. They express the same dependency materialization intent. The vendor name identifies the destination.

Примеры Reject the fetch command alias →Materialize a registry dependency with vendor →

Диагностика One registry materialization command rejection →

One registry materialization command rejection

Семейство: topaz-cli
Этап: command
Операция: argument-validation
Категория: registry-command

Причина и условия

Use topaz vendor --from <registry> for registry dependency materialization. topaz fetch is rejected during command validation.

Связанное правило · One registry materialization command →

Действия

Use topaz vendor --from <registry> to materialize registry dependencies.

One registry materialization command examples

Reject the fetch command alias

reject · command-validation · Проверка · Не выполнялось

main.tpzReject the fetch command aliasОткрыть песочницу →

let value = 1

Ожидаемый выводКод завершения 1

Нет стандартного вывода.

$ topaz fetch --root . --from registry · Целевой продукт 5.21.3

topaz.tomlReject the fetch command aliasОткрыть песочницу →

[package]
name = "tools_registry_example"
version = "0.1.0"
language = "5.21"
entry = "main.tpz"
[build]
target = "native"
deterministic = true
[dependencies]
sample = { version = "1.0.0" }

registry/sample/1.0.0/topaz.tomlReject the fetch command aliasОткрыть песочницу →

[package]
name = "sample"
version = "1.0.0"
language = "5.21"
entry = "main.tpz"

registry/sample/1.0.0/main.tpzReject the fetch command aliasОткрыть песочницу →

export let value = 1

Ожидаемый результат

Ожидаемый результат

Этап отклонения command. Код завершения 1.

One registry materialization command rejection →
tools-unknown-command

Нет стандартного вывода.

Этот пример ещё не выполнялся.

Materialize a registry dependency with vendor

check · command-validation · Проверка · Не выполнялось

main.tpzMaterialize a registry dependency with vendorОткрыть песочницу →

let value = 1

Ожидаемый выводКод завершения 0

Нет стандартного вывода.

$ topaz vendor --root . --from registry · Целевой продукт 5.21.3

topaz.tomlMaterialize a registry dependency with vendorОткрыть песочницу →

[package]
name = "tools_registry_example"
version = "0.1.0"
language = "5.21"
entry = "main.tpz"
[build]
target = "native"
deterministic = true
[dependencies]
sample = { version = "1.0.0" }

registry/sample/1.0.0/topaz.tomlMaterialize a registry dependency with vendorОткрыть песочницу →

[package]
name = "sample"
version = "1.0.0"
language = "5.21"
entry = "main.tpz"

registry/sample/1.0.0/main.tpzMaterialize a registry dependency with vendorОткрыть песочницу →

export let value = 1

Ожидаемый результат

Ожидаемый результат

Проверка принимает программу. Код завершения 0.

Нет стандартного вывода.

Этот пример ещё не выполнялся.

Dependency declarations use tables

Правилоtopaz.tools.dependency-table.rule

Dependency declarations use tables

Each entry in [dependencies] is a table. A bare version string is rejected while the package manifest is loaded.

A version dependency uses version and may include hash. A path dependency uses path and requires hash. Each table chooses exactly one of version and path.

Причина

A version string and a table containing that version select the same dependency. The table preserves this intent and carries version, path, and content hash fields through one declaration structure.

Примеры Reject a version string dependency →Lock a table dependency →

Диагностика Dependency declarations use tables rejection →

Dependency declarations use tables rejection

Семейство: topaz-cli
Этап: package
Операция: manifest-admission
Категория: dependency-table

Причина и условия

Each entry in [dependencies] is a table. A bare version string is rejected while the package manifest is loaded.

Связанное правило · Dependency declarations use tables →

Действия

Use a table such as std = { version = "5.21" } in [dependencies].

Dependency declarations use tables examples

Reject a version string dependency

reject · package-configuration · Проверка · Не выполнялось

topaz.tomlReject a version string dependencyОткрыть песочницу →

[package]
name = "tools_dependency_table"
version = "0.1.0"
language = "5.21"
entry = "main.tpz"
[dependencies]
std = "5.21"

main.tpzReject a version string dependencyОткрыть песочницу →

let value = 1

Ожидаемый выводКод завершения 1

Нет стандартного вывода.

$ topaz lock --root . · Целевой продукт 5.21.3

Ожидаемый результат

Ожидаемый результат

Этап отклонения package. Код завершения 1.

Dependency declarations use tables rejection →
tools-dependency-table-required

Нет стандартного вывода.

Этот пример ещё не выполнялся.

Lock a table dependency

check · package-configuration · Проверка · Не выполнялось

topaz.tomlLock a table dependencyОткрыть песочницу →

[package]
name = "tools_dependency_table"
version = "0.1.0"
language = "5.21"
entry = "main.tpz"
[dependencies]
std = { version = "5.21" }

main.tpzLock a table dependencyОткрыть песочницу →

let value = 1

Ожидаемый выводКод завершения 0

Нет стандартного вывода.

$ topaz lock --root . · Целевой продукт 5.21.3

Ожидаемый результат

Ожидаемый результат

Проверка принимает программу. Код завершения 0.

Нет стандартного вывода.

Этот пример ещё не выполнялся.

Compiler selection →