125 lines
6.7 KiB
Markdown
125 lines
6.7 KiB
Markdown
# LinuxCNC Source Policy
|
|
|
|
The simulator must not grow independently designed functional behavior.
|
|
Functional behavior must come from LinuxCNC source code.
|
|
|
|
Hard rules:
|
|
|
|
- Port-first: prefer direct LinuxCNC source porting, trimming, wrapping, or
|
|
platform adaptation over project-authored replacements.
|
|
- Do not write project-owned functional CNC behavior.
|
|
- Functional CNC behavior must be ported, trimmed, wrapped, or routed from
|
|
LinuxCNC source code.
|
|
- Any G/M-code interpretation, motion behavior, kinematics, coordinate
|
|
handling, cutter compensation, canned cycle, parameter expression, modal
|
|
state, tool data, remap behavior, or RTCP behavior must first be traced to
|
|
LinuxCNC source before implementation.
|
|
- Browser-side wasm filesystem behavior must use OPFS-backed storage. Do not
|
|
add browser filesystem paths that bypass OPFS.
|
|
|
|
Allowed project code:
|
|
|
|
- LinuxCNC source porting, trimming, wrappers, and platform adaptation.
|
|
- Thin adapters between LinuxCNC source code and the simulator C API.
|
|
- Platform shims needed to compile LinuxCNC code for native tests or wasm.
|
|
- Event serialization, test fixtures, build scripts, and documentation.
|
|
- Temporary smoke scaffolding only when it is explicitly marked as temporary.
|
|
|
|
Not allowed as final behavior:
|
|
|
|
- Hand-written G-code interpretation semantics.
|
|
- Hand-derived kinematics, RTCP, coordinate transform, cutter compensation, canned cycle, modal, parameter, or expression behavior.
|
|
- Behavior copied from documentation, controller intuition, or examples without checking the LinuxCNC implementation.
|
|
|
|
Required workflow for every functional change:
|
|
|
|
1. Identify the LinuxCNC source file and function that defines the behavior.
|
|
2. Add or update a test that demonstrates the LinuxCNC behavior.
|
|
3. Port, wrap, or route to that LinuxCNC implementation.
|
|
4. Record the source file/function in code comments or nearby documentation when the mapping is not obvious.
|
|
5. Keep the change inside one active workstream context unless a dependency is
|
|
unavoidable and explicitly named in the final report.
|
|
6. Run `./test-native.sh` and `./test-linuxcnc-source-link.sh`.
|
|
7. For source-manifest, build, or build-policy changes, also run the aggregate
|
|
and guardrail checks: `./test-all-native.sh`,
|
|
`./test-linuxcnc-source-syntax.sh`, and
|
|
`./test-linuxcnc-wasm-cmake-safe-probe.sh`.
|
|
|
|
Efficiency rules:
|
|
|
|
- Do not add a smoke-only behavior path when the LinuxCNC-backed route already
|
|
exists; add coverage to the source-backed route instead.
|
|
- Do not mix generator/table work, manifests, OPFS/browser work, and build
|
|
policy cleanup in the same pass unless the files directly depend on each
|
|
other.
|
|
- Prefer tightening an existing probe or manifest over adding another broad
|
|
end-to-end smoke case.
|
|
- Default native, source-link, build-wasm, and wasm-safe CMake probe
|
|
parallelism to `CNC_SIM_BUILD_JOBS:-8`; raise it only by explicit
|
|
positive-integer environment override.
|
|
- When `ccache` is available and `CXX` is unset, native and wasm build paths
|
|
should enable compiler caching automatically rather than requiring a manual
|
|
wrapper.
|
|
- Persistent native, source-link, and wasm-safe CMake probe build directories
|
|
may be overridden for local workflows, but must not point at the filesystem
|
|
root.
|
|
- Build policy knobs are intentionally narrow:
|
|
`CNC_SIM_BUILD_JOBS`, `CNC_SIM_NATIVE_BUILD_DIR`,
|
|
`CNC_SIM_SOURCE_LINK_BUILD_DIR`, `CNC_SIM_SOURCE_SYNTAX_BUILD_DIR`, and
|
|
`CNC_SIM_WASM_CMAKE_SAFE_PROBE_BUILD_DIR`. Build directory overrides must
|
|
stay non-empty, whitespace-free, and outside the filesystem root.
|
|
- `build-wasm.sh` keeps fixed artifact paths: CMake writes `build/wasm`, then
|
|
the script copies and byte-compares `cnc_sim.js` and `cnc_sim.wasm` under
|
|
`web/public` before running Node and browser smoke checks.
|
|
|
|
Build and source-link guardrails:
|
|
|
|
- `CNC_SIM_BUILD_JOBS` must be a positive integer and defaults to `8`.
|
|
- `test-native.sh` uses persistent `build/native-test` objects, dependency
|
|
files, and `native-build.signature`.
|
|
- `test-linuxcnc-source-link.sh` uses persistent `build/source-link-test`
|
|
objects, dependency files, and `source-link-build.signature`.
|
|
- `test-linuxcnc-source-syntax.sh` uses persistent
|
|
`build/source-syntax-test` stamps, dependency files, and
|
|
`source-syntax.signature`.
|
|
- `test-linuxcnc-wasm-cmake-safe-probe.sh` uses persistent
|
|
`build/wasm-cmake-safe-probe` and `wasm-cmake-safe-probe.signature`.
|
|
- Native, source-link, source-syntax, wasm-safe CMake probe, and build-wasm
|
|
paths must reject empty, whitespace-containing, or filesystem-root build
|
|
directory overrides before doing destructive cleanup.
|
|
- Native, source-link, source-syntax, and build-wasm entry points must serialize
|
|
shared non-concurrency-safe paths with lock files before writing fixed
|
|
outputs.
|
|
- Source-link and syntax probes must build from generated makefiles with
|
|
`-MMD -MP` dependency tracking and `make --output-sync=target`.
|
|
- `build-wasm.sh` must run blocker, syntax, object, CMake, tooldata,
|
|
`interp_*`, Python, `rs274ngc_pre`, and runtime link probes before copying
|
|
browser artifacts.
|
|
- `build-wasm.sh` must check `cmake`, `emcmake`, `emcc`, and `node` before the
|
|
Emscripten configure step.
|
|
- `build-wasm.sh` must build `cnc_sim_wasm_runtime_probe` before
|
|
`cnc_sim_wasm`.
|
|
- `build-wasm.sh` must copy `build/wasm/cnc_sim.js` and
|
|
`build/wasm/cnc_sim.wasm` exactly once each.
|
|
- `build-wasm.sh` must compare copied artifacts with `cmp -s` before running
|
|
Node or browser smoke tests.
|
|
- `build-wasm.sh` must run the Node smoke before the browser smoke.
|
|
- The default wasm manifest partition must remain explicitly checked for 25
|
|
wasm-safe core sources and 9 blocked sources.
|
|
- Manifest source listers must reject malformed lines, absolute source paths,
|
|
unknown groups, unknown filters, and duplicate source entries.
|
|
- Native link flags must include the built LinuxCNC `lib` path and rpath.
|
|
- Common CXX flag helpers must surface helper failures instead of hiding them
|
|
behind process substitution or `read`.
|
|
- Temporary probe reports must be cleaned on failure and preserved only after a
|
|
successful report path explicitly opts in.
|
|
- Documentation-only build policy edits should still update the guardrail
|
|
checks that enforce the relevant script and artifact ordering.
|
|
|
|
Current temporary exceptions:
|
|
|
|
- The smoke parser exists only to exercise the public API and UI around remaining fallback paths; native, source-linked, and wasm smoke coverage now route LinuxCNC RS274 behavior through the LinuxCNC-backed interpreter.
|
|
- RTCP pivot behavior is limited to LinuxCNC source-backed switchkins paths; unsupported switchkins types must not fall back to hand-derived geometry.
|
|
|
|
Both exceptions should shrink over time. New functional behavior should not be added to them unless it is directly copied from, or routed to, LinuxCNC source code.
|