Development¶

lib contains the library; examples contains complete original programs; tests contains fixtures and host assertions. The compiler is an external dependency. Do not add compiler crates, copied runtime code, private headers or sibling-checkout assumptions.

compiler.json records the tested compiler repository and immutable revision. CI checks out that revision into ignored .tools, builds zebc, and uses it through its CLI. To update compatibility, change the pin and rerun source and native checks together. Library and compiler versions need not advance together.

Run the README commands. The test runner selects --zebc, then ZEBC, then PATH, without fallback after an invalid explicit selection. Native prerequisites follow the compiler's discovery settings. Tests share one temporary output/cache directory per run; no cache entry is committed. Existing output directories are refused.

Source checks cover every complete example and fixture, host protocol validation and generated catalogue consistency. Native checks use independent expected outcomes for actions, scope, travel, scheduling, actor following, dialogue and persistence. The same suite runs on macOS Intel/Apple Silicon, Linux x86-64 and Windows x86-64. The independent inspection host uses the generated header and manifest, POSIX threads on Unix and a C runtime worker thread on Windows. Windows links the manifest-selected import libraries; Unix uses relative library-loading paths. Missing prerequisites fail the requested native run.

Native builds currently require Rust 1.98.1 and LLVM 22.1.8, as specified by the compiler pin. Linux needs host C/C++ development tools, including libc headers and startup libraries. Windows needs Visual Studio C++ Build Tools and a Windows SDK, with INCLUDE and LIB configured by an x64 developer environment. macOS needs its SDK and both x86_64-apple-darwin and aarch64-apple-darwin Rust target libraries. The workflow initializes MSVC on Windows and uses the pinned compiler's checksum-verified LLVM bootstrap on all three runners. The bootstrap has no Intel macOS archive; local Intel runs need an existing LLVM 22.1.8 installation selected with ZEB_LLVM_CONFIG. Use ZEB_RUSTC to select the pinned Rust compiler explicitly when necessary.

Keep documentation with its API changes, and make examples executable in tests. Preserve code/message identity unless an intentional compatibility change is documented. Do not replace independent assertions with output snapshots generated by the same implementation.

To build the programmer reference locally, install the pinned documentation dependency with python3 -m pip install -r requirements-docs.txt, then run python3 tools/build_docs.py. Open build/site/index.html. Run python3 tools/build_docs.py --check to validate the complete reference and links without updating tracked files. The builder reads vhyl declarations and adjacent comments; /** @api author */ and /** @api host */ comments identify supported interfaces, while other declarations remain browsable as internal entries. Built site files remain under ignored build/.

The Library reference Pages workflow is separate from compiler checks. It can be started manually on main after the repository's Pages source is set to GitHub Actions; it builds and uploads the site without committing generated pages.

Before a release, test a fresh source export with an empty output/cache directory, review links and the file inventory, and run a local secret scanner. Do not commit build logs, evidence, local tool fingerprints, private story data or historical planning material.

CI is manual-only (workflow_dispatch). In GitHub Actions, select Library checks, choose Run workflow and select the relevant branch or tag. Run it for changes requiring validation, compiler-pin updates and before releases. Pushes, pull requests and published releases do not trigger it. Each run executes source and native checks on Ubuntu 24.04 x86-64, Windows Server 2025 x86-64 and macOS 15. macOS builds universal output, then executes its Apple Silicon slice; CI does not execute the Intel slice. Local Intel execution does not validate Apple Silicon, other operating systems or a minimum OS version. No CI execution is claimed solely because the workflow exists.