wasm-simulator/docs/linuxcnc-rs274-source-map.md

# LinuxCNC rs274 source map

This is the working map for moving from native `librs274` linking to source-level compilation and then to wasm.

## Compile assumptions

Native user-space syntax checks require:

- `-DULAPI`
- LinuxCNC include roots:
  - `linuxcnc/src`
  - `linuxcnc/src/emc`
  - `linuxcnc/src/emc/nml_intf`
  - `linuxcnc/src/emc/rs274ngc`
  - `linuxcnc/src/emc/motion`
  - `linuxcnc/src/emc/pythonplugin`
  - `linuxcnc/include`
- Python development headers for current upstream sources, because the interpreter still embeds Python/Boost.Python paths.

## Source groups

### Interpreter core

These are the first group to keep compiling while we peel away native-only dependencies:

- `interp_arc.cc`
- `interp_array.cc`
- `interp_base.cc`
- `interp_check.cc`
- `interp_convert.cc`
- `interp_cycles.cc`
- `interp_execute.cc`
- `interp_find.cc`
- `interp_g7x.cc`
- `interp_inspection.cc`
- `interp_internal.cc`
- `interp_inverse.cc`
- `interp_namedparams.cc`
- `interp_o_word.cc`
- `interp_python.cc`
- `interp_queue.cc`
- `interp_read.cc`
- `interp_remap.cc`
- `interp_setup.cc`
- `interp_write.cc`
- `modal_state.cc`
- `nurbs_additional_functions.cc`
- `rs274ngc_pre.cc`

### Python binding modules

These are not needed for the browser simulator ABI and should not be part of the wasm core:

- `canonmodule.cc`
- `gcodemodule.cc`
- `interpmodule.cc`
- `pyarrays.cc`
- `pyblock.cc`
- `pyemctypes.cc`
- `pyinterp1.cc`
- `pyparamclass.cc`

### WASM-safe source core

These are the LinuxCNC source files compiled by the browser-safe source-link
probes from `linuxcnc-rs274-wasm-source-files.txt`:

- `src/emc/rs274ngc/interp_arc.cc`
- `src/emc/rs274ngc/interp_array.cc`
- `src/emc/rs274ngc/interp_base.cc`
- `src/emc/rs274ngc/interp_check.cc`
- `src/emc/rs274ngc/interp_convert.cc`
- `src/emc/rs274ngc/interp_cycles.cc`
- `src/emc/rs274ngc/interp_execute.cc`
- `src/emc/rs274ngc/interp_find.cc`
- `src/emc/rs274ngc/interp_g7x.cc`
- `src/emc/rs274ngc/interp_inspection.cc`
- `src/emc/rs274ngc/interp_internal.cc`
- `src/emc/rs274ngc/interp_inverse.cc`
- `src/emc/rs274ngc/interp_queue.cc`
- `src/emc/rs274ngc/interp_read.cc`
- `src/emc/rs274ngc/interp_setup.cc`
- `src/emc/rs274ngc/interp_write.cc`
- `src/emc/rs274ngc/modal_state.cc`
- `src/emc/rs274ngc/nurbs_additional_functions.cc`
- `src/emc/rs274ngc/interp_namedparams.cc`
- `src/emc/rs274ngc/interp_o_word.cc`
- `src/emc/rs274ngc/interp_python.cc`
- `src/emc/rs274ngc/interp_remap.cc`
- `src/emc/rs274ngc/rs274ngc_pre.cc`
- `src/emc/tooldata/tooldata_common.cc`
- `src/emc/ini/inifile.cc`
- `src/emc/nml_intf/emcops.cc`

### WASM-blocked sources

These LinuxCNC sources remain tracked in the wasm manifest, but are not part of
the browser-safe core until their Python/Boost.Python or native storage
dependencies are replaced:

- `src/emc/tooldata/tooldata_mmap.cc`
- `src/emc/rs274ngc/canonmodule.cc`
- `src/emc/rs274ngc/gcodemodule.cc`
- `src/emc/rs274ngc/interpmodule.cc`
- `src/emc/rs274ngc/pyarrays.cc`
- `src/emc/rs274ngc/pyblock.cc`
- `src/emc/rs274ngc/pyemctypes.cc`
- `src/emc/rs274ngc/pyinterp1.cc`
- `src/emc/rs274ngc/pyparamclass.cc`

### WASM-tracked headers

These LinuxCNC headers are tracked by the wasm manifest because the
browser-safe source-link probes compile against them or shim their declarations:

- `src/emc/rs274ngc/array1.hh`
- `src/emc/rs274ngc/interp_array_types.hh`
- `src/emc/rs274ngc/interp_base.hh`
- `src/emc/rs274ngc/interp_fwd.hh`
- `src/emc/rs274ngc/interp_inspection.hh`
- `src/emc/rs274ngc/interp_internal.hh`
- `src/emc/rs274ngc/interp_parameter_def.hh`
- `src/emc/rs274ngc/interp_python.hh`
- `src/emc/rs274ngc/interp_queue.hh`
- `src/emc/rs274ngc/modal_state.hh`
- `src/emc/rs274ngc/paramclass.hh`
- `src/emc/rs274ngc/rs274ngc.hh`
- `src/emc/rs274ngc/rs274ngc_interp.hh`
- `src/emc/rs274ngc/rs274ngc_return.hh`
- `src/emc/rs274ngc/units.h`
- `src/emc/pythonplugin/python_plugin.hh`
- `src/emc/ini/inifile.h`
- `src/emc/ini/inifile.hh`
- `src/emc/nml_intf/emc.hh`
- `src/emc/nml_intf/emc_nml.hh`
- `include/hal.h`
- `src/libnml/nml/nmlmsg.hh`
- `src/libnml/nml/stat_msg.hh`
- `src/libnml/rcs/rcs_print.hh`
- `src/rtapi/rtapi.h`
- `src/rtapi/rtapi_string.h`

### WASM-blocked headers

These headers are tracked for source coverage but should not become browser API
surface until their Boost.Python dependency is replaced:

- `src/emc/rs274ngc/boost_pyenum_macros.hh`

### WASM metadata sources

These LinuxCNC source and build metadata files document the source basis for
the browser-safe shims and manifest completeness checks:

- `src/emc/rs274ngc/Submakefile`
- `src/emc/rs274ngc/meson.build`
- `src/emc/pythonplugin/python_plugin.cc`
- `src/emc/task/emctaskmain.cc`
- `src/emc/task/taskclass.cc`
- `src/emc/task/emccanon.cc`
- `src/emc/sai/dummyemcstat.cc`
- `src/emc/ini/Submakefile`
- `src/libnml/nml/stat_msg.cc`
- `src/libnml/nml/nmlmsg.cc`
- `src/libnml/rcs/rcs_print.cc`
- `src/rtapi/uspace_common.h`
- `src/hal/hal_lib.c`
- `src/emc/tooldata/tooldata_db.cc`
- `src/emc/tooldata/tooldata_nml.cc`

### Browser-hostile dependencies to replace

- Python/Boost.Python remap and named parameter hooks.
- `dlopen`/`dlsym` interpreter loading in `interp_base.cc`.
- native mmap/filesystem storage in `tooldata_mmap.cc`.
- persistent parameter file writes.
- dynamic INI/HAL queries.

The wasm-safe runtime now constructs its detached `EMC_STAT` through LinuxCNC
`src/emc/nml_intf/emcops.cc`. The singleton follows LinuxCNC
`src/emc/sai/dummyemcstat.cc`, and the required `NMLmsg`/`RCS_STAT_MSG`
constructors are trimmed from `src/libnml/nml/nmlmsg.cc` and
`src/libnml/nml/stat_msg.cc` in `core/wasm_shims/nml_status_shim.cc`, so
interpreter paths such as `Interp::tag_arc()` in `interp_convert.cc` read
initialized LinuxCNC status defaults without linking the task controller or
native NML channels.

## Current syntax probe

Run:

```bash
./test-linuxcnc-source-syntax.sh
```

The probe checks a representative subset of source files with `-DULAPI`. It is not a full source build yet; it is a guardrail before the full source backend is introduced.

## Current object probe

Run:

```bash
./test-linuxcnc-source-objects.sh
```

This compiles every `core:` entry in `linuxcnc-rs274-source-files.txt` into object files. As of this step, the core interpreter sources compile to `.o` in the native environment with `-DULAPI`.

The next boundary is linking. Expected link risks:

- `PythonPlugin` and Boost.Python symbols from remap/named parameter paths.
- Python module initialization symbols if the source backend reuses the existing builtin module setup.
- `tooldata_mmap.cc` native mmap/filesystem storage. `tooldata_common.cc` now
  remains in the wasm-safe core and links against browser-safe tooldata backend
  shims.
- dynamic loader code in `interp_base.cc`.
- parameter file persistence in `rs274ngc_pre.cc`.

## Current source-link probe

Run:

```bash
./test-linuxcnc-source-link.sh
```

This compiles every `core:` interpreter source into local objects and links the
native runner without `librs274`. It still uses built LinuxCNC support objects
and libraries for the dependencies that have not been replaced yet:

- Boost.Python binding module initializers required by the current interpreter constructor.
- `libpyplugin` for Python remap and named-parameter hooks.
- `liblinuxcncini` and `liblinuxcnchal` for INI/HAL named parameter paths.
- `liblinuxcnc-uspace-posix` for `rtapi_*` user-space helpers.
- `libtooldata` for the native source-link runner. The wasm-safe source probes
  instead compile LinuxCNC `tooldata_common.cc` with `tooldata_mmap_backend.cc`
  and `tooldata_runtime_stubs.cc`.

This is not wasm-ready yet, but it proves the simulator can own and compile the
RS274 interpreter core sources directly. The next source-port boundary is to
replace each support dependency with browser-safe shims instead of pulling in
the LinuxCNC task, motion, HAL, and Python runtime layers.

The wasm-safe source manifest is `linuxcnc-rs274-wasm-source-files.txt`. The
`rs274ngc_pre` wasm link and undefined-symbol probes read their LinuxCNC source
list from that manifest so `inifile.cc`, `tooldata_common.cc`, and the
interpreter sources stay on one source of truth.

When `CNC_SIM_ENABLE_LINUXCNC_WASM_SAFE_PROBE=ON`, CMake also exposes
`linuxcnc_rs274_wasm_safe_probe_objects` and the `EXCLUDE_FROM_ALL`
`linuxcnc_rs274_wasm_safe_probe` executable. The executable mirrors the
`rs274ngc_pre` shell link probe and is built only when explicitly requested, so
the normal browser wasm artifact does not accidentally link the probe runtime.

The native runner used by this probe now recognizes simulator-owned control
lines before handing code to LinuxCNC: `M428`, `M429`, `M430`, `G43.4`,
`G43.5`, and `G49`. This keeps the direct runner aligned with the public
`linuxcnc-rs274` API backend for RTCP and kinematics switch tests.