Nitpick Build System (npkbld) Specification

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

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.abc)

By default, npkbld looks for a build.abc configuration file in the project root. The syntax is TOML-based and defines project metadata and individual target parameters.

Example 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

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.