Files
ziran/docs/PACKAGES.md
waozi fc11f5cefb
Build check / check (push) Canceled after 6m6s
Build and verify versioned ZX library packages
2026-11-20 17:04:13 -03:00

39 KiB

Packages and project imports

Ziran packages are Git repositories. There is no central registry: a dependency is the URL of the repository that holds it, pinned to a full commit in a committed ziran.lock. A Ziran application is itself a package with a ziran.toml. make install-user installs the native ziran command; project commands build and use the compiler pinned by the application lock, and hand the command to that toolchain's own launcher, so an installed ziran that is older or newer than the lock behaves exactly like the pinned one.

Starting a project

ziran new DIR writes a project from a template and locks it:

ziran new hello                        # a command-line program (template cli)
ziran new geometry --template lib      # a library with one exported module
ziran new calc --template kryonlabs/kryon          # a package's first template
ziran new calc --template kryonlabs/kryon:tui      # one of its named templates
ziran new calc --template ../my-templates:service  # a local package directory

cli and lib ship with Ziran. Any package can offer templates by listing directories in its ziran.toml; the first one is the default:

[templates]
app = "templates/app"
tui = "templates/tui"

A template directory holds a ziran.toml and whatever files a project starts with. In file contents and paths, {{name}} becomes the package name and {{module}} the same name as an identifier (my-tool becomes my_tool). --name NAME sets the name when the directory's name is not one, and --ref REF fetches the template from another branch, tag, or commit.

--overrides FILE copies a validated local configuration into the new project's ignored ziran.local.toml before locking. Use it with a local template and overrides for the toolchain and dependencies to build against existing source checkouts without fetching copies. Relative override paths are relative to the created project. An existing ziran.local.toml is never overwritten, including when applying a template with init.

ziran init --template SOURCE applies a template to the project in the current directory. It never overwrites a file. When the project already has a ziran.toml, the template's manifest is merged into it: missing tables and keys are added, string arrays such as module_roots gain the template's entries, and every other value the project already sets is kept and reported. That is how an existing command-line program becomes, for example, a Kryon application: the template adds the dependency, tool = "kryon", and the [tool.kryon] settings, and keeps the program's own entry.

Building and running a program

In a project directory, run, build, check, and install without a file work on the project's program:

ziran run                 # build, then run the entry module's main
ziran run -- one two      # arguments after -- go to the program
ziran build               # build/NAME
ziran check               # check the entry, or a library's exports
ziran install             # copy the program to ~/.local/bin/NAME

The program is the main procedure of [package] entry, which takes nothing or (argc: s32, argv: **u8) and returns nothing or its exit status. Ziran writes C and compiles it with CC (default cc), honoring CFLAGS, LDFLAGS, and LDLIBS. [package] links names system libraries to link:

[package]
name = "fetcher"
entry = "src/main.zi"
links = ["curl"]

Names are linker library basenames, such as gio-2.0, gdk_pixbuf-2.0, or stdc++, without lib, a filename suffix or -l. They start with a letter, digit or underscore and may then contain letters, digits, underscores, hyphens, dots and plus signs. Paths, options and shell syntax are rejected.

System links also apply when building an explicit source file with ziran build --project --target=c --exe, alongside the caller's LDLIBS.

System links apply to the root manifest that declares them; they are not inherited from a dependency's [package] table. For example, a native consumer of audio/pipeline and audio/resample declares links = ["opus", "samplerate", "m"] in its own [package] table. An audio/opus codec-only consumer needs links = ["opus", "m"]. Portable audio/ogg inspection and audio/wav conversion need no codec libraries. A custom native host supplies the corresponding linker flags.

ziran install --prefix DIR installs under DIR/bin; [install] bin changes the command name. The copy replaces an installed program in one step.

A project whose [package] tool names a dependency hands these four commands to that dependency's project tool instead (see below). Naming a file, as in ziran check --project src/cell.zi, or passing --target, keeps the command on that file or target.

Adding a dependency

Pass any spelling of the repository to ziran add:

ziran add https://github.com/kryonlabs/plot.git
ziran add [email protected]:kryonlabs/plot.git
ziran add ssh://[email protected]/owner/repo.git
ziran add codeberg.org/owner/repo
ziran add kryonlabs/plot            # OWNER/REPO means GitHub

The dependency is named after the repository (plot; kryon-ui becomes kryon_ui). Use --name NAME for another name, --ref REF for a branch, tag, or full commit instead of master, and --source for a repository that is not a Ziran package. ziran add writes the declaration, locks it, and prints the modules you can import:

[dependencies.plot]
git = "[email protected]:kryonlabs/plot.git"
ref = "master"

HTTPS and SSH name the same package. Ziran identifies a repository by its canonical HTTPS spelling, so switching a manifest between the two keeps the lock valid, and two packages that reach one repository over different transports share a single locked copy. Ziran fetches over the transport the manifest names; when that fails, for example SSH without a key in CI or HTTPS without credentials for a private repository, it retries once over the other transport. It never prompts for a password. URLs with embedded credentials are rejected.

Importing modules

A dependency's exported modules are imported by the dependency name and the module name, so every import says where it comes from:

#import "plot/Plot"
Text :: #import "kryon/text";
Desktop :: #import "kryon/host/desktop";
#import "std/text";

std/NAME is the pinned standard library. Modules in your own package use their short names. A package can also import its own public exports as PACKAGE/EXPORT, where PACKAGE is its [package] name and EXPORT is an identifier or slash-separated identifier namespace used as a quoted key in its [exports] table. For example, a package named plot exporting Plot = "src/module.zi" can import plot/Plot internally. A quoted export "host/desktop" = "src/desktop.zi" is imported as plot/host/desktop. Slashes organize the public namespace; they do not expose the package's directory tree. This works both when building that package directly and when it is a dependency, even if a consumer gives it a different dependency alias. Private modules still use short names inside their package; self qualification exposes only public exports and grants no access to transitive dependencies. Short-name resolution is unchanged. If a direct dependency alias equals the package's own name, that alias retains the whole qualified namespace; use short names for your own modules in that case. ziran pkg list shows each direct dependency, its URL, ref, commit and checkout, and every import path it provides:

plot  [email protected]:kryonlabs/plot.git  master  3e1433d0b2c1
  checkout /home/me/.cache/ziran/sources/p1f0c…
  #import "plot/Plot"                src/module.zi
std  /home/me/.cache/ziran/sources/p5a7…/std
  #import "std/NAME"               the standard library

A short import such as #import "Plot" also works. A short name resolves in the importing package first, then among its direct dependencies' exports, then in the standard library. When two direct dependencies export the same name, the short import reports both qualified spellings; import one of them, or rename one with module_aliases:

[dependencies.Graphics]
git = "https://example.com/graphics.git"
ref = "master"
module_aliases = { Drawing = "GraphicsDrawing" }

Only the dependency's [exports] are visible. Its other modules are private to it, so their names never collide with yours.

Generated modules

A build step can write modules for your program, such as translations or level tables. Pass their folder to the project command that needs them:

ziran bundle --project --module-path build/gen --entry app:main -o app.zx src/app.zi
ziran check --project --module-path build/gen

module_roots and repeated --module-path DIR have no fixed folder-count limit. Storage follows the input size, subject to manifest-size, allocation and operating-system argument limits.

Each --module-path DIR (repeatable) adds DIR/NAME.zi and DIR/NAME/module.zi to your package's own modules, as if they were under a module_roots folder. Everything else still resolves from ziran.lock. The folder belongs to your package only: dependencies never see its modules, so a generated Value cannot replace a dependency's own Value. A generated module may not share a name with one of your modules, and the folder may not lie inside a locked package or the toolchain. Packages come from the lock, so the standalone NAME=DIR spelling is refused here.

Commands that don't pass the folder never look for it, so lock, update, fetch and check work on a fresh checkout before the build step has run; only an import of a module that isn't there yet fails. A project tool that runs ziran build, run or check for the project receives the same --module-path arguments. Without --project, --module-path keeps a command standalone.

Publishing a package

An exported module is a package-owned file. Its public name may differ from the file name, so a package can keep the short path src/module.zi:

[package]
name = "Plot"
module_roots = ["src"]

[toolchain]
git = "https://github.com/ziranlang/ziran.git"
ref = "master"

[exports]
Plot = "src/module.zi"
"host/desktop" = "src/host/desktop.zi"

Push the repository anywhere Git can reach. Prefer HTTPS URLs in published manifests so fresh clones and CI can fetch without an SSH key.

Package modules receive an internal identity derived from their repository and commit. Two versions of a transitive dependency can coexist in one build. The identity is carried through ZIR, saved .zir, portable bundles, and native output names.

Commands

ziran add URL|OWNER/REPO
ziran lock
ziran update
ziran update plot
ziran update ziran
ziran fetch
ziran pkg list [plot]
ziran pkg path plot --locked
ziran pkg paths plot ziran --locked
ziran check --project
ziran ir --project --entry app:main -o build/ir
ziran build --project --target=c --entry app:main -o build/c

ziran update refreshes every package and the toolchain to their current refs. ziran update plot refreshes Plot and its transitive dependencies while keeping unrelated packages pinned. ziran update ziran refreshes only the compiler toolchain.

To generate a normal lock directly from local Git objects, set ZIRAN_LOCK_GIT_OBJECTS for ziran lock:

ZIRAN_LOCK_GIT_OBJECTS=/repos/plot:/repos/ziran ziran lock

List absolute paths to Git directories or repository roots containing a .git directory, separated by colons. For each dependency and the toolchain, Ziran verifies the exact commit in the first store whose origin matches the declared URL, using the usual HTTPS and SSH equivalence. Other sources use existing exact-commit cache entries. A branch or tag declaration requires a matching pin in the existing lock. Ziran reads package manifests from the pinned commits, ignores ziran.local.toml, and leaves the repositories and source cache alone. Missing stores, commits, or valid manifests fail the lock command without fetching or creating checkouts. The resulting lock uses the usual format and can be used with --locked once the project's development overrides are removed. Build commands still require their normal locked source checkouts.

--locked requires a matching lock and ignores local development overrides; --offline requires cached checkouts. The cache is under $XDG_CACHE_HOME/ziran or ~/.cache/ziran. Normal fetch and pkg path commands also validate cached tracked payloads. If an immutable source-cache entry has missing files or staged deletions only, they restore the locked source from existing Git objects, including with --locked --offline; no separate repair command or network access is needed. A matching HEAD alone does not establish that the source is ready. Modified tracked files, or untracked/ignored data alongside missing files, prevent repair and produce a package cache ... preserved at diagnostic. Failed entries are never automatically deleted. Redirected, sparse or flagged checkouts are refused; explicit local overrides remain user-owned and are never repaired this way.

ziran pkg path returns the checkout selected by the lock, including a unique transitive dependency. Add --submodules when a platform build needs its vendored backend source. The command initializes the submodules at the commits recorded by that package; with --offline, it requires them to be present.

ziran pkg paths PACKAGE... resolves several selectors with one graph checkout and validation in the selected launcher. It uses the same direct-alias and unique transitive package-name selection as pkg path, including ziran for the toolchain, and accepts --locked, --offline, and a trailing --submodules. Pinned-launcher forwarding and cache validation remain the same as pkg path. On success stdout is a JSON array in argument order, with repetitions retained:

[{"selector":"plot","path":"/home/user/.cache/ziran/sources/p123"},
 {"selector":"ziran","path":"/home/user/Projects/ziranlang/ziran"}]

Each object contains the original selector and its authoritative absolute path. JSON escaping preserves spaces, quotes, backslashes and control characters. An empty selection, missing or ambiguous package, graph-validation failure, or missing requested submodules returns nonzero with no result on stdout. Resolve the full batch before consuming any paths.

A platform build can also pin a repository that is not a Ziran package, such as a C library it compiles from source. Mark the dependency with source = true:

[dependencies.sqlite]
git = "https://github.com/sqlite/sqlite.git"
ref = "master"
source = true

ziran add URL --name sqlite --source writes the same declaration. A source package is locked, fetched, and cached like any other dependency, and ziran pkg path sqlite --locked returns its checkout, but it has no ziran.toml, exports no modules, and cannot declare dependencies or module aliases. Build scripts use that path instead of a vendor/ submodule.

For local development, an ignored ziran.local.toml can map package names to working directories:

[overrides]
kryon = "../../kryonlabs/kryon"
ziran = "../../ziranlang/ziran"

Each override is the top of its own Git checkout: ziran lock records the commit checked out there. An explicitly overridden checkout whose branch has no first commit is also usable for local development, including an overridden toolchain. Its lock entry has a development field instead of commit, with an unborn: identity derived deterministically from the canonical checkout path. This identifies local source; it does not claim a committed revision or a reproducible source snapshot. This is an optional field in lock format 1. Only a genuine unborn branch qualifies; missing commit objects and invalid Git metadata are refused. A directory inside another repository, such as an uninitialized submodule, is refused, because its HEAD would be the enclosing repository's commit. A root dependency's override selects that source for all incoming edges, including transitive dependencies with different aliases or exact revision pins. These edges use one actual checkout and module type identity. The lock records each edge's declared ref separately, so changing a ref, URL, alias or source kind in the root manifest still requires ziran lock. Source-only edits and newer local commits can be used without changing those declarations; build commands derive local module identities from the actual checkout HEAD. When several locked revisions select a checkout whose commit is already in the lock, they use that commit's locked dependency graph before merging their identities. When an overridden checkout's own manifest declares other dependencies than the lock records, local commands resolve the graph from the working manifests in memory, as ziran lock would, keeping every unchanged pin, and print a note; with --offline a newly declared branch ref cannot be resolved. Packages without an override and --locked keep the exact check. The lock on disk remains unchanged. Conflicting overrides for one source are refused.

After removing overrides, run ziran lock to resolve the declared revisions again. Development-only entries require their explicit overrides and cannot be fetched into the immutable cache. --locked rejects a development-only lock even after overrides have been removed. Once a checkout has its first commit, ziran lock records the real commit instead. Exact pins select their declared commits rather than retaining a local development identity or newer override commit. --locked refuses an override-only ref substitution. Targeted updates cannot preserve an unrelated unborn package or toolchain's source snapshot; use ziran lock or a full ziran update while developing such a graph.

Production builds omit overrides and use the locked Git commits. A host module that calls into the application can use an explicit reverse bridge:

[package]
bridge_modules = ["app"]

This makes only the named app module visible to direct dependencies. It does not change the package's public exports. Native system libraries remain ordinary platform build dependencies.

Project tools and their options

A package can ship a project tool, such as the command that builds an application with a UI library. It names the tool and declares the options an application may set for it in its own ziran.toml:

[tool]
project = "build/bin/kryon"

[options]
default_profile = "string"

[options.profiles."*"]
backend = "string!"
codegen = "string=c99"

[options.install]
autostart = "bool=false"

[options] holds top-level keys, [options.NAME] one table, and [options.NAME."*"] any number of named tables. Each value is "string" or "bool", followed by ! when it is required or =DEFAULT for a default.

The application sets those options under the dependency's alias, and its ignored ziran.local.toml may replace any of them on one machine:

[tool.kryon]
default_profile = "desktop"

[tool.kryon.profiles.desktop]
backend = "desktop"

ziran tool kryon COMMAND rebuilds the tool if its sources changed, checks every setting against the declaration, and reports an unknown or missing key with its file and line. It then runs the tool from the project root. The tool reads the merged settings as KEY=VALUE lines from the file named by ZIRAN_TOOL_OPTIONS, for example default_profile=desktop, profiles=desktop and profiles.desktop.backend=desktop, so no tool parses TOML itself. ZIRAN_PROJECT_LINKS contains the validated root system library names in manifest order, separated by spaces; native project tools append each as a -l argument. ZIRAN_PROJECT_ROOT, ZIRAN_PROJECT_NAME, ZIRAN_PROJECT_ENTRY, ZIRAN_PROJECT_LINKS, ZIRAN_PACKAGE_ROOT, ZIRAN_PACKAGE_ID and ZIRAN_TOOLCHAIN_ROOT describe the project and the tool's checkout.

Handing a project to its tool

[package] tool names the dependency whose project tool runs, builds, checks, and installs the application, and [install] bin the command name it installs as:

[package]
name = "example"
entry = "src/app.zi"
tool = "kryon"

[install]
bin = "example"

ziran run, ziran build, and ziran check without a file then run ziran tool kryon run, build, or check with the remaining arguments, so ziran run desktop is ziran tool kryon run desktop. ziran install runs the tool's install command with ZIRAN_INSTALL_PREFIX (~/.local unless --prefix DIR is given) and ZIRAN_INSTALL_BIN; other arguments are passed on. The tool decides what else an install includes, such as a desktop entry, from its own options.

Prebuilt portable images

Build a .zx application or an explicitly exported ZX library once, then publish the image to the repository owner's Gitea Generic package registry. The repository name, full Git commit and build profile form the download address. Give each combination of exports, compiler settings and feature defines its own profile. The publishing job should build from the exact revision and record its toolchain and dependency locks. Gitea Generic package registry

zi2zx --library demo/counter --export counter:Add -o counter.zx counter.zi
repo=https://git.waozi.xyz/example/counter.git
commit=$(git rev-parse HEAD)
ziran pkg zx publish "$repo" "$commit" counter counter.zx --netrc "$NETRC_FILE"

The publishing command validates the image and prints its SHA-256. A repeat upload succeeds if the registry already holds those exact bytes. The netrc file supplies credentials for the HTTPS host and should be readable only by the publishing account. Publishing needs Gitea package-write access.

Pin the repository, commit, profile and printed digest in the consumer's build configuration. For a library, pass the declared module name to obtain a module root the ZX loader can search. The consumer can build its own app and run it with the library source absent. See the typed import example in Loading libraries.

modules=$(ziran pkg zx fetch "$repo" "$commit" counter "$sha256" --module demo/counter)
ziran run --backend engine --module-root "$modules" app.zx

For normal builds, put the same pins and typed import mappings in a JSON file such as ziran.zx.lock. Use the full commit and SHA-256 from the publishing job in place of the example values.

{
  "format": 1,
  "modules": [
    {
      "interface": "Counter.v1",
      "name": "demo/counter",
      "repository": "https://git.waozi.xyz/example/counter.git",
      "commit": "0123456789abcdef0123456789abcdef01234567",
      "profile": "counter",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ],
  "imports": [
    {"module": "app", "function": "AddExternal", "interface": "Counter.v1", "export": "Add"}
  ]
}
ziran bundle --zx-lock ziran.zx.lock --root . --entry app:main -o app.zx app.zi
ziran run --backend engine --zx-lock ziran.zx.lock app.zx

The build uses app.zi's typed foreign declaration and the pin file's import mapping. Packaged library bodies are never compiled by the consumer. The run command fetches any missing pinned images before opening the app. Include any transitive ZX libraries in modules, with unique interface and logical names. The runner resolves that exact image map and verifies each image's SHA-256 again on the bytes it opens. A locked run uses the local runtime and its host bindings. Set ZIRAN_PACKAGE_NETRC for a private registry.

For an application image, omit --module to get the verified image path. --offline requires the exact image to be in the local cache. A failed download, digest, image format or module name stops the command. The loader still checks typed imports and requires the host grants used by the image. This workflow uses ZX runtime interfaces. Checked packages support source imports and generics. Platform-native dependencies use native artifacts.

Prebuilt Ziran toolchains

The canonical Gitea check job packages the Ziran executables, standard library, headers, and native archive from the build it just tested. Each artifact identifies the full Ziran commit and the build host's Linux architecture and glibc version. The native job reuses its build directory.

Download toolchain-<commit> from the corresponding check run. When the workflow has a package writer configured, the same two files are available from Gitea Generic Packages under ziranlang/ziran-toolchain, using the full Git commit as the package version. The .json descriptor and .tar.gz archive share the profile name, for example linux-x64-glibc-2.39.

python3 scripts/toolchain_package.py verify "$commit" "$profile.json"

Compare commit to the toolchain commit in the consuming project's ziran.lock and use a Linux host that supports the archive's profile. The verification command checks the commit, archive length, and SHA-256. The archive contains build/bin/ziran and its companion tools. Package commands that require a source checkout still use their existing exact Git source cache.

Configure ZIRAN_TOOLCHAIN_PACKAGE_USER and ZIRAN_TOOLCHAIN_PACKAGE_TOKEN as Gitea Actions secrets for a package writer in the ziranlang organization. The workflow uploads the archive first and its descriptor second. Existing registry files are accepted on retry when their bytes match.

Checked packages for source imports

A package with manifest exports can distribute its checked Ziran modules as a .zx library. Pack it from the clean provider revision using the exact, clean toolchain and dependencies pinned in ziran.lock. Each profile names a fixed toolchain and set of feature defines at that provider revision. Supply defines with --define NAME when packing.

repo=https://git.waozi.xyz/example/counter.git
commit=$(git rev-parse HEAD)
ziran pkg zx pack-ir "$repo" "$commit" default build/counter.zx --locked
ziran pkg zx inspect-ir build/counter.zx
sha256=$(ziran pkg zx publish-ir "$repo" "$commit" default build/counter.zx --netrc "$NETRC_FILE")
ziran pkg zx fetch-ir "$repo" "$commit" default "$sha256"

publish-ir uploads <profile>.zx and then <profile>.zx.tsv to the <repository>-zx-library Generic package at the full Git revision. Either upload can be repeated with identical bytes. inspect-ir verifies local library bytes and prints the same tab-separated record with the package, toolchain, profile, and digest.

ziran add and ziran lock discover libraries on https://git.waozi.xyz and save their exact profile, digest and toolchain identity in the package entry in ziran.lock. For a different Gitea server, set ZIRAN_ZX_REGISTRY to its HTTPS origin. Discovery uses the default profile unless ZIRAN_ZX_PROFILE selects another. Set ZIRAN_PACKAGE_NETRC for authenticated reads. A missing discovery record for an unpinned package allows ordinary source resolution. Invalid metadata, an incompatible toolchain, or a missing advertised library stops resolution. A saved pin continues to identify the same exact library.

ziran add "$repo" --ref "$commit"
ziran bundle --project --entry app:main -o app.zx app.zi
ziran lock --offline
ziran bundle --project --offline --entry app:main -o app.zx app.zi

You can also supply a library pin explicitly in ziran.zx.lock, using the dependency's id from ziran.lock and the publisher's profile and digest. An explicit pin for a package with a discovered pin must agree with it.

{
  "format": 1,
  "packages": [
    {
      "package": "p0123456789abcdef",
      "profile": "default",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  ]
}

Project bundle, check, and native build and run select pinned libraries before checking out those dependencies. build --target=zx does the same. Source imports resolve through the dependency aliases and manifest exports. The compiler verifies the checked modules and uses their types, bodies and specializations when it lowers the application. This skips dependency source checking and keeps shared types and state in one program. Each transitive package whose source will be absent needs a pin. --offline requires the pinned libraries in the local cache. Local source overrides still take precedence unless --locked is set. Distribute the final .zx with the portable image commands above.

Check a library from a working tree

From the provider checkout, use its current ziran.lock and actual HEAD. pack-dev includes the working source, manifest, lock and feature defines in a source fingerprint. It allows local toolchain and source overrides.

ziran pkg zx pack-dev "$repo" "$(git rev-parse HEAD)" default build/counter-dev.zx --offline
ziran pkg zx inspect-ir build/counter-dev.zx

The inspection record starts with dev, followed by the package identity, toolchain identity, profile, provider source fingerprint, and file SHA-256. Copy the development library to a local directory as <package-id>.zx. Point ZIRAN_DEV_ZX_DIR at that directory when compiling the consumer. Keep the normal project lock and remove any source override for that provider from the consumer. Several development libraries can share a directory.

ZIRAN_DEV_ZX_DIR="$libdir" ziran bundle --project --offline --entry app:main -o app.zx app.zi

The compiler checks each development library against the locked package and toolchain. These files are for local verification. publish-ir, production pins, and --locked commands reject development libraries.

Dependency-owned native artifacts

A dependency can declare named artifacts alongside its existing project tool:

[tool]
project = "build/bin/provider"

[artifacts.native]
inputs = ["tools/provider.zi", "src/library.c", "Makefile"]
outputs = ["lib/library.a", "include/library.h", "resources/data.bin"]
requires = ["support:native"]

inputs and outputs are nonempty arrays of package-relative input files and staging-relative output files. List all recipe inputs, including ignored native source inputs, configuration, assets and tool build rules; directories and escaping paths are rejected. artifact.tsv and dependencies.tsv are reserved. requires is optional and names artifacts through the provider's own locked dependency aliases; self:NAME names another recipe in the same package. Unknown selections and recipe cycles fail before invoking the affected provider.

Recipes derive outputs only from declared inputs, dependency artifacts, the platform, resolved options and keyed toolchain/environment. Consumer identity is not an input; encode consumer-specific variation as a declared option. The current host command needs make, git, mktemp, which and sha256sum.

Consumers request the recipe without reconstructing its source or link graph:

ziran pkg artifact provider:native --platform linux-x86_64-gnu
ziran pkg artifact provider:native --platform windows-x86_64-mingw --locked

--platform is a required explicit OS-architecture-ABI identifier, independent of the compiler backend (--target=c or go). The provider must validate supported platforms and choose the correct native toolchain. The engine treats libraries, bundles and resources identically. This command does not alter project lifecycle delegation or explicit compiler target selection.

Per-invocation options override [tool.Alias] and ziran.local.toml values in memory, using the dependency's existing declared option types:

ziran pkg artifact provider:native --platform linux-x86_64-gnu \
  --option provider:mode=release \
  --option 'support:sdk.path=/opt/SDK folder/tool=chain' \
  --option provider:enabled=true

Repeat --option Alias:key=value after the platform. key is a top-level key, group.key, or group.name.key for a declared named table. Alias matching is case-insensitive and resolves to a locked package identity, so overrides also reach prerequisite recipes (including self recipes). A prerequisite uses its root consumer alias when present, otherwise its locked package name; the provider's requires edge still uses the provider's dependency alias. Strings are nonempty literal argv values, including spaces, quotes, backslashes and additional = characters. Boolean values are exactly true or false. There is no TOML parsing or shell evaluation of invocation values. Quote the whole argument as required by your shell. Control characters, unknown or ambiguous packages, undeclared keys, malformed paths and duplicate keys for the same package are rejected before compiler identification, cache lookup or any provider runs. Provider-specific value constraints remain the provider's job. New named tables are ordered deterministically, so reordering invocation arguments does not change the effective option file or cache identity. Manifests, local overrides and lock files are never edited by these options. Artifact providers receive atomic, content-addressed option snapshots so concurrent invocations cannot overwrite one another's effective values.

The ordinary project tool is built through its existing Makefile and invoked as artifact NAME --platform TARGET --output STAGE with the existing project, package, toolchain and resolved ZIRAN_TOOL_OPTIONS environment. Additional variables are ZIRAN_ARTIFACT_OUTPUT, ZIRAN_ARTIFACT_TARGET, and ZIRAN_ARTIFACT_DEPENDENCIES. The last names a TSV file with one dependency:artifact<TAB>absolute-descriptor-path line per requirement. Providers read those descriptors instead of rebuilding dependencies. They write every declared output below STAGE, send diagnostics to stderr, return nonzero on failure, and honor serial build settings (MAKEFLAGS=-j1 and CMAKE_BUILD_PARALLEL_LEVEL=1). Invocation uses argv, never shell interpolation.

On success stdout contains the absolute path of artifact.tsv in the shared Ziran artifact cache. Its TSV header records schema, package, artifact, platform, and key; remaining lines map declared relative output paths to SHA-256 digests. Resolve each output beside the descriptor. Descriptors and outputs are published together by directory rename only after all declared files exist and remain inside staging. A failed build removes staging and preserves previously published results. Cache hits verify output digests.

Python build-tool consumers

The resolved toolchain provides scripts/ziran_artifacts.py. Build scripts can load it from the directory returned by their package wrapper's pkg path ziran; they do not need a copied descriptor parser. For example, with tool naming that wrapper and project the consuming project directory:

import importlib.util
from pathlib import Path
import subprocess

toolchain = Path(subprocess.check_output(
    [tool, 'pkg', 'path', 'ziran'], cwd=project, text=True).strip())
spec = importlib.util.spec_from_file_location(
    'ziran_artifacts', toolchain / 'scripts/ziran_artifacts.py')
artifacts = importlib.util.module_from_spec(spec)
spec.loader.exec_module(artifacts)
result = artifacts.request('provider:native', 'linux-x86_64-gnu',
                           project=project, ziran=tool)
library = result.output('lib/library.a')

request forwards repeated options as literal --option arguments and uses --locked when the project has no ziran.local.toml. Its optional env is passed to the selected tool unchanged. Callers own build resource limits and display isolation. Artifact(absolute_descriptor, artifact=..., platform=...) also consumes an already requested result. Construction verifies the schema, identity, unique rows, canonical contained paths and every declared output's SHA-256 digest. output(name) requires a declared output; path(name) resolves a contained path such as a provider's include directory. Symlinks cannot escape the descriptor directory.

metadata(name) reads a declared JSON object whose integer schema is 1 and whose artifact and platform match the descriptor. Its remaining fields belong to the provider. Renderer layouts, assets, Android editions and application output names remain provider or application policy.

Providers may expose an ordered link.txt output for foreign native support. Each row is kind<TAB>value; supported kinds are:

  • archive: a declared archive output, passed as one argument.
  • library or flag: one literal linker argument.
  • pkg-config: shell-word-separated package names, queried with --libs.
  • js-library: a declared output passed after --js-library.
  • embed: a declared output and absolute virtual mount, joined with @, passed after --embed-file.

result.link_flags() expands those rows, followed by each prerequisite's metadata in the order recorded by dependencies.tsv. Each prerequisite is verified against its own output paths, artifact name and the same platform. Cycles are rejected; repeated prerequisites on separate edges retain their static link order. env also selects PKG_CONFIG and its environment. No metadata or option is evaluated by a shell.

Use link_flags(include_archives=False) when ordinary imports already compile this provider's source into the host. It omits only the current provider's archives; its flags and prerequisite foreign archives remain. For example, importing a Ziran library and linking its complete native archive again would duplicate its module globals. A foreign C host instead uses the default to link that archive once.

Identity includes the locked package graph and toolchain revisions, actual checkout HEADs, launcher/compiler bytes, native platform/ABI, recipe and input bytes, resolved options, dependency descriptors, CC executable bytes/version and relevant native build environment (PATH, CFLAGS, CPPFLAGS, CXX, CXXFLAGS, LDFLAGS, LDLIBS, AR, LD, RANLIB, PKG_CONFIG, PKG_CONFIG_PATH, PKG_CONFIG_LIBDIR, SYSROOT, SDKROOT, MACOSX_DEPLOYMENT_TARGET). CC must name one executable. Any dirty tracked or untracked checkout in the resolved graph disables reuse; declared ignored inputs are hashed regardless. Dirty builds receive unique publication directories, so local edits cannot hit or overwrite clean results. Two independent consumers with the same graph, options and environment share a clean artifact.

The package-driver entry point is PkgBuildArtifact(project: string, package: string, artifact: string, target: string) -> s32. For invocation overrides use PkgBuildArtifactWithOptions(project: string, package: string, artifact: string, target: string, overrides: []string) -> s32. Each slice element is the same Alias:key=value string as the CLI; an empty slice has the original entry point's behavior. CLI dispatch passes its already resolved graph to the same implementation. Downstream adoption consists of adding provider-owned recipes and an artifact command to the existing Ziran project tool, then replacing consumer source/link reconstruction with this request and descriptor consumption. Platform-specific sources, link decisions and assets stay in those providers.

Run the focused native fixture independently before adopting provider recipes:

env -u DISPLAY -u WAYLAND_DISPLAY build/bin/ziran run --target=c --root tests tests/package_artifacts_cases.zi -- build/bin/ziran

The regular sh tests/packages.sh build/bin/ziran runner includes this fixture. It creates only disposable miniature input repositories under build/tests/.