The Nox Build & Automation System

Nox is a cross-platform build system, task runner, and project runtime written in Rust. Its core models projects, targets, dependencies, toolchains, Riders, and structured build actions independently of any one language.

See the complete documentation for project integration, command behavior, the nox.build language, architecture, and troubleshooting.

Build Nox

Build Nox. It is a build system. The name does most of the work here.

cargo build --release

Building with Nix

Enter the nix dev shell by running nix develop then run

nox setup builddir
nox compile -C builddir

The Nix flake packages the working tree, allowing Nox to install itself directly into the development shell.

Use Nox

A project declares its build graph in nox.build:

project "example" {
    version = "1.0.0"

    executable "example" {
        sources = glob("src/*.c")
        include_dirs = ["include"]
        defines = ["FEATURE=1"]
        flags = ["-Wall", "-Wextra"]
    }
}

Configure once, then build incrementally:

nox setup build
nox build build -j8

Install the configured project into /usr/local, placing executables in /usr/local/bin:

nox install

Use --prefix for a different installation root. nox install configures and builds automatically when the build directory does not exist:

nox install --prefix "$HOME/.local"

Successful local and remote installs are recorded in Nox's installed-package database. List installed packages, inspect one, search the public registry, or remove an installed package by name:

nox install .
nox packages list
nox packages <package>
nox packages search <package>
nox uninstall <package>

Nox can also install a valid remote Nox project from GitHub or from the public package registry:

nox install github:playfairs/ripnet
nox install pkgs:ripnet

Both forms require the fetched repository to contain a valid nox.build and pass the same project-validation and toolchain checks as a local project. The package registry only resolves a package name to a GitHub source; it does not bypass Nox's own build and Rider validation.

To install Nox itself from a source checkout, bootstrap the executable once with Cargo, then let Nox handle the rest:

cargo run -- install
/usr/local/bin/nox

The default configuration is debug; pass --release during setup for release artifacts. Commands include setup, configure, build, clean, rebuild, install, uninstall, validate, status/stat, test, run, graph, targets, list, version, and task NAME. Every command supports --help.

noxfile is optional and contains task automation. It is separate from nox.build, which describes the actual compilation graph.

Supported Backends

C and C++ sources use the detected GCC or Clang-compatible compiler with compiler-generated dependency files. Static libraries, shared libraries, executables, includes, definitions, compiler flags, linker flags, debug/release settings, and parallel compilation are supported. Basic Rust executables and libraries use rustc directly. Q# sources use the .NET SDK via Microsoft.Quantum.Sdk and are recognized through the .qs extension.

Nix

The flake provides the package, development shell, formatter, and flake checks:

nix develop
nix fmt
nix flake check

Other flakes can consume the repository package:

inputs.nox.url = "github:playfairs/nox";

packages = [ inputs.nox.packages.${system}.default ];

The same package is available as inputs.nox.packages.${system}.nox, and the executable can be run with:

nix run github:playfairs/nox

See nox-vscode for LSP support for Visual Studio Code.