Skip to content

Commit 2c4fa58

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, a user finds the design, a measurement of it, a log or the scaffolding without reading the Makefile. The rule was unwritten. This writes down the one master already follows: the design in any format in RESULTS_DIR, measurements in REPORTS_DIR, logs and the metrics .json next to them in LOG_DIR, and what is not the design (derived platform files, a step's own intermediates, caches, stopgaps) in OBJECTS_DIR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Øyvind Harboe <oyvind.harboe@zylin.com>
1 parent 64939f3 commit 2c4fa58

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: the design, a measurement of it, a log, or scaffolding. One
146+
directory would work for the flow; four make the tree legible. What a file
147+
is decides its directory, not who reads it.
148+
149+
- **`RESULTS_DIR` holds the design, in any format:** netlists, `.odb`,
150+
`.def`, `.gds`, `.sdc`, routing guides, placement scripts, the checkpoint a
151+
failed step leaves, and memory inventories.
152+
*Breaks:* a flow or a user looking for the design finds part of it
153+
elsewhere.
154+
- **`REPORTS_DIR` holds measurements of the design,** for tools or people to
155+
read. No step's result depends on it.
156+
*Breaks:* a flow that hands a step only the results has to carry reports
157+
along.
158+
- **`LOG_DIR` holds logs,** and each step's metrics `.json` next to its log.
159+
*Breaks:* `genReport.py` and the metrics tools miss a run's record.
160+
- **`OBJECTS_DIR` holds what is not the design:** files a step derives from
161+
the platform (`klayout.lyt`), a step's own intermediate files
162+
(`abc.constr`, `rtlmp/`, `surgery/`), caches, and stopgaps that wait for a
163+
cleaner implementation.
164+
*Breaks:* the design is mixed with scaffolding.

0 commit comments

Comments
 (0)