Reference

Manifest Format

The Netsukefile is the heart of your build configuration. It is a YAML document with explicit top-level keys and controlled Jinja expansion inside values.

Anatomy of a Manifest

Every Netsukefile is a YAML mapping. Unknown fields and duplicate mapping keys are errors. netsuke_version and targets are required (an empty targets list is valid for an action-only manifest); vars, macros, rules, actions, and defaults are optional.

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.
vars	Mapping	Global strings, numbers, booleans, or lists available to Jinja. Keys named `env` or `glob` are rejected at parse time because they would shadow the built-in helpers.
macros[]	List of Mapping	Named Jinja macros, each with a `signature` and a `body`, registered before other fields render.
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.
description	String	On a rule, the text Ninja shows in its progress display. On a target or action, discovery metadata surfaced by `netsuke help targets`.
defaults	List of String	Lists the target or action names built when `netsuke` runs without explicit targets. Entries are literal names; Jinja expressions are not rendered in this field.

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. A target or action that performs work carries exactly one of rule, command, or script; one whose entire job is its non-empty deps list may omit the recipe altogether and becomes a native Ninja phony node. Since v0.1.0-beta3 that dependency-only form is preferred over a no-op such as command: ":".

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
$PATH Shell dollars are written normally; Netsuke escapes them for Ninja. $in/$out are not Netsuke placeholders — use the markers above.

On POSIX and Bash routes a marker may sit unquoted, single-quoted, or double-quoted, but not inside a command substitution or backticks. In PowerShell, use markers unquoted; quoted and command-substitution marker sites are rejected rather than risking a context escape.

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 or List of String

One shell command string, or an ordered list of commands run in declaration order and stopped at the first non-zero exit — the fail-fast behaviour of a handwritten && chain. Each entry sees the same Jinja context; use {{ ins }} for quoted inputs and {{ outs }} for quoted outputs. An empty command list is rejected at parse time.

script String (multiline)

A multi-line script interpreted by the selected recipe shell: /bin/sh -e on Unix, so any line failing aborts the step, and Windows PowerShell on Windows unless NETSUKE_WINDOWS_SHELL=bash selects the Bash compatibility route. Mutually exclusive with command and rule.

deps String or List

Implicit dependencies: they affect freshness and ordering but are not appended to the recipe. Declared per target or action; reusable rules reject deps. Pair with dependency_order: serial to run the list in declaration order.

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.

Getting Started

Rules & Targets