# Makefile Contract

`flow/Makefile` is written in make, a rich programming language behind a
terse syntax: recursive and simple expansion, `=` against `:=` against `?=`,
the origin of a variable, exports to sub-makes, a graph built in one pass and
run in another. ORFS keeps the Makefile as simple as it can, and over time a
handful of conventions have grown up that keep it that way. Most of them were
never written down.

This page writes them down as rules a review can check a change against: a
change to `flow/Makefile`, `flow/scripts/*.mk`, the stage scripts in
`flow/scripts/*.tcl`, `flow/scripts/variables.yaml`, or the `config.mk` of a
platform (`flow/platforms/*/config.mk`) or a design
(`flow/designs/**/config.mk`). It is written for
automated review of AI maintenance of these files: an agent that changes one
of them, or reviews such a change, checks it against every rule here.

The rules are hard stops: a change that breaks one is wrong, whatever else it
fixes. Each rule says what breaks when it is broken. Any place where the
existing code disagrees with a rule is technical debt, whether an expedient
solution or older code written before the rule: debt to fix, not a precedent
to follow.

Some flows run the Makefile one step at a time, each step in a fresh tree that
holds only that step's inputs, and track the dependencies themselves;
[bazel-orfs](https://github.com/The-OpenROAD-Project/bazel-orfs) is one.
Several of the rules exist for them.

## Targets

- **A `do-` target never builds anything.** It runs its one step on the files
  already in the tree. Its prerequisites are checks (`check-kepler-formal`),
  the step's source files and one-time markers (`$(OBJECTS_DIR)/copyright.txt`):
  never an order-only prerequisite, never a file another target writes.
  *Breaks:* a flow that runs each `do-` target alone in a fresh tree rebuilds
  the prerequisite every time.
- **Dependencies live only on the file targets and stage aliases**
  (`$(RESULTS_DIR)/2_1_floorplan.odb`, `synth`, `floorplan`, ...), never on a
  `do-` target. The file target checks the dependencies and calls the `do-`
  target to run the step.
  *Breaks:* a flow that tracks dependencies itself cannot run one step on
  existing results.
- **`open_*`, `gui_*`, `web_*` and `run` never build anything.** `run` writes
  `$(LOG_DIR)/$(RUN_LOG_NAME_STEM).log` and nothing under `RESULTS_DIR`,
  `REPORTS_DIR` or `OBJECTS_DIR`.
  *Breaks:* opening or scripting a stage changes the tree it looks at, and a
  caller that runs several `make run` at once on one tree gets them writing
  the same files.
- **The graph never depends on a variable.** No `ifeq` chooses which steps run
  or which files they write. A step with nothing to do for a design runs
  anyway and copies its `.odb` and `.sdc` through; the choice is made in its
  `.tcl`.
  *Breaks:* a flow that names a step's outputs before running it gets a
  different set for each design.

## Steps

- **A step never writes next to its inputs or into one.** It writes new files
  under names of its own, as `2_floorplan.odb` → `3_place.odb`.
  *Breaks:* a rerun reads what the last run wrote, and a flow that keeps
  inputs read-only cannot run the step.
- **A step never skips an output because the file exists.** "Up to date" is
  the file target's decision.
  *Breaks:* a tree that kept a file from an earlier run and a fresh tree give
  different results.
- **A step never reads a file it does not declare.**
  *Breaks:* it works under `make synth`, where an earlier target happened to
  build the file, and fails when the step runs alone.
- **A step never reads an input it does not use.**
  *Breaks:* every change to that input reruns the step and every step after
  it.
- **A step never leaves configuration for a later step.** A command gets its
  options in its own `log_cmd` line; a setting it needs is set right before
  the call and reset right after. State that crosses steps is in the `.odb` or
  another result file.
  *Breaks:* the later step's log does not show what it ran with, and a
  checkpoint changes when the design did not.
- **A step never draws an unseeded random number.** The seed comes from a
  variable and is recorded.
  *Breaks:* caching a step's result, the QoR check against a baseline, and
  bisecting a regression.
- **A failing step never calls `exit`.** It writes `<step>-failed.odb` and
  calls `error`, as `flow/scripts/global_place.tcl` does.
  *Breaks:* the log and the exit status stop saying where the step failed,
  and there is no checkpoint to inspect.
- **A `PRE_<STEP>_TCL` hook never runs before the design is loaded.** Hooks
  run through `source_step_tcl` in `flow/scripts/util.tcl`, after
  `load_design`.
  *Breaks:* the hook has no design to act on.

## Variables

- **A variable a design sets is never assigned with `=` in the Makefile.** It
  is assigned with `?=`. `RUN_CMD` in `flow/scripts/variables.mk` is the
  exception; it can be set only on the make command line.
  *Breaks:* a flow that passes a design's variables in `DESIGN_CONFIG` as
  `export VAR?=value` lines is overridden.
- **A variable the environment supplies is never exported with
  `export VAR := $(VAR)`.** It is exported bare, `export VAR`, and its default
  is a `?=` fallback to the in-tree install.
  *Breaks:* `:=` rebinds the variable to origin "file", `UNSET_AND_MAKE`
  unsets it before the sub-make, and the fallback fires there with an in-tree
  path that a flow supplying its own tools does not have (the "HERE BE
  DRAGONS" comment in `flow/scripts/variables.mk`).
- **Only the Makefile sets `RESULTS_DIR`, `LOG_DIR`, `REPORTS_DIR` and
  `OBJECTS_DIR`.** It derives them from `WORK_HOME`, which a flow sets. A
  variable a flow adds never reuses one of these names.
  *Breaks:* a flow that relocates the tree through `WORK_HOME` finds results
  where the Makefile did not put them.
- **A variable a design or platform sets, or a stage script reads, is never
  missing from `flow/scripts/variables.yaml`.** Its entry has its default,
  when it has one, and `stages:` when not every stage reads it. A variable
  only the Makefile reads, such as `WORK_HOME`, or that is internal to it,
  such as `DO_STEP_DEPS_*` and `UNSET_AND_MAKE`, may be documented elsewhere
  and need not be listed.
  *Breaks:* a flow that checks variable names against `variables.yaml`
  refuses it, and a flow that passes each stage only its own variables
  passes it nowhere, or everywhere.
- **A variable that has a default is never read through an existence check.**
  It is read as `$::env(VAR)`, never through `env_var_exists_and_non_empty`
  with a fallback. A boolean is `0`/`1` and has a default.
  *Breaks:* a misspelled or unpropagated variable takes the other branch
  quietly, instead of stopping at the line that reads it.
- **A script never overwrites a variable that is set.** It sets one only when
  it is unset.
  *Breaks:* the design's or the user's value is ignored.
- **A platform default is never repeated in a design's `config.mk`.** It is in
  the platform's `config.mk`, assigned with `?=`.
  *Breaks:* a change to the platform default misses the designs that copied
  it, and a design can no longer override it.
- **A variable never has a negative name** (`LEC_CHECK=1`, never
  `DISABLE_LEC_CHECK`), **never duplicates an existing one** (`ADDITIONAL_LIBS`
  for an extra library), **and is never a default-off feature toggle** that no
  CI design sets. A variable with no effect is deleted, not deprecated.
  *Breaks:* double negatives in settings, two variables for one choice, and
  code no CI run exercises.
- **A variable's value is never computed with `$(shell awk ...)` or
  `$(shell sed ...)`.** That logic is in Python with unit tests.
  *Breaks:* a heuristic nobody can test, read, or run on a machine without
  that tool.

## Directories

A design's files are split over four directories so that where a file lands
says what it is: the design, a measurement of it, a log, or scaffolding. One
directory would work for the flow; four make the tree legible. What a file
is decides its directory, not who reads it.

- **`RESULTS_DIR` holds the design, in any format:** netlists, `.odb`,
  `.def`, `.gds`, `.sdc`, routing guides, placement scripts, the checkpoint a
  failed step leaves, and memory inventories.
  *Breaks:* a flow or a user looking for the design finds part of it
  elsewhere.
- **`REPORTS_DIR` holds measurements of the design,** for tools or people to
  read. No step's result depends on it.
  *Breaks:* a flow that hands a step only the results has to carry reports
  along.
- **`LOG_DIR` holds logs,** and each step's metrics `.json` next to its log.
  *Breaks:* `genReport.py` and the metrics tools miss a run's record.
- **`OBJECTS_DIR` holds what is not the design:** files a step derives from
  the platform (`klayout.lyt`), a step's own intermediate files
  (`abc.constr`, `rtlmp/`, `surgery/`), caches, and stopgaps that wait for a
  cleaner implementation.
  *Breaks:* the design is mixed with scaffolding.