Project file

Declare the
build graph.

nox.build is a small declarative language. It is not TOML, JSON, YAML, or shell. For comparison the syntax is most similar to HCL (HashiCorp Configuration Language), but not based on it.

A complete file

The Nox project file.

project "nox" {
    description = "The Nox Build & Automation System."
    repository = "https://github.com/playfairs/nox"
    website = "https://noxbuild.cc"
    authors = ["playfairs", "invra"]
    maintainers = ["playfairs <root@playfairs.cc>"]

    version = file("./VERSION")
    license = file("./UNLICENSE")
    version_files = ["Cargo.toml", "VERSION"]
    edition = "1"
    dependencies = []

    extra.env {
        RUST_BACKTRACE = "full"
    }

    executable.rust "nox" {
        sources = ["src/main.rs"]
        flags = []
        install = true
    }
}

A small C project

Targets are explicit.

project "hello" {
    version = "1.0.0"
    description = "A small command-line application."

    executable "hello" {
        sources = ["src/main.c"]
        flags = ["-Wall", "-Wextra"]
        install = true
    }
}

Source paths are relative to the directory containing nox.build.

Target properties

Sources, dependencies, flags.

sourcesList of paths or a simple glob("src/*.c").

dependenciesTarget names resolved in the same project.

include_dirsDirectories passed as compiler -I arguments.

definesPreprocessor definitions passed as -D.

flagsAdditional compiler flags for the target.

Project settings

Keep values reusable.

set windows-shell := ["powershell.exe", "-NoProfile", "-Command"]
version := `cargo xtask`

project "example" {
    let sources = ["src/main.c"]
    let warnings = ["-Wall", "-Wextra"]

    executable "app" {
        sources = sources
        flags = warnings
    }
}

Top-level settings support set NAME := VALUE andNAME := VALUE. Backtick values run through the platform shell while parsing. Project-level letbindings are immutable and can be reused by target properties.

Target kinds

Choose the shape of the artifact.

executableGeneric executable whose Rider is selected from its source.

executable.<language>Explicit language-qualified executable, such as executable.rust or executable.cpp.

static_library / shared_libraryArchives objects or links a shared library. static and shared are accepted aliases.

rust_libraryBuilds a Rust library target.

Generic Rider targets use the first source file to select the language backend. Every target needs at least one source. The supported explicit qualifiers include rust, cpp, c, d, haskell, swift, fsharp, javascript, typescript, and python.

Configure and build

Let Nox order the work.

nox validate
nox setup build
nox compile -C build -j8
nox targets
nox graph
nox install --prefix "$HOME/.local"

Nox validates missing targets and dependency cycles before building. Libraries are passed to executable link commands in dependency order.

Project metadata

Describe the project once.

repositorySource repository URL.

websiteProject website URL.

authorsList of project authors.

maintainersList of current maintainers and contact details.

Multiple projects

One file can name several projects.

project "nox" {
    executable.rust "nox" {
        sources = ["src/main.rs"]
    }
}

project "noml" {
    executable.rust "noml" {
        sources = ["noml/src/main.rs"]
    }
}

When more than one project is declared, specify the project for commands that operate on one project: nox stat nox,nox run noml, or nox install nox. Without a project name, Nox prints the available executable choices and exits without guessing.

Declare thebuild graph.