tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
77d4fd72b3674d54a2140e53ed620e183e4f33a1
hakorune/docs/archive/phases/phase-10.11-builtins-to-plugins.md

2.2 KiB
Raw Blame History

Phase 10.11: Builtins → Plugins Migration

Goals

  • Remove builtin Box implementations from execution paths (Interpreter/VM/JIT) to avoid divergence and double sources of truth.
  • Provide all functionality via plugins (BID-FFI v1) and/or user-defined boxes.
  • Keep backward compatibility guarded behind env flags until migration completes.

Rationale

  • Conflicts like ConsoleBox builtin vs plugin cause unexpected behavior.
  • Native build (AOT/EXE) path benefits from uniform plugin boundary.
  • One registry, one implementation per Box: simpler, safer.

Plan (Incremental)

  1. Disable Switch (Now)
  • Add NYASH_DISABLE_BUILTINS=1 to skip registering builtin box factory.
  • Keep off by default; use in CI lanes and targeted tests.
  1. Constructor Delegation (Now → Next)
  • Ensure all constructors go through the unified registry, not direct builtin instantiation.
  • Done: ConsoleBox; Next: remaining non-basic constructors.
  1. Override Policy (Ongoing)
  • Use NYASH_USE_PLUGIN_BUILTINS=1 + NYASH_PLUGIN_OVERRIDE_TYPES to prefer plugins for selected types.
  • Grow the allowlist as plugins become available.
  1. Plugin Coverage (Milestones)
  • ConsoleBox (stdout) — done
  • Array/Map/String/Integer — in place
  • File/Net/Python — in place
  • Math/Time/etc. — add nyash_box.toml and minimal plugins
  1. Remove Builtins (Final)
  • Remove builtin factory or move into separate optional crate for legacy runs.
  • Update docs, examples, and CI to plugin-only.

Acceptance Criteria

  • NYASH_DISABLE_BUILTINS=1 + plugin set → examples run green (VM path).
  • No direct builtins in interpreter constructors (registry only).
  • JIT/AOT compile from MIR uses only plugin invoke shims for Box methods.

How to Test

# Strict plugin preference + disable builtins
export NYASH_USE_PLUGIN_BUILTINS=1
export NYASH_PLUGIN_OVERRIDE_TYPES="ArrayBox,MapBox,ConsoleBox,StringBox,IntegerBox"
export NYASH_DISABLE_BUILTINS=1

cargo build --release --features cranelift-jit
./target/release/nyash --backend vm examples/console_demo.hako

Notes

  • Temporary breakages expected when some builtin-only boxes remain. Use the override allowlist tactically.
  • Keep [libraries] and [plugins] configured to ensure provider discovery.