AI_Assistant/pcbjam
Watch
1
0
Fork
You've already forked pcbjam
 0
Code Issues Pull requests Projects Releases 4 Packages Wiki Activity Actions 2
pcbjam/docs/features/fork-cleanup/README.md
Istvan Matejcsok c35005589d refactor(cmake): batch F (gerbview/pl_editor #5 + navlib #6) + docs 
Bumps kicad to 6f82742e68 (in-place CMake de-dup pass A-F complete) and updates
the fork-cleanup docs: CMake churn 1,702 -> 1,019, build-graph proven byte-identical
pre/post (zero behavior change), only Phase-B cmake/wasm relocation remaining.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-22 18:50:08 +02:00

9.6 KiB
Raw Blame History

Fork cleanup: minimize divergence & re-enable web-feasible features

Status: research / planning only. No code has been changed. Authored June 2026. All file:line references are against the kicad submodule at its current HEAD (ac7d733787), upstream merge-base 4bfed3f174, and the root repo at the same time. Verify line numbers before editing — they drift.

⚠️ The baseline counts in this README are superseded — doc 01 has since landed (commit c39e8f8689) and other work shifted the numbers. For the current divergence, the per-change revert/relocate/re-enable verdict, effort, and resulting diff, see 00-effort-and-current-state.md (measured at HEAD cb82b64410, 2026-06-17): ~2,795 churned lines / 88 modified files today → ~480–620 / ~50 files after ~16–28 engineer-days of cleanup.

Why this exists

Getting KiCad to build for the browser meant disabling, stubbing, and #ifdef-ing a lot of things "because we had to." Two goals now pull in the same direction:

  1. Keep the kicad and wxwidgets forks as close to mainline as possible. Where we add things, they should live in new files/folders (or build flags, runtime config, the wasm/ layer) — not as edits to upstream source.
  2. Everything that can work in a browser should actually work. The 3D viewer, importers, the symbol chooser — turn them back on. Only Python scripting and things that are genuinely impossible on the web stay off.

The key reframe that ties them together: re-enabling features mostly deletes fork code. Almost everything disabled is disabled by a fork-added gate, stub, or exclusion. Turning it back on removes that divergence. The two goals are one project.

TL;DR — the baseline and the target

Fork state vs. merge-base 4bfed3f174 (24 commits):

Count
New files (policy-compliant) 44 (~28k lines, mostly the WebGL GAL copy)
Modified upstream files 104
Changed lines in modified files ~2,400 (~1,600 of it CMake)

Estimated reachable end-state after the refactors below: ~15–20 modified files / ~150–250 lines, with the WASM product gaining the 3D viewer, render-to-PNG jobs, VRML export, five importers, the symbol browser, and optionally simulation, tooltips, HTTP libraries, and working local history.

Three facts do most of the work:

  • Big chunks of the diff are dead code. All #ifdef KICAD_IPC_API gating, the +189-line kiglew.h shim, and the opengl_gal.cpp refactor compile in configurations the shipping build never uses. See 01.
  • Several "disabled" features are disabled by stale mechanisms. The Altium importer's blocker was fixed months ago (the fix is force-included into every TU); three build-script -D flags don't even exist as options in this KiCad version. See 08 and 07.
  • The 3D viewer has a cheap path. KiCad ships a pure-CPU raytracer that needs zero OpenGL, and the fork currently nulls it out. See 10.

Master inventory

Every disabled/divergent item, with verdict. Detail + recipes in the linked docs.

Reduce divergence (shrink the submodule diff — no behavior change)

Item Mechanism Action Doc
#ifdef KICAD_IPC_API gates (18 files) dead code (build sets =ON) revert 01
kiglew.h +189, opengl_gal.cpp +32/−31 dead (opengl GAL not built for wasm) revert 01
KI_DIAG_* call sites (~30 lines) debugging a solved crash delete 01
~600 lines of CMake reindent/duplication wrap-and-reindent instead of additive de-churn 02
zoom warp, Backspace, timer, kiface init #ifdef behavior changes runtime config 03
fontconfig/libcontext/SpaceMouse stubs in-file #ifdef move to new TUs 04
scale factor, selection, header hygiene wx-port quirks patched in KiCad fix in wx fork 05
RTree fix, hotkey bug, wxUSE_* guards upstreamable send upstream 06
6 native-build regressions + diff tooling fork bugs fix 07

Re-enable (web-feasible — mostly deletes gates)

Item Blocker today Verdict Doc
Altium importer (sch+pcb) stale exclusion (fix already active) re-enable now 08
Eagle/CADSTAR/LTspice/EasyEDA(Pro) sch MVP-scoping exclusion re-enable now 08
Symbol chooser + viewer empty lib tables (asset gap) un-gate + asset pipeline 09
3D viewer + render job + VRML export KICAD_BUILD_3D_VIEWER_WASM=OFF + gates port (raytracer first) 10
SPICE simulator ngspice dep stubbed port (~1–2 wk) 11
HTTP libraries / local history curl & libgit2 stubbed port 12
Tooltips wxUniversal never implemented them port in wx fork 05

Keep off

  • Impossible: SpaceMouse/navlib, ODBC database, nng/IPC transport, fswatcher, webview, dynamic KIFACE dlopen, OS keychain, pointer warping. (See 12 for the full catalog and why each is impossible.)
  • Policy-off: Python scripting (see ../../../features/python/research.md), PCM, update check, the kicad project-manager / cvpcb apps (never wasm targets).

Suggested sequencing

  1. Quick wins + dead-code reverts (01, 07, 08) — one build, one e2e run; large diff reduction and new importers. Importers are configure-confident but runtime-untested → smoke-test with a sample Eagle + Altium file.
  2. 3D viewer Route C (10) — raytracer + blit; brings render job and VRML export back nearly free.
  3. Symbol-library asset pipeline (09).
  4. CMake de-churn + config-not-code + stub relocation + wx fixes (02–05) — the bulk of the remaining line-count reduction.
  5. Upstream PRs (06) — divergence that vanishes on merge.
  6. 3D Route B (WebGL2) and Tier-3 ports (10–12) per product priority.

Document index

File Contents
00-effort-and-current-state.md Current state (2026-06-17): per-change revert/relocate/re-enable verdict, effort, and resulting diff math reconciled against a live file ledger. Read this first.
01-revert-dead-code.md Diff that compiles only in unused configs: IPC-API gates, kiglew.h, opengl_gal.cpp, diagnostics. ~480 lines, zero behavior change. (DONE — c39e8f8689.)
02-cmake-dechurn.md ~600 lines of CMake reindent/duplication → early-return guards, list(REMOVE_ITEM), shader-hook, relocate if(EMSCRIPTEN) to cmake/wasm/. (In-place de-dup A–F done — 6f82742e68; CMake churn 1,702→1,019, build graph proven identical. Only Phase-B cmake/wasm/ relocation remains.)
03-config-not-code.md Patches that re-implement existing settings: zoom pref, hotkeys file, HAVE_CLOCK_GETTIME, kiface init from the shell.
04-stub-tu-relocation.md Move in-file #else stubs to new translation units: fontconfig, libcontext, SpaceMouse.
05-wx-layer-fixes.md KiCad patches that belong in the wxWidgets wasm port: scale factor, selection, header self-sufficiency, tooltips.
06-upstreamable-patches.md Bug fixes & portability guards to send to KiCad/wxWidgets upstream so the diff disappears on merge.
07-native-build-bugs-and-tooling.md 6 regressions the fork introduced into native builds + dead build-script flags + the broken kicad-diff-stats.sh.
08-importers.md Re-enable Altium + Eagle/CADSTAR/LTspice/EasyEDA(Pro). Net-negative diff.
09-symbol-libraries.md Un-gate the symbol chooser/viewer + ship a starter library set to the browser FS.
10-3d-viewer.md Why it's off; Route C (CPU raytracer), Route B (WebGL2 port), Route A (rejected); model loading; render job; VRML export.
11-ngspice-simulator.md Static-link a wasm ngspice + the one init_dll branch; retest the model-data stubs.
12-network-stack.md curl→fetch shim, libgit2/local-history, and the catalog of genuinely-impossible features.

Related docs