Nitpick Build System (npkbld) Specification

The official build system for Nitpick is npkbld. It manages compilation orchestration and parallel building, integrating seamlessly with the npkc compiler. For dependency resolution and package management, use the standalone npkpkg package manager tool.

1. Core Commands

npkbld offers a standard suite of build commands similar to Cargo or Make.

• build : Build the project. (This is the default command if no command is specified).
• clean : Remove build artifacts and state.
• rebuild : Run a clean followed by a complete build from scratch.
• check : Show what would be built without actually compiling anything (a dry run).
• targets : List all available build targets configured for the current project.
• deps : Show the project’s dependency graph exported in DOT format.
• test : Build and execute all test files (test_*.npk, *_test.npk).

2. Global Options and Flags

You can customize the build execution environment with several global flags:

• -C <dir> : Change to the specified directory before initiating the build.
• -f <file> : Specify a custom build file instead of the default.
• -j, --jobs <N> : Specify the number of parallel build jobs. Defaults to the total number of CPU cores.
• -v, --verbose : Verbose mode; displays all underlying npkc shell commands being executed.
• -q, --quiet : Quiet mode; minimal standard output.
• --force : Force a rebuild of all targets, deliberately ignoring the current build state and cache.
• --dry-run : Print the commands that would be executed without running them.
• --fail-fast : Immediately halt the build process on the very first compilation error (This is the default behavior).
• --keep-going : Ignore errors on independent targets and continue building as much of the dependency tree as possible.

3. Configuration Format (build.npk and build.abc)

npkbld natively supports execution-based build manifests using the Nitpick language itself (build.npk), providing programmatic control over build targets. It also supports static TOML-based configurations (build.abc) for legacy compatibility.

Programmatic build.npk Structure

When build.npk is present, npkbld compiles and executes it to emit the final build manifest. This utilizes the standard bld.npk API:

use "bld.npk".*;

pub func:main = int32() {
    Project:p;
    p.name = "my_project";
    p.version = "0.1.0";
    drop(emit_project(p));

    Target:main_tgt;
    main_tgt.name = "main";
    main_tgt.target_type = "binary";
    main_tgt.sources = raw str_array1("src/*.npk");
    main_tgt.flags = raw str_array2("-O2", "--verify");
    drop(emit_target(main_tgt));

    exit 0i32;
};

Static build.abc Structure

[project]
name = "my_project"
version = "0.1.0"

[target.main]
type = "binary"              # Can be "binary" or "library"
sources = ["src/*.npk"]      # Glob patterns supported
deps = []                    # Internal target dependencies
flags = ["-O2", "--verify"]  # Custom npkc flags

4. CMake Integration

For integration into larger C/C++ projects, Nitpick ships with FindNitpick.cmake. Downstream projects can easily import and build Nitpick sources natively within CMake:

find_package(Nitpick REQUIRED)

# Compiles Nitpick sources to objects and links with libnitpick_runtime.a
add_nitpick_executable(my_app src/main.npk)
add_nitpick_library(my_lib STATIC src/utils.npk)

Dependency Emission

npkbld deeply integrates with npkc’s --emit-deps flag. During a build, it triggers the compiler to emit JSON dependency manifests, which npkbld then consumes to build the parallelized internal build graph. You can visualize this graph using the npkbld deps > graph.dot command.