Skip to content
The Cook Standard

§ 0 — Introduction

0. Introduction

Normative. This chapter defines the scope of the Cook Standard and the conventions the Standard uses.

0.1. Purpose

The Cook Standard is the authoritative specification of the Cookfile language. It defines the lexical structure, syntactic grammar, execution semantics, Cook Lua API, and module system. A Cookfile that conforms to the Standard is a conforming Cookfile; a tool that parses and executes Cookfiles in accordance with the Standard is a conforming implementation.

0.2. Scope

The Standard covers the full language surface a Cookfile author can use:

  • Lexical structure (tokens, lines, prefixes). See § 3.
  • Top-level structure, declarations, and the syntactic grammar (productions, ordering). See § 4, § 5, and App. A.
  • Recipe structure and step kinds. See § 6 and § 8.
  • Cross-recipe references (name references, path accessors, dep-driven iteration, string substitution). See § 10.
  • The Cook Lua API exposed in > / >{ ... } / >{ ... } contexts, including the use declaration. See § 21.
  • Cross-Cookfile composition (import, qualified references, module resolution). See § 11 and § 12.
  • Execution semantics (register phase, execute phase, step groups, cross-recipe ordering, cache semantics). See § 13.

0.3. Non-scope

The Standard does NOT cover:

  • The cook CLI surface (subcommands, flags).
  • Exit codes, error message wording, or diagnostic formatting.
  • Performance characteristics, including scheduler thread counts.
  • The on-disk cache layout or the hash function used.
  • Terminal output formatting.

These are implementation concerns and are documented in docs/architecture/.

0.4. Normative and informative material

Chapters 00 through 08 and Appendix A are normative. Appendices B, C, and D are informative. Within a normative chapter, Example and Note blocks are informative unless explicitly marked otherwise; the surrounding paragraphs are normative when they contain RFC 2119 keywords. See § 2.3 for the full convention.

0.5. Versioning

Cook Standard versions are of the form MAJOR.MINOR. The current version is recorded in standard/VERSION and rendered in the site header. Pre-1.0, MINOR increments on each version cut. A cut MAY contain one or more CS entries (App. D); authoring granularity (one CS per merge) and publication granularity (one cut per N CSes) are decoupled. There is no PATCH track pre-1.0; clarifications and typo fixes that ship without a CS land on head-of-main and are absorbed into the next cut.

A cut consists of three actions performed in a single commit on main: bumping standard/VERSION, adding the new version to the top of the App. D Versions index, and tagging the commit cs-standard/vX.Y. The tag and index entry together constitute the published cut.

CS-0001 through CS-0010 are grouped retroactively under v0.1; CS-0011 (top-level variable_declaration removal) and CS-0012 (this versioning machinery) ship in v0.2.

There is no version pragma in the Cookfile header at this time. At 1.0, the Standard will transition to strict SemVer (MAJOR.MINOR.PATCH); the rules for that transition are out of scope for the present draft.

0.6. Relationship to docs/architecture/

docs/standard/ defines what Cookfiles mean. docs/architecture/ documents how the current reference implementation works (parser module layout, runtime internals, scheduler thread-pool design, cache layout). Implementation documents can evolve freely without touching the Standard, provided they do not make normative claims about language behavior.