KiCadRoutingTools CLAUDE.md

Project Notes for Claude

Running Python

Invoke Python as python3 (bare python does not exist on macOS and many Linux distros). On Windows, if python3 is missing, fall back to py -3 or python — don't retry blindly. Add -X utf8 when a script prints special characters (Ω etc.) to avoid Windows encoding errors.

On Windows/Git Bash, export MSYS2_ARG_CONV_EXCL='*' before any command carrying NET NAMES. MSYS2 rewrites any argument starting with / into a Windows path, and every KiCad net name is /-prefixed: /+1V1 reaches the tool as C:/Program Files/Git/+1V1. Nothing warns, because a tool cannot tell a mangled net name from a net that does not exist. Measured: 61 nets passed to --ignore-nets, 4 survived (the four not starting with /), and the resulting render reported 1315 crossings where the truth was 357. It hits --nets, --ignore-nets, --power-nets, --rip-existing-nets — every net-name argument. The variable is not free: it also disables conversion for legitimate paths, so ~/Documents/... then arrives as an unusable /c/Users/.... Pass Windows-style paths (C:/Users/...) in the same command.

Building the Rust Router

Use build_router.py to build the Rust router:

python build_router.py

This builds the Rust module, copies the library to the correct location, and verifies the version. Do not run cargo build directly.

Prefer Python-only solutions; avoid changing the Rust router (rust_router/) unless clearly necessary and agreed. A Rust change forces a crate version bump, a build_router.py --from-source rebuild, and re-distributing prebuilt per-platform binaries via GitHub Releases — heavy overhead. When a feature seems to need a Rust change, surface that cost early and check for a Python-only approach first.

Important: When making changes to the Rust router, bump the version in rust_router/Cargo.toml and update the version history in rust_router/README.md. The release triple is rust_router/Cargo.toml + /VERSION + metadata.json — keep them aligned. The crate is 0.20.1 and the 0.20.1 binaries ARE now published, in the v0.20.2 release (2026-08-09; verified — the published grid_router-macos-arm64.so reports __version__ == 0.20.1). v0.20.2 is a python-only release, so Cargo.toml correctly stayed at 0.20.1 while /VERSION went to 0.20.2, and the release built the crate as it stands: a plain python3 build_router.py now downloads and keeps the prebuilt instead of paying a wasted download and rebuilding from source. (The older hazard, for reference: the v0.20.1 release carried 0.20.0-built assets. build_router.py handles that case on its own — it skips the download when Cargo.toml is ahead of the release tag, and when the tag matches but the asset inside is stale it detects the version mismatch after install and rebuilds from source. Both checks verify in a fresh subprocess: an in-process re-import of a compiled extension reports the previously-loaded library. --from-source just skips the lookup. 0.20.1 removes the block_vias parameter from add_stub_proximity_costs_batch, so the 0.20.0 binary is API-incompatible with current Python besides the version gate.) Note this is why /VERSION can lead Cargo.toml — a python-only release still republishes the current crate binaries, which is the cheapest way to unstick a stale-asset release.