Skip to content

Commit a2acaac

Browse files
oharboeclaude
andcommitted
docs: MakefileContract: what goes in RESULTS_DIR, OBJECTS_DIR, REPORTS_DIR and LOG_DIR
The four directories exist for the reader: one directory would work for the flow, but when the directory says what a file is for, a user finds the result a later stage reads, the log of a failed step or the report to look at without reading the Makefile. The rules were unwritten, and files on master break them: route.guide and maze.log sit in RESULTS_DIR although no stage reads them, klayout.lyt sits in OBJECTS_DIR although the final stage reads it. The contract now says what each directory holds, with the edge cases named: a stage is a numbered stage, not a make target; a file that can affect the flow is a result even when a person also reads it; a file that only suggests a change is a report; a cache a stage falls back from is the stage's own; a stage's metrics .json stays next to its log. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
1 parent 64939f3 commit a2acaac

1 file changed

Lines changed: 24 additions & 0 deletions

File tree

‎docs/contrib/MakefileContract.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,3 +138,27 @@ Several of the rules exist for them.
138138
`$(shell sed ...)`.** That logic is in Python with unit tests.
139139
*Breaks:* a heuristic nobody can test, read, or run on a machine without
140140
that tool.
141+
142+
## Directories
143+
144+
A design's files are split over four directories so that where a file lands
145+
says what it is for. One directory would work for the flow; four make the
146+
tree legible.
147+
148+
- **`RESULTS_DIR` holds what can affect the flow:** what a later stage reads,
149+
and what a flow built on ORFS uses. A file that can affect the flow goes
150+
here even when a person also reads it (`memories.json`).
151+
*Breaks:* a flow that hands a stage only the earlier stages' results is
152+
missing a file the stage reads.
153+
- **`OBJECTS_DIR` holds what only its own stage uses, and stopgaps that
154+
wait for a cleaner implementation.** A stage is a numbered stage, not a
155+
make target: a file passed between the steps of one stage belongs here. So
156+
does a cache the stage falls back from on a miss.
157+
*Breaks:* a later stage reads a file nobody declared as a result.
158+
- **`REPORTS_DIR` holds what tools or people read afterwards.** No stage reads
159+
it. A file that only suggests a change, such as `updated_clks.sdc`, is a
160+
report.
161+
*Breaks:* a user looks in `RESULTS_DIR` for what the flow produced and finds
162+
debug output.
163+
- **`LOG_DIR` holds logs,** and a stage's metrics `.json` next to its log.
164+
*Breaks:* `genReport.py` and the metrics tools miss a run's record.

0 commit comments

Comments
 (0)