hakorune/docs/guides/exe-first-wsl.md

# EXE‑First Quickstart (WSL/Ubuntu)

This guide prioritizes building and running the Nyash parser as a native executable on WSL (Ubuntu). It uses the LLVM harness (llvmlite) and the NyRT static runtime.

Prerequisites
- Rust toolchain (stable): `curl https://sh.rustup.rs -sSf | sh`
- Build tools: `sudo apt update && sudo apt install -y build-essential git python3 python3-pip`
- llvmlite: `pip3 install --user llvmlite`
- LLVM 18 (for `llvm-config-18` used by the Rust build + tools):
  - Ubuntu (with apt.llvm.org):
    - `sudo apt install -y wget gnupg lsb-release`
    - `wget https://apt.llvm.org/llvm.sh && chmod +x llvm.sh && sudo ./llvm.sh 18`
    - This installs `llvm-18` and `llvm-18-dev` (provides `llvm-config-18`).

Verify
- `rustc --version`
- `python3 -c "import llvmlite, sys; print('llvmlite', llvmlite.__version__)"`
- `llvm-config-18 --version`

Build Parser EXE (bundle)
- `tools/build_compiler_exe.sh`
- Result: `dist/nyash_compiler/` containing `nyash_compiler`, `nyash.toml`, and the FileBox plugin.

Smoke (Parser EXE → JSON)
- `echo 'return 1+2*3' > dist/nyash_compiler/tmp/sample.ny`
- `(cd dist/nyash_compiler && ./nyash_compiler tmp/sample.ny > sample.json)`
- `head -n1 dist/nyash_compiler/sample.json` should start with `{` and contain `"kind":"Program"`.

End‑to‑End (JSON → execute via bridge)
- `./tools/exe_first_smoke.sh`
  - Builds the EXE bundle, runs parser → JSON, and executes via the bridge to verify exit code `7`.

MIR Builder (optional, EXE)
- Build: `cargo build --release --features llvm`
- EXE from JSON: `./target/release/ny_mir_builder --in dist/nyash_compiler/sample.json --emit exe -o app_out`
- Run: `./app_out` (exit `7` expected for `return 1+2*3`).

Runner with EXE‑First Parser
- `NYASH_USE_NY_COMPILER=1 NYASH_USE_NY_COMPILER_EXE=1 ./target/release/hakorune --backend vm tmp/sample.hako`
- Smoke: `./tools/exe_first_runner_smoke.sh`

Troubleshooting
- `llvm-config-18: not found`
  - Ensure apt.llvm.org installation worked (see above), or install the distro’s `llvm-18-dev` package.
- `ModuleNotFoundError: llvmlite`
  - `pip3 install --user llvmlite` and re‑run the build/smoke.
- Link errors (`cc` not found or missing libs)
  - `sudo apt install -y build-essential`
  - If you have a custom toolchain, export `CC` to point at your compiler.
- Plugin resolution
  - The EXE bundle includes a minimal `nyash.toml` and plugin paths under `dist/nyash_compiler/plugins/`.

Notes
- The EXE‑first path is the delivery priority. PyVM remains a development aid for semantics parity.
- Windows support is evolving; WSL is the recommended environment for now.