From 2c4fa58cad2a90bb9380e46aaf6df8af879f6cd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=98yvind=20Harboe?= Date: Tue, 27 Oct 2026 20:51:41 +0100 Subject: [PATCH] docs: MakefileContract: what goes in RESULTS_DIR, OBJECTS_DIR, REPORTS_DIR and LOG_DIR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Øyvind Harboe --- docs/contrib/MakefileContract.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/contrib/MakefileContract.md b/docs/contrib/MakefileContract.md index ae604ca719..333f800403 100644 --- a/docs/contrib/MakefileContract.md +++ b/docs/contrib/MakefileContract.md @@ -138,3 +138,27 @@ Several of the rules exist for them. `$(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.