Author a manifest

Netsukefile is a YAML mapping. Unknown fields and duplicate mapping keys are errors. netsuke_version and targets are required; all other top-level collections are optional.

The following complete example shows every top-level section:

netsuke_version: "1.0.0"

vars:
  greeting: Hello

macros:
  - signature: "message(name)"
    body: |
      {{ greeting }}, {{ name }}!

rules:
  - name: write_message
    command: "echo '{{ message('Netsuke') }}' > {{ outs }}"
    description: "Writing greeting"

actions:
  - name: greet
    command: "echo '{{ message('builder') }}'"

targets:
  - name: greeting.txt
    rule: write_message

defaults:
  - greeting.txt

The top-level fields are:

• netsuke_version: required semantic version for the manifest schema.
• vars: global strings, numbers, booleans, or lists available to Jinja.
• macros: named Jinja macro definitions registered before other fields render.
• rules: reusable recipes referenced by targets or actions.
• actions: implicitly phony operations, such as test or lint.
• targets: required list of file-producing or logical build nodes. An empty list is valid for an action-only manifest.
• defaults: target or action names used when build receives no explicit targets.

defaults entries are literal names in v0.1.0-beta1; Jinja expressions are not rendered in this field.

A rule or target must provide exactly one recipe:

• command: one shell command.
• script: a multi-line POSIX shell script.
• rule: the name of another rule to use.

Rules may also provide description, text used for Ninja's progress display.

The v0.1.0-beta1 script implementation invokes /bin/sh -e; it is not currently a portable PowerShell abstraction. Prefer command or platform-selected actions when a manifest must work on Windows.

A target supports these fields:

• name: one output path or a list of output paths.
• rule, command, or script: exactly one recipe.
• sources: explicit inputs. They affect freshness and become {{ ins }}.
• deps: implicit dependencies. They affect freshness but do not become recipe arguments. Declare them on each target; reusable rules reject deps. The planned rule-level deps_from contract is not implemented in v0.1.0-beta1.
• order_only_deps: ordering dependencies. Their changes do not rebuild the dependent target.
• vars: values that override global variables for this target.
• phony: marks a logical target that does not represent a file.
• always: forces the recipe to run whenever the target is requested.

name, sources, deps, and order_only_deps accept either one string or a list of strings.

Netsuke quotes paths inserted through {{ ins }} and {{ outs }}. Other Jinja values render as ordinary command text and are not automatically shell-quoted. The shell_escape filter described in older drafts is not implemented in v0.1.0-beta1.

Cycle detection follows sources and deps. Order-only dependencies enforce ordering but do not participate in cycle detection.