wangdequan
5025b0c1a1
结论：已将核心 LinuxCNC interpreter 源接入 standalone native 编译链接路径，移除 minimal runtime 中的手写 convert_g 行为，并通过 native probe 验证。
156 lines
4.3 KiB
Markdown
156 lines
4.3 KiB
Markdown
# SKILL.md
|
|
|
|
## Skill Name
|
|
|
|
LinuxCNC WASM Simulation Port
|
|
|
|
## Purpose
|
|
|
|
This skill guides work inside `wasm-port/` for building a standalone
|
|
LinuxCNC-based CNC simulation program.
|
|
|
|
It is intended for tasks involving:
|
|
|
|
- source extraction from upstream LinuxCNC;
|
|
- vendoring and patching selected LinuxCNC modules;
|
|
- wrapping LinuxCNC compute code for native and WASM use;
|
|
- preserving interpreter, planner, kinematics, HAL-visible, and INI-visible
|
|
semantics;
|
|
- building HTML + JavaScript + OPFS frontend integration.
|
|
|
|
## When To Use
|
|
|
|
Use this skill when the work involves any of the following:
|
|
|
|
- deciding whether to reuse or reimplement LinuxCNC code;
|
|
- mapping CNC features to LinuxCNC source files;
|
|
- creating or updating extraction scripts under `tools/`;
|
|
- defining standalone runtime structure under `runtime/core/`;
|
|
- building browser-facing WASM APIs;
|
|
- integrating OPFS-backed configuration and session persistence;
|
|
- validating LinuxCNC-equivalent simulation behavior.
|
|
|
|
## Core Principles
|
|
|
|
1. Upstream LinuxCNC is the semantic source of truth.
|
|
2. The standalone port is a separate program and separate workspace.
|
|
3. Reuse comes before rewrite.
|
|
4. Native runtime dependencies are replaced at the edges, not copied whole.
|
|
5. Machine state and controller-visible behavior are first-class compatibility
|
|
targets, not optional nice-to-haves.
|
|
6. Do not continue building a project-authored CNC program once the porting
|
|
harness runs; move behavior back to vendored LinuxCNC source functions.
|
|
|
|
## Source Reuse Priorities
|
|
|
|
Highest-priority source reuse targets:
|
|
|
|
- `src/emc/rs274ngc`
|
|
- `src/emc/tp`
|
|
- `src/emc/kinematics`
|
|
- `src/libnml/posemath`
|
|
- `src/emc/ini`
|
|
|
|
Secondary semantic references:
|
|
|
|
- `src/hal/hal.h`
|
|
- `src/hal/halmodule.cc`
|
|
- `src/emc/ini/inihal.cc`
|
|
|
|
Reference-only UI sources:
|
|
|
|
- `src/emc/usr_intf/axis`
|
|
- `src/hal/user_comps/vismach`
|
|
- `configs/sim/axis/vismach/5axis`
|
|
|
|
## Required Port Boundaries
|
|
|
|
The port should preserve or expose these LinuxCNC behaviors:
|
|
|
|
- G-code parsing and execution
|
|
- canonical motion generation
|
|
- parameter file semantics
|
|
- named variable lookup semantics
|
|
- `_ini[...]` lookup semantics
|
|
- `_hal[...]` lookup semantics through simulation adapter
|
|
- planner behavior
|
|
- 3-axis through 5-axis kinematics
|
|
- machine/controller state visible to software
|
|
|
|
The port should replace these native dependencies:
|
|
|
|
- Linux process orchestration
|
|
- NML transport implementation
|
|
- HAL runtime internals
|
|
- realtime scheduling
|
|
- native GUI implementation
|
|
- native filesystem assumptions
|
|
|
|
## Implementation Pattern
|
|
|
|
Preferred order of work:
|
|
|
|
1. Identify upstream file owners for the feature.
|
|
2. Extract files into `vendor/linuxcnc/`.
|
|
3. Add wrappers or shims in `runtime/core/`.
|
|
4. Apply minimal patches only to vendored copies if needed.
|
|
5. Build a native standalone harness first.
|
|
6. Build the WASM export layer second.
|
|
7. Build the JS SDK and HTML frontend last.
|
|
|
|
Current migration emphasis:
|
|
|
|
- Treat `linuxcnc_interp_minimal_runtime.cpp` as a temporary probe surface.
|
|
- Retire hand-written `convert_g()` behavior by linking and calling vendored
|
|
LinuxCNC interpreter conversion code.
|
|
- Add shims only for host/runtime edges that prevent vendored LinuxCNC source
|
|
from compiling.
|
|
- Do not add new G-code behavior in JavaScript or in standalone C++ wrappers
|
|
except as a short-lived adapter around LinuxCNC code.
|
|
|
|
## Filesystem And Browser Guidance
|
|
|
|
For browser use:
|
|
|
|
- WASM core should not directly own OPFS logic.
|
|
- JavaScript host should own OPFS and file management.
|
|
- WASM core should operate on abstract file services or explicit byte blobs.
|
|
|
|
Recommended browser storage targets:
|
|
|
|
- INI files
|
|
- tool tables
|
|
- parameter files
|
|
- G-code programs
|
|
- preview caches
|
|
- session snapshots
|
|
|
|
## Validation Pattern
|
|
|
|
For each migrated feature, validate in this order:
|
|
|
|
1. Upstream LinuxCNC behavior
|
|
2. Standalone native extracted-core behavior
|
|
3. WASM behavior in Node or CLI harness
|
|
4. Browser behavior through the frontend
|
|
|
|
Always record:
|
|
|
|
- source origin
|
|
- any shim introduced
|
|
- any vendored patch introduced
|
|
- known deviations from upstream behavior
|
|
|
|
## Deliverable Bias
|
|
|
|
Prefer deliverables that directly improve execution readiness:
|
|
|
|
- source reuse maps
|
|
- extraction scripts
|
|
- standalone runtime wrappers
|
|
- regression fixtures
|
|
- drift reports
|
|
|
|
Prefer not to spend time on speculative abstractions unless they reduce
|
|
real migration complexity.
|