69 lines
3.7 KiB
Markdown
69 lines
3.7 KiB
Markdown
# LinuxCNC OPFS source map
|
|
|
|
This map records the source basis for browser-side LinuxCNC parameter-file
|
|
persistence. It is a policy and bridge map only; it must not add independent filesystem behavior or expand the temporary smoke parser.
|
|
|
|
## LinuxCNC Source Basis
|
|
|
|
- `src/emc/rs274ngc/interp_internal.hh` defines
|
|
`RS274NGC_PARAMETER_FILE_NAME_DEFAULT` as `rs274ngc.var`.
|
|
- `src/emc/rs274ngc/interp_internal.hh` defines
|
|
`RS274NGC_PARAMETER_FILE_BACKUP_SUFFIX` as `.bak`.
|
|
- `src/emc/rs274ngc/rs274ngc_pre.cc` implements
|
|
`Interp::restore_parameters()` for parameter-file reads.
|
|
- `src/emc/rs274ngc/rs274ngc_pre.cc` implements
|
|
`Interp::save_parameters()` for `filename + ".new"`, backup, and replacement
|
|
writes.
|
|
- `src/emc/rs274ngc/rs274ngc_pre.cc` unlinks `filename + ".bak"`, links the
|
|
previous parameter file to that backup path, then renames `filename + ".new"`
|
|
over the configured parameter file.
|
|
|
|
## OPFS Coverage
|
|
|
|
| Entry | Boundary |
|
|
| --- | --- |
|
|
| `web/src/wasm-core.js` | Keeps LinuxCNC parameter restore/save bridge files under the OPFS workspace and cleans WASM scratch files. |
|
|
| `web/src/wasm-core.d.ts` | Exposes only the OPFS-backed workspace, directory, parameter-file, and mount/workspace option types used by the bridge. |
|
|
| `web/src/app.js` | Persists browser programs at `programs/current.ngc` and LinuxCNC parameters at `parameters/rs274ngc.var`. |
|
|
| `web/test-browser-wasm-smoke-opfs-basic-sections.js` | Verifies OPFS program file reads through LinuxCNC `read_text()` and rejects unsafe paths. |
|
|
| `web/test-browser-wasm-smoke-opfs-parameter-sections.js` | Verifies OPFS parameter restore, save, `.new`, `.bak`, failure, and stale-state semantics. |
|
|
| `web/test-browser-wasm-smoke-opfs-workspace-sections.js` | Aggregates OPFS basic, parameter, mirror, and directory checks under browser OPFS availability. |
|
|
| `web/test-browser-wasm-smoke-opfs-mirror-sections.js` | Verifies OPFS/WASM mirror persistence used by source-backed file parsing and parameter movement. |
|
|
| `web/test-browser-wasm-smoke-opfs-directory-sections.js` | Verifies OPFS directory persistence and WASM mirror refresh without polluting mirrors during metadata queries. |
|
|
| `web/test-browser-wasm-smoke-opfs-policy-sections.js` | Verifies OPFS workspace and mount policy, including the browser rule that OPFS cannot be disabled. |
|
|
| `web/test-browser-wasm-smoke-app-sections.js` | Verifies app-level OPFS program, parameter, backup, and reload behavior. |
|
|
|
|
## Browser Bridge Boundary
|
|
|
|
- `web/src/wasm-core.js` must keep LinuxCNC parameter persistence routed
|
|
through an OPFS workspace.
|
|
- Browser contexts with OPFS support must not disable OPFS.
|
|
- OPFS workspace paths must remain relative paths inside the CNC workspace, and
|
|
OPFS mount points must remain absolute paths inside the Emscripten
|
|
filesystem.
|
|
- Browser app and wasm bridge code must not use Local Storage, IndexedDB,
|
|
File Picker, Directory Picker, WebKit filesystem, or FileReader persistence
|
|
paths for CNC programs, LinuxCNC parameter files, or mirrored workspace files.
|
|
- `web/src/app.js` must parse browser programs through
|
|
`parseFileWithParameterFile()` so the program file and LinuxCNC parameter
|
|
state both live under OPFS.
|
|
- `test-native.sh`, `test-linuxcnc-source-link.sh`, and `build-wasm.sh` must
|
|
run `./check-linuxcnc-opfs-source-map.sh` before consuming app-backed browser
|
|
artifacts or source-linked LinuxCNC objects.
|
|
- The OPFS source-map guard validates LinuxCNC source-backed filesystem bridge
|
|
policy only; it does not interpret G-code.
|
|
|
|
## Checks
|
|
|
|
Run:
|
|
|
|
```bash
|
|
./check-linuxcnc-opfs-source-map.sh
|
|
./test-native.sh
|
|
./test-linuxcnc-source-link.sh
|
|
./build-wasm.sh
|
|
```
|
|
|
|
`check-linuxcnc-opfs-source-map.sh` keeps this document, the LinuxCNC source
|
|
anchors, and the browser bridge guardrails synchronized.
|