Merge wip/166-coin-port: ECCE_USE_COIN build option, off by default (#166 stage 1)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R9WkbXZ96rqCJxYuumcrgF

Author: andy

CMakeLists.txt

@@ -92,6 +92,27 @@ include_directories(
   ${FREETYPE_UNQUALIFIED_INCLUDE_DIR}
 )
 
+# #166: build against the system Coin3D instead of the
+# vendored Inventor core in src/inv. <inv/X/Y.H> includes are forwarded to
+# <Inventor/X/Y.h> by a generated overlay that is searched before include/.
+option(ECCE_USE_COIN "Build against Coin3D instead of the vendored Inventor core (#166; coexists with the vendored core until stage 4)" OFF)
+if(ECCE_USE_COIN)
+  file(GLOB _coin_scan LIST_DIRECTORIES true ${CMAKE_SOURCE_DIR}/src/*)
+  list(FILTER _coin_scan EXCLUDE REGEX "/src/inv$")
+  file(GLOB _coin_scan_inc LIST_DIRECTORIES true ${CMAKE_SOURCE_DIR}/include/*)
+  list(FILTER _coin_scan_inc EXCLUDE REGEX "/include/inv$")
+  list(APPEND _coin_scan ${_coin_scan_inc})
+  execute_process(COMMAND python3 ${CMAKE_SOURCE_DIR}/tools/coin/gen_shim.py
+                          ${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR}/coin-shim ${_coin_scan}
+                  RESULT_VARIABLE _shim_rc)
+  if(NOT _shim_rc EQUAL 0)
+    message(FATAL_ERROR "gen_shim.py failed")
+  endif()
+  include_directories(BEFORE ${CMAKE_BINARY_DIR}/coin-shim)
+  add_compile_definitions(OIV_COIN)
+  find_library(COIN_LIBRARY Coin REQUIRED)
+endif()
+
 if(APPLE)
   # ~90 files across the tree spell OpenGL headers the Linux/X11 way
   # ("GL/gl.h", "GL/glu.h") -- Apple's own OpenGL framework headers live
@@ -222,21 +243,6 @@ else()
   set_property(TARGET eccercmd PROPERTY SOURCES ${_rcmd_srcs})
 endif()
 # --- src/inv -> libecceinv.a + libeccemoiv.a (libeccewxinv.a needs wx, TODO) ---
-ecce_library(ecceinv
-  src/inv/dbelements
-  src/inv/dbengines
-  src/inv/dbfields
-  src/inv/dbnodes
-  src/inv/dbsb
-  src/inv/dbso
-  src/inv/dbupgraders
-  src/inv/flclient
-  src/inv/image
-  src/inv/interaction
-  src/inv/nodekits
-)
-target_compile_definitions(ecceinv PRIVATE NDEBUG)
-target_link_libraries(ecceinv PRIVATE OpenGL::GL OpenGL::GLU)
 # Old build's src/inv/flclient/Makefile adds `pkg-config --cflags-only-I freetype2`
 # on top of the baseline include dir: some FreeType headers (ft2build.h) live at
 # the top of the freetype2 include tree, others (ftoutln.h etc, used elsewhere in
@@ -249,8 +255,30 @@ find_path(FREETYPE_ROOT_INCLUDE_DIR ft2build.h
 if(NOT FREETYPE_ROOT_INCLUDE_DIR)
   message(FATAL_ERROR "FreeType's ft2build.h not found -- searched the usual Linux and Homebrew locations")
 endif()
-target_include_directories(ecceinv PRIVATE ${FREETYPE_ROOT_INCLUDE_DIR})
-
+if(ECCE_USE_COIN)
+  # Only the FreeType font layer (flclient) is kept from the vendored core.
+  ecce_library(ecceinv src/inv/flclient)
+  target_compile_definitions(ecceinv PRIVATE NDEBUG)
+  target_include_directories(ecceinv PRIVATE ${FREETYPE_ROOT_INCLUDE_DIR})
+  target_link_libraries(ecceinv PUBLIC ${COIN_LIBRARY} OpenGL::GL OpenGL::GLU)
+else()
+  ecce_library(ecceinv
+    src/inv/dbelements
+    src/inv/dbengines
+    src/inv/dbfields
+    src/inv/dbnodes
+    src/inv/dbsb
+    src/inv/dbso
+    src/inv/dbupgraders
+    src/inv/flclient
+    src/inv/image
+    src/inv/interaction
+    src/inv/nodekits
+  )
+  target_compile_definitions(ecceinv PRIVATE NDEBUG)
+  target_link_libraries(ecceinv PRIVATE OpenGL::GL OpenGL::GLU)
+  target_include_directories(ecceinv PRIVATE ${FREETYPE_ROOT_INCLUDE_DIR})
+endif()
 ecce_library(eccemoiv src/inv/moiv)
 target_compile_definitions(eccemoiv PRIVATE NDEBUG)
 target_link_libraries(eccemoiv PRIVATE OpenGL::GL OpenGL::GLU)

GETTING_STARTED.md

@@ -33,6 +33,12 @@ generator (Unix Makefiles on Debian) instead of Ninja, which still builds
 but via `make`, not the `ninja` command used everywhere else in this
 document.
 
+Optional (#166, experimental): `cmake -G Ninja -DECCE_USE_COIN=ON ..` builds
+the 3D viewer stack against the system Coin3D (`libcoin-dev` 4.0.x on Debian)
+instead of the vendored Open Inventor core; the default (OFF) is unchanged.
+Use a separate build directory (e.g. `build-coin`) so both configurations can
+be built from one tree, and have CI build both while the two coexist.
+
 This produces the 19 GUI apps (`gateway`, `organizer`, `builder`,
 `pertable`, ...) plus the CLI apps, all statically linked against the
 in-tree libraries.

docs/claude/wx-viewer/ecce-use-coin-builds-the-viewer-against-coin3d.md

@@ -0,0 +1,28 @@
+---
+type: map
+title: "ECCE_USE_COIN builds the viewer stack against Coin3D; both builds coexist until stage 4"
+area: wx-viewer
+paths: [CMakeLists.txt, tools/coin/gen_shim.py, include/inv/ChemKit/ChemDisplay.H, include/inv/SoWx/SoWxViewer.H, src/inv/wxinv/SoWxRenderArea.C]
+issues: [166]
+---
+`cmake -DECCE_USE_COIN=ON` (default OFF) does not compile the vendored
+Inventor core in `src/inv` (`db*`, `image`, `interaction`, `nodekits`).
+`ecceinv` shrinks to `src/inv/flclient` (our FreeType font layer) plus
+`libCoin`; `moiv`, `wxinv`, `src/viz`, `src/wxviz` and the apps build
+unchanged otherwise. `<inv/X/Y.H>` includes are forwarded to
+`<Inventor/X/Y.h>` by an overlay that `tools/coin/gen_shim.py` writes into
+`<build>/coin-shim` at configure time and that is searched before
+`include/`; `OIV_COIN` is defined. `inv/ChemKit`, `inv/SoWx` and
+`inv/flclient.h` stay ours.
+
+Header fixes are portable and work in both builds: `ChemDisplay.H`
+includes Coin's `SoTextureCoordinateElement.h` (a typedef in Coin, so it
+cannot be forward-declared) and `SoWxViewer.H`/`SoWxRenderArea.C` include
+`SbLinear.h`/`SbColor.h`, which Coin's headers do not pull in transitively.
+
+Why both exist: the vendored core is still the shipped, tested viewer; the
+Coin build is validated side by side (stage 2 onwards) and the vendored
+core is removed only at stage 4. Use separate build directories
+(`build-cmake`, `build-coin`): switching the option in one tree rebuilds
+everything. After a change under `src/inv/moiv`, `src/inv/wxinv` or
+`include/inv/{ChemKit,SoWx}`, build both.

docs/claude/wx-viewer/index.md

@@ -12,6 +12,7 @@ Read this before changing any dialog, panel, sizer, grid, ewx control or the Ope
 ### wxWidgets 3.2/GTK3, the 3D viewer, and C++ pitfalls
 
 - [Open Inventor's redraw sensor is a ONE-SHOT that re-arms on render, and with a render callback installed nothing re-arms it](open-inventors-redraw-sensor-is-a-one.md)
+- [`ECCE_USE_COIN` builds the viewer stack against Coin3D; both builds coexist until stage 4](ecce-use-coin-builds-the-viewer-against-coin3d.md)
 - [wx3.2/GTK3 layout reentrancy](wx3-2-gtk3-layout-reentrancy.md)
 - [`wxGrid::CreateGrid()`/`SetTable()` synchronously fires `wxEVT_GRID_SELECT_CELL`](wxgrid-creategrid-settable-synchronously-fires-wxevt-grid.md)
 - [The `.pjd` (DialogBlocks) files are reference only; never regenerate code from them](the-pjd-dialogblocks-files-are-reference-only.md)

include/inv/ChemKit/ChemDisplay.H

@@ -106,7 +106,11 @@ class ChemBondStuff;
 class ChemUnitCylinder;
 class ChemUnitSphere;
 class SoClipPlaneElement;
+#ifdef OIV_COIN
+#include <Inventor/elements/SoTextureCoordinateElement.h>   // a typedef in Coin
+#else
 class SoTextureCoordinateElement;
+#endif
 // --> CAstick
 class ChemResidueStuff;
 class ChemData;

include/inv/SoWx/SoWxViewer.H

@@ -10,6 +10,9 @@
 #include <X11/Intrinsic.h>
 
 #include "inv/SoType.H"
+#ifdef OIV_COIN
+#include <Inventor/SbLinear.h>   // Coin headers do not pull this in transitively
+#endif
 #include "inv/SbTime.H"
 
 #define ID_VIEWER 1000000

src/inv/wxinv/SoWxRenderArea.C

@@ -2,6 +2,9 @@
 #include "inv/actions/SoGLRenderAction.H"
 #include "inv/elements/SoWindowElement.H"
 
+#ifdef OIV_COIN
+#include <Inventor/SbColor.h>
+#endif
 #include "inv/SoWx/SoWx.H"
 #include "inv/SoWx/SoWxRenderArea.H"
 #include "inv/SoWx/SoWxViewer.H"

tools/coin/gen_shim.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Build an include overlay that maps SGI-style <inv/X/Y.H> includes onto
+Coin's <Inventor/X/Y.h>. Headers Coin lacks become empty stubs and are
+listed in missing.txt. inv/ChemKit comes from the tree (moiv's own)."""
+import os, re, sys
+root, out = sys.argv[1], sys.argv[2]
+coin = "/usr/include/Inventor"
+scan = [os.path.join(root, d) for d in ("src/inv/moiv", "src/inv/wxinv", "include/inv/ChemKit", "include/inv/SoWx")]
+# extra roots to scan (headers outside src/inv that include inv/)
+scan += sys.argv[3:]
+pat = re.compile(r'^\s*#\s*include\s+[<"](inv/[^>"]+)[>"]', re.M)
+seen = set()
+for d in scan:
+    for dp, _, fs in os.walk(d):
+        for f in fs:
+            if f.endswith(('.C', '.H', '.h', '.c', '.cpp', '.inc')):
+                try: txt = open(os.path.join(dp, f), errors='replace').read()
+                except OSError: continue
+                for m in pat.finditer(txt): seen.add(m.group(1))
+missing = []
+for inc in sorted(seen):
+    if inc.startswith(("inv/ChemKit/", "inv/SoWx/")) or inc == "inv/flclient.h": continue
+    rel = inc[len("inv/"):]
+    base = re.sub(r'\.[Hh]$', '', rel)
+    target = os.path.join(out, "inv", rel)
+    os.makedirs(os.path.dirname(target), exist_ok=True)
+    c = "Inventor/" + base + ".h"
+    if os.path.exists(os.path.join("/usr/include", c)):
+        open(target, "w").write('#include <%s>\n' % c)
+    else:
+        open(target, "w").write('/* not in Coin: %s */\n' % inc)
+        missing.append(inc)
+os.makedirs(os.path.join(out, "inv"), exist_ok=True)
+for n in ("ChemKit", "SoWx", "flclient.h"):   # ours, taken from the tree
+    ck = os.path.join(out, "inv", n)
+    if not os.path.exists(ck): os.symlink(os.path.join(root, "include/inv", n), ck)
+open(os.path.join(out, "missing.txt"), "w").write("\n".join(missing) + "\n")
+print(len(seen), "inv/ includes,", len(missing), "not in Coin")