hakorune/docs/guides/selfhost-pilot.md

Self‑Hosting Pilot — Quick Guide (Phase‑15)

Overview

• Goal: Run Ny→JSON v0 via the selfhost compiler path and execute with PyVM/LLVM.
• Default remains env‑gated for safety; CI runs smokes to build confidence.

Recommended Flows

• Runner (pilot): NYASH_USE_NY_COMPILER=1 ./target/release/nyash --backend vm apps/examples/string_p0.nyash
• Emit‑only: NYASH_USE_NY_COMPILER=1 NYASH_NY_COMPILER_EMIT_ONLY=1 ...
• EXE‑first (parser EXE): tools/build_compiler_exe.sh && NYASH_USE_NY_COMPILER=1 NYASH_USE_NY_COMPILER_EXE=1 ./target/release/nyash --backend vm apps/examples/string_p0.nyash
• LLVM AOT: NYASH_LLVM_USE_HARNESS=1 tools/build_llvm.sh apps/... -o app && ./app

CI Workflows

• Selfhost Bootstrap (always): .github/workflows/selfhost-bootstrap.yml
  • Builds nyash (cranelift-jit) and runs tools/bootstrap_selfhost_smoke.sh.
• Selfhost EXE‑first (optional): .github/workflows/selfhost-exe-first.yml
  • Installs LLVM 18 + llvmlite, then runs tools/exe_first_smoke.sh.

Useful Env Flags

• NYASH_USE_NY_COMPILER=1: Enable selfhost compiler pipeline.
• NYASH_NY_COMPILER_EMIT_ONLY=1: Print JSON v0 only (no execution).
• NYASH_NY_COMPILER_TIMEOUT_MS=4000: Child timeout (ms). Default 2000.
• NYASH_USE_NY_COMPILER_EXE=1: Prefer external parser EXE.
• NYASH_NY_COMPILER_EXE_PATH=<path>: Override EXE path.
• NYASH_SELFHOST_READ_TMP=1: Child reads tmp/ny_parser_input.ny when supported.

Troubleshooting (short)

• No Python found: install python3 (PyVM / harness).
• No llvm-config-18: install LLVM 18 dev (see EXE‑first workflow).
• llvmlite import error: python3 -m pip install llvmlite.
• Parser child timeout: raise NYASH_NY_COMPILER_TIMEOUT_MS.
• EXE‑first bridge mismatch: re‑run with NYASH_CLI_VERBOSE=1 and keep dist/nyash_compiler/sample.json for inspection.

Notes

• JSON v0 schema is stable but not yet versioned; validation is planned.
• Default backend vm maps to PyVM unless legacy VM features are enabled.