Defining Rules

Updated Nov 24, 2025

Rules encapsulate reusable build commands or scripts.

  • name: Unique string identifier.

  • recipe: The action to perform. Defined by one of:

  • command: A single shell command string. May contain {{ ins }} (space-separated inputs) and {{ outs }} (space-separated outputs). These specific placeholders are substituted after Jinja rendering but before hashing the action. All other Jinja interpolations happen first. The final command must be parseable by shlex (POSIX mode).

  • script: A multi-line script (using YAML |). If it starts with #!, it's executed directly. Otherwise, it's run via /bin/sh -e (or PowerShell on Windows) by default. Interpolated variables are automatically shell-escaped unless | raw is used.

  • rule: References another rule by name (less common within a rule definition).

  • description (Optional): A user-friendly message printed by Ninja when this rule runs. Can contain {{ ins }} / {{ outs }}.

  • deps (Optional): Specifies dependency file format (gcc or msvc) for C/C++ header dependencies, generating Ninja's depfile and deps attributes.

rules:
  - name: compile # Unique identifier for the rule
    # Recipe: Exactly one of 'command', 'script', or 'rule'
    command: "{{ cc }} {{ cflags }} -c {{ ins }} -o {{ outs }}"
    # Optional: Displayed during the build
    description: "Compiling {{ outs }}"
    # Optional: Ninja dependency file info (gcc or msvc format)
    deps: gcc