On a Windows machine without Visual Studio, scikit-build-core left the generator to CMake's default (NMake), the build failed with "'nmake' -? failed", and every contributor had to hand-set CMAKE_GENERATOR / CC / CXX / CMAKE_ARGS. uv also rebuilt the editable install on any pyproject.toml change (a version bump), which is how the failure showed up after the 2.2.9 release. - tools/build_backend/scad_build.py: a PEP 517 backend wrapping scikit-build-core. On Windows it uses Ninja + the gcc on PATH when Visual Studio is absent, finds OCCT (SCAD_OCCT_PREFIX, C:/occt, a per-user cache, or builds it once with tools/build_occt.py) and limits jobs by RAM (g++ ran out of memory under ninja's default). Anything the user or CI sets wins. - [tool.uv] cache-keys: rebuild only when src/cpp changes. Build tooling only: nothing in the published package changes, so no version bump. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
8.6 KiB
First of all, you should follow the phylosophy below whatever you are going to do:
Completeness Principle — Boil the Lake
AI-assisted coding makes the macrginal cost of completeness near-zero. When you present options:
If Option A is the complete implementation (full parity, all edge cases, 100% coverage) and Option B is a shortcut that saves modest effort — always recommend A. The delta between 80 lines and 150 lines is meaningless with Codex. "Good enough" is the wrong instinct when "complete" costs minutes more. Lake vs. ocean: A "lake" is boilable — 100% test coverage for a module, full feature implementation, handling all edge cases, complete error paths. An "ocean" is not — rewriting an entire system from scratch, adding features to dependencies you don't control, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope. When estimating effort, always show both scales: human team time and Codex time. The compression ratio varies by task type — use this reference: Task type Human team Codex Compression Boilerplate / scaffolding 2 days 15 min ~100x Test writing 1 day 15 min ~50x Feature implementation 1 week 30 min ~30x Bug fix + regression test 4 hours 15 min ~20x Architecture / design 2 days 4 hours ~5x Research / exploration 1 day 3 hours ~3x This principle applies to test coverage, error handling, documentation, edge cases, and feature completeness. Don't skip the last 10% to "save time" — with AI, that 10% costs seconds. Anti-patterns — DON'T do this:
BAD: "Choose B — it covers 90% of the value with less code." (If A is only 70 lines more, choose A.) BAD: "We can skip edge case handling to save time." (Edge case handling costs minutes with Codex.) BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.) BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour Codex.")
Second: Only do necessary action, rather than do much is better.
Third: Never use complex English Terms in chinese, you should say normal chinese.
Before editing or adding code, plan for module splitting rather than putting code in one file which is not human readable.
If you have any experience during working, you can write it down here, with detailed reasons.
Experience: rebuilding the C++ module on this Windows machine (2026-11-10)
Why this is written down: changing anything under src/cpp needs a rebuilt _native module, and the obvious command
failed three times before it worked. Each failure had a cause that is not visible from the error text.
- UPDATE (2026-11-10, later): none of the flags below are needed any more.
pyproject.tomlbuilds withtools/build_backend/scad_build.py, which on Windows picks Ninja + the gcc on PATH when Visual Studio is absent, finds OCCT (SCAD_OCCT_PREFIX,C:/occt, or%LOCALAPPDATA%/simplecadapi/occt-<tag>, building it there once if missing) and limits the job count by RAM. A bareuv sync/uv runworks; anything you set yourself (CMAKE_GENERATOR, CC, CXX, CMAKE_ARGS, CMAKE_BUILD_PARALLEL_LEVEL) still wins.[tool.uv] cache-keysmakes uv rebuild only whensrc/cppchanges, not on a version bump. What remains true: a running editor locks the installed.pyd(rename it aside, see below). - (Older note) Use the project's own path,
uv pip install --python .venv/Scripts/python.exe -e . --no-deps -v. It reusessrc/cpp/build/wheel/<tag>/(incremental when the compiler flags did not change). Plainninja _nativein that directory fails: its CMakeCache points into a temporary isolated build environment (ninja, pybind11, python) that was deleted when the last build ended, so CMake cannot regenerate. - A bare run picks the NMake generator (no
nmakehere) and then a stale OpenCASCADE from%TEMP%\occt-build-*. Pass the MinGW toolchain and the real OCCT explicitly, in the same shell:CMAKE_GENERATOR=Ninja CC=<scoop gcc>/gcc.exe CXX=<scoop gcc>/g++.exe CMAKE_ARGS="-DCMAKE_MAKE_PROGRAM=<scoop shims>/ninja.exe -DSCAD_OCCT_PREFIX=C:/occt -DOpenCASCADE_DIR=C:/occt/lib/cmake/opencascade". (The first full rebuild after the environment changed took about 4 minutes; the next, after one binding file, 1m16s.) - The build ends with "failed to remove ... Scripts/sca.exe" when an editor (
sca edit) is running: that is only the install step. The compiled module is already atsrc/cpp/build/wheel/<tag>/bindings/python/_native.<tag>.pyd. The installed copy in.venv/lib/site-packages/simplecadapi/_cpp/is locked by the running processes (copy fails with "Device or resource busy") but Windows lets you RENAME a loaded DLL: rename the old.pydaside, copy the new one in. New processes load the new module, running editors keep the old one. Do not kill the user's editor to install. - The built web UI (
src/simplecadapi/editor/webui/) is git-ignored: after changingeditor-web/src, rebuild it witheditor-web/node_modules/.bin/vite.exe build, and typecheck withnode editor-web/node_modules/typescript/bin/tsc --noEmit -p editor-web/tsconfig.json(npx tscdownloads an unrelated package named tsc). design-docs/is git-ignored but some files in it are tracked: a new file there needsgit add -f.docstrings.jsonis read back over the docstring in the Python source at import time, so a docstring edit is invisible inhelp()until_glue/docstrings.jsonis updated too (edit the one line, do not re-dump the file).
How to commit: one decision per commit, with the reasons (the owner's rule, 2026-11-10)
Why this rule exists: a change that reverses an earlier design (for example "a Part holds exactly one solid") is made of many small edits across layers. Someone who takes over later sees the edits, not the conversation that caused them. The commit history is where that conversation has to survive, so that handing over and tracing back are possible without asking anyone.
- One commit per decision, split as finely as is sensible. A decision is a choice that could have gone the other way (a rule, a format, an API removal, a place where a feature lives). Edits that only follow from a decision (tests, docs, comments, dead code) are their own commits, each stating which decision they follow. Do not mix two decisions in one commit; do not split one decision so far that no commit holds its reason.
- Every message states the chain of the decision and WHY, and the why carries the core of the discussion between the owner and the assistant that led to it: the need that started it, the owner's judgement, the analysis that was agreed, and what was rejected. Write it as what was said, not as a summary of the diff. The reader must be able to see why the decision exists from the message alone.
- Message layout (subject line, then paragraphs; the subject says the decision, not only the edit):
DECISION:what is decided, in one or two sentences.WHY(name the discussion and its date; point to the decision record): the need, the judgement, the analysis, and facts found by checking (with where and how they were checked).ALTERNATIVE CONSIDERED AND REJECTED:when there was one, and why.WHAT CHANGES:the files / behaviour, only as far as the reason needs; and what is kept on purpose.Checked:what was run and what it showed, including what was not verified.- Last line:
Co-Authored-By: ...as the session's attribution reminder says.
- A decision that outlives one commit gets a decision record in
design-docs/<name>.md(the whole discussion, the audit table, the rules after the decision, the list of commits). The first commit of the series carries the full account; later commits carry the short form and name that commit or the record.design-docs/is git-ignored: add a new file withgit add -f. If an older design document is replaced, mark it superseded at its top and keep its body. - Refer to other commits by subject line, not by hash. Hashes change when history is rewritten (rewording a
message with
filter-branchchanged every hash of the series once); a subject survives. A hash is acceptable only for a commit that is already published or will not be rewritten. - Say the true thing. If a message claims a check passed or a set of files is equal, run the check first; if
a claim turns out wrong,
git commit --amendwhile the commit is still the newest and unpublished. - Mechanics that worked here: write the message to a file with the file tool and use
git commit -F file(long heredocs with quotes broke in this shell); stage by explicit paths, nevergit add -A(the untrackedSTILLfile is not ours); work on a branch, not onmaster; do not push or merge unless asked.