diff --git a/AGENT.md b/AGENT.md index c707112d..cb2f7791 100644 --- a/AGENT.md +++ b/AGENT.md @@ -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//` (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=/gcc.exe CXX=/g++.exe + CMAKE_ARGS="-DCMAKE_MAKE_PROGRAM=/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//bindings/python/_native..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). diff --git a/test/test_multi_body_part.py b/test/test_one_solid_part.py similarity index 100% rename from test/test_multi_body_part.py rename to test/test_one_solid_part.py