继续把 interp_execute.cc、interp_queue.cc、interp_find.cc 等 LinuxCNC 源文件纳入直接编译/链接路径，逐步删除临时 convert_g() wrapper 行为
结论：已将核心 LinuxCNC interpreter 源接入 standalone native 编译链接路径，移除 minimal runtime 中的手写 convert_g 行为，并通过 native probe 验证。
This commit is contained in:
155
wasm-port/SKILL.md
Normal file
155
wasm-port/SKILL.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user