Manifest Reference - Netsuke Build System

Anatomy of a Manifest

Every Netsukefile is a YAML mapping. The common top-level sections are netsuke_version, vars, macros, rules, targets, actions, and defaults.

Manifest metadata

Reusable rules

Targets and defaults

Netsukefile

# 1. Schema version
netsuke_version: "1.0.0"

# 2. Variables and reusable rules
vars:
  cc: "gcc"

rules:
  - name: "compile"
    command: "{{ cc }} -c {{ ins }} -o {{ outs }}"

# 3. Build targets and defaults
targets:
  - name: "main.o"
    rule: "compile"
    sources: "src/main.c"

defaults:
  - "main.o"

Common Attributes

These fields show up frequently across rules, targets, and actions. They define identity, reuse, and execution behaviour.

Attribute	Type	Description
netsuke_version	String	Required Declares which manifest schema version the file follows.
rules[].name	String	Names a reusable command or script template that targets can reference.
targets[].sources	String or List	Lists the input files or previously generated outputs required by a target.
defaults	List of String	Lists the target names built when `netsuke` runs without explicit targets.

Inline commands and scripts

Targets may define command or script inline instead of referencing a named rule. This is useful for one-off steps that are too small to deserve a shared rule.

Basic Usage

targets:
  - name: "page.html"
    sources:
      - "header.txt"
      - "body.txt"
      - "footer.txt"
    command: "cat {{ ins }} > {{ outs }}"

Common placeholders

{{ ins }} Space-separated list of quoted input paths
{{ outs }} Space-separated list of quoted output paths
vars Global and target-local values exposed to Jinja rendering

Specific Attributes

name String (single-output) or
List of String (multi-output)

Primary output path for this target. For single-output targets, use a String. For multi-output targets, use a List of Strings; all listed paths are produced by the same target and share a single identity in the build graph. Dependencies and sources entries refer to the target as a whole, not to individual output paths.

sources String or List

Input file path(s) required to build this target. If a sources entry matches another target's name, an implicit dependency on that target is created. For multi-output targets (where name is a List of Strings), the lookup checks each string in the list; a match on any of them creates a dependency on the target as a whole. To depend on a specific output of a multi-output target, reference the exact output path as it appears in the target's name list.

command String

A single shell command string. Use {{ ins }} for quoted inputs and {{ outs }} for quoted outputs. Interpolated values are shell-escaped by default.

script String (multiline)

A multi-line script executed via /bin/sh -e, so any line failing aborts the step. Mutually exclusive with command and rule.

Best Practices

Granularity is Key

Keep targets small. Instead of one huge compile_all rule, break your project into smaller libraries. This maximizes parallelism and cache hits.

Use Globs Wisely

glob() is convenient but can be brittle. Explicitly listing sources is often safer for critical libraries, as it prevents accidental inclusion of unwanted files.

Avoid Non-Determinism

Don't use timestamps, random numbers, or absolute paths in your build commands. These break caching and make builds unreproducible.

No Circular Dependencies

Netsuke enforces a Directed Acyclic Graph (DAG). If package A depends on B, B cannot depend on A. Refactor common code into a third package C.

Manifest Format