AGENT.md: record how to rebuild the C++ module here, and why the obvious commands fail
DECISION: write the build experience of this series into AGENT.md, as that file asks ("if you have any
experience during working, write it down here, with detailed reasons").
WHY: the owner asked for a one-solid Part to be implemented urgently (see design-docs/part-holds-one-solid.md),
which needed a rebuilt native module, and the first three build attempts failed for reasons the errors do not
show: a CMakeCache pointing into a deleted temporary build environment, the NMake generator being chosen when
none is configured, a stale OpenCASCADE found in %TEMP%, and the installed .pyd being locked by the owner's
running editor. The next person (or agent) to change src/cpp on this machine should not rediscover them. The
same note records the web UI rebuild, the `npx tsc` trap, `git add -f` for design-docs, and that
docstrings.json shadows source docstrings.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -29,3 +29,29 @@ BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks h
|
||||
# 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.
|
||||
|
||||
- Use the project's own path, `uv pip install --python .venv/Scripts/python.exe -e . --no-deps -v`. It reuses
|
||||
`src/cpp/build/wheel/<tag>/` (incremental when the compiler flags did not change). Plain `ninja _native` in 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 `nmake` here) 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 at `src/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 `.pyd` aside, 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 changing `editor-web/src`, rebuild it with
|
||||
`editor-web/node_modules/.bin/vite.exe build`, and typecheck with `node editor-web/node_modules/typescript/bin/tsc
|
||||
--noEmit -p editor-web/tsconfig.json` (`npx tsc` downloads an unrelated package named tsc).
|
||||
- `design-docs/` is git-ignored but some files in it are tracked: a new file there needs `git add -f`.
|
||||
- `docstrings.json` is read back over the docstring in the Python source at import time, so a docstring edit is
|
||||
invisible in `help()` until `_glue/docstrings.json` is updated too (edit the one line, do not re-dump the file).
|
||||
|
||||
Reference in New Issue
Block a user