pcbjam/docs/features/fork-cleanup/02-cmake-dechurn.md

# 02 — CMake de-churn

> **Status — the in-place de-dup pass (batches A–F) is COMPLETE** (kicad `6f82742e68` on `b5ac6dcbe4`,
> root `0b4d830`): Move 0 (`KICAD_WASM_LAYER` var) + moves #1–#7 across all apps, incl. #5 for
> gerbview/pl_editor and #6 (navlib, behavior-preserving stub de-churn). **Not yet done:** only the
> `cmake/wasm/` **relocation (Phase B)**. CMake churn: **1,702 → 1,019** (−683), validated by an `-O1`
> WASM build (pcbnew/eeschema/calculator) + 9/9 e2e with no screenshot change, **and a build-graph
> equivalence proof** (compile + link + custom commands byte-identical pre/post across the whole tree) →
> zero behavior change. The recipes below describe the full design (Phase-B relocation still pending).

> The build-system diff is **~1,600 changed lines across 17 `CMakeLists.txt` files**, and
> **35–40% of it (~600 lines) is reindentation and duplication** — not logic. The logic
> that *is* there (single-binary kiface linking, stub injection, the WebGL GAL) is mostly
> legitimate; it's expressed in the most invasive way possible. This refactor keeps the
> behavior and cuts the touched-line count to roughly **120–180** inside upstream files.

## The anti-patterns and their fixes

### 1. Wrap-and-reindent → early-return guard

`pcbnew/CMakeLists.txt`: the ~110-line Python-module install section was wrapped in
`if(KICAD_SCRIPTING) … endif()` **and reindented**, turning ~110 lines into ~215 diff
lines. The section runs to EOF, so a 3-line guard does the same job with ~5 diff lines:

```cmake
if( NOT KICAD_SCRIPTING )
    return()
endif()
# ... upstream python-install body, unindented, byte-identical ...
```

`scripting/CMakeLists.txt` already does the minimal version of this (top-level `if(...)` /
bottom `endif()`, **no reindent**) — copy that discipline. Same treatment for the root
`CMakeLists.txt` Python/SWIG discovery section (~100 lines of pure reindent today).

### 2. if/else source duplication → `list(REMOVE_ITEM)`

The additive pattern is already proven in-tree for the ngspice BSIM data files
(`eeschema/CMakeLists.txt`): keep the upstream list byte-identical, then remove/replace
under `if(EMSCRIPTEN)`:

```cmake
# upstream SRCS list stays exactly as-is, then:
if( EMSCRIPTEN )
    list( REMOVE_ITEM FOO_SRCS path/to/native_only.cpp )
    list( APPEND FOO_SRCS ${KICAD_WASM_LAYER}/stubs/foo_stub.cpp )
endif()
```

Apply to: the OpenGL-GAL sources in `common/gal/CMakeLists.txt` (currently moved into an
`if(NOT EMSCRIPTEN)` block + reindented), the eeschema importer block, the
`common/CMakeLists.txt` exclusions (`python_scripting.cpp`, `api_utils.cpp`, altium,
database, webview), and the `PCBNEW_IO_LIBRARIES` altium dual-list in `pcbnew/CMakeLists.txt`.

### 3. pcb_calculator: whole file forked → block + `return()`

`pcb_calculator/CMakeLists.txt` (+130/−89) forks the *entire* file `if(EMSCRIPTEN) … else()`
with the upstream body reindented in the `else`. Instead, insert the wasm single-binary
block (duplicating only `make_lexer`) followed by `return()` *before* the upstream
`add_executable`, leaving the upstream body untouched. ~160 diff lines → ~55 additive.

### 4. Shader calls: 85-line duplicate → redefine-the-function hook

`common/gal/CMakeLists.txt` duplicates all 10 upstream `add_shader(...)` calls in an
`else()` branch for the ES3 variant. Instead, after upstream's `add_shader` definition,
`include()` a wasm `.cmake` that *redefines* `add_shader` to the ES3 path (later definition
wins) — upstream's 10 calls are then reused verbatim.

### 5. `BUILD_KIWAY_DLL` source-property forks (5 apps)

eeschema/pcbnew/gerbview/pl_editor/pcb_calculator each fork the `set_source_files_properties`
defs `if/else`. Replace with a single additive `if(EMSCRIPTEN)` block *after* the upstream
lines that re-sets the properties (last set wins). ~120 diff lines → ~35 additive.

### 6. navlib ×3: probably deletable entirely

`pcbnew/navlib`, `gerbview/navlib`, `pagelayout_editor/navlib` each fork their CMakeLists to
build a stub from `wasm/stubs/nl_*_plugin_stub.cpp` with the upstream body reindented in the
`else`. **But `eeschema/navlib` is unchanged** and builds its *real* sources under wasm
against the bundled `thirdparty/3dxware_sdk` stub. Strong evidence the other three stub
forks are unnecessary — try reverting all three CMakeLists and deleting the 3 stub `.cpp`
files. (This also fixes a native bug — see [07](07-native-build-bugs-and-tooling.md) on the
duplicate `add_subdirectory(navlib)`.) Fallback if a link fails: a 4-line early-return stub
`include()` at the top of each, with zero reindent.

### 7. `kiapi` SHARED-vs-STATIC: variable, not duplicate list

`api/CMakeLists.txt` (+14/−5) duplicates the source list across an
`add_library(kiapi SHARED)` / `STATIC` if/else. Collapse to `set(_KIAPI_TYPE ...)` + one
`add_library(kiapi ${_KIAPI_TYPE} ...)`.

## Relocate the surviving `if(EMSCRIPTEN)` logic

The legitimate blocks (static-kiface linking, stub `target_sources`, the `symbol_editor`
target, WebGL GAL sources) don't shrink in *content*, but they can move out of upstream
files into a new merge-conflict-free directory:

- Create `kicad/cmake/wasm/*.cmake` and reduce each upstream `CMakeLists.txt` touch to a
  1–3 line `if(EMSCRIPTEN) include(wasm/foo.cmake) endif()` hook.
- Replace the hardcoded `${CMAKE_SOURCE_DIR}/../wasm` paths (which reach outside the
  submodule and currently prevent it from configuring standalone) with a `KICAD_WASM_LAYER`
  cache variable, defaulted to `../wasm` and passed by `build-kicad-target.sh`.

## Mechanisms that were evaluated and rejected

- **`CMAKE_PROJECT_INCLUDE` / `CMAKE_PROJECT_KICAD_INCLUDE`**: runs at `project()` time —
  *before* upstream's `set(CMAKE_MODULE_PATH ...)` overwrite — so it can't even replace the
  1-line module-path fix, and can't reach subdirectory logic. Worth ~2% of the diff; skip.
- **Super-project `add_subdirectory(kicad)` wrapper**: infeasible. KiCad uses
  `${CMAKE_SOURCE_DIR}` pervasively (incl. the `../wasm` reach-outs and install logic); it
  would re-root to the super-project and break.

## Net

Moves 1–7 alone cut the build-system diff from ~1,600 to roughly **500–600** lines; adding
the `cmake/wasm/` relocation drops the lines touched *inside upstream files* to roughly
**120–180**. Irreducible in-place edits that remain: the `CMAKE_MODULE_PATH` preserve
(1 line), the wx-port regex `(msw|qt|gtk|osx)` → `(…|wasm)` (1 line), the `KICAD_SCRIPTING`
option, root `add_subdirectory` gates, `kiapi` genex gates in `common`, and the
`thirdparty/lemon` cross-compile block.