nanvix-zutil

Build orchestration utilities for the Nanvix ecosystem.

nanvix_zutil is a Python 3.12+ library that provides a unified ZScript base class with lifecycle hooks, structured logging, config persistence, GitHub release artifact downloading, lockfile-based dependency resolution, and deterministic exit codes.

Quick Start

Consumer repositories subclass ZScript in .nanvix/z.py:

from nanvix_zutil import ZScript

class MyBuild(ZScript):
    def build(self) -> None:
        self.run("make", "-f", "Makefile.nanvix", "all")

    def test(self) -> None:
        self.run("make", "-f", "Makefile.nanvix", "test")

if __name__ == "__main__":
    MyBuild.main()

Then invoke via the bootstrap wrapper or the nanvix-zutil CLI:

./z setup            # download sysroot + install dependencies
./z build            # cross-compile (Docker auto-enabled)
./z test             # run tests
./z lint             # black --check + pyright on .nanvix/*.py
./z format           # auto-format .nanvix/*.py with black
./z format --check   # verify formatting without writing (non-zero on diff)
./z distclean        # remove all generated artifacts

Or directly with nanvix-zutil:

nanvix-zutil lock    # resolve dependency graph → nanvix.lock
nanvix-zutil setup   # download sysroot + install deps
nanvix-zutil build   # cross-compile
nanvix-zutil test    # run tests
nanvix-zutil lint            # lint .nanvix/*.py
nanvix-zutil format          # format .nanvix/*.py
nanvix-zutil format --check  # verify formatting (non-zero on diff)

Installation

Install from the GitHub Releases page — pick the .whl URL for the version you need:

pip install "https://github.com/nanvix/zutils/releases/download/v<VERSION>/nanvix_zutil-<VERSION>-py3-none-any.whl"

Or with uvx for zero-install usage:

uvx nanvix-zutil build

Consumer repos typically don't install manually — the bootstrap wrappers (z, z.sh, z.ps1) auto-create a virtualenv and install the pinned version into .nanvix/venv/.

To iterate on nanvix-zutil itself against a downstream consumer, point the bootstrapper at a local source checkout (a directory containing pyproject.toml) via the --with-zutils flag. An editable install is materialised in .nanvix/venv/ and the pinned-version check is bypassed:

Linux/macOS:

./z.sh --with-zutils ~/src/zutils build

Windows:

.\z.ps1 --with-zutils C:\src\zutils build

The override is re-applied when the recorded source path changes or when the venv is missing, so repeated invocations stay fast. ./z distclean removes the venv, so the flag must be passed again on the next bootstrap.

Documentation

Document	Description
Design Overview	Architecture, module graph, data flow
Setup	Developer environment setup
Build	How to build the project
Test	How to run tests
Troubleshooting	Solutions to common problems

Additional references:

Document	Description
Manifest Reference	nanvix.toml format and options
Local Development (--with-nanvix)	Using local Nanvix builds
Contributing	Contribution guidelines and release process

Examples

• examples/lib-hello/ — cross-compiles a static library (libhello.a).
• examples/bin-hello/ — depends on lib-hello and cross-compiles a binary.

License

MIT — see LICENSE.