11506cee3b
Major changes: - LLVM backend initial implementation (compiler.rs, llvm mode) - Semantics layer integration in interpreter (operators.rs) - Phase 12 plugin architecture revision (3-layer system) - Builtin box removal preparation - MIR instruction set documentation (26→Core-15 migration) - Cross-backend testing infrastructure - Await/nowait syntax support New features: - LLVM AOT compilation support (--backend llvm) - Semantics layer for interpreter→VM flow - Tri-backend smoke tests - Plugin-only registry mode Bug fixes: - Interpreter plugin box arithmetic operations - Branch test returns incorrect values Documentation: - Phase 12 README.md updated with new plugin architecture - Removed obsolete NYIR proposals - Added LLVM test programs documentation Co-Authored-By: Claude <noreply@anthropic.com>
40 lines
2.2 KiB
Markdown
40 lines
2.2 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- `src/`: Nyash core (MIR, backends, runner modes). Key: `backend/`, `runner/`, `mir/`.
|
||
- `crates/nyrt/`: NyRT static runtime for AOT/LLVM (`libnyrt.a`).
|
||
- `plugins/`: First‑party plugins (e.g., `nyash-array-plugin`).
|
||
- `apps/` and `examples/`: Small runnable samples and smokes.
|
||
- `tools/`: Helper scripts (build, smoke).
|
||
- `tests/`: Rust and Nyash tests; historical samples in `tests/archive/`.
|
||
- `nyash.toml`: Box type/plug‑in mapping used by runtime.
|
||
|
||
## Build, Test, and Development Commands
|
||
- Build (JIT/VM): `cargo build --release --features cranelift-jit`
|
||
- Build (LLVM AOT): `LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix) cargo build --release --features llvm`
|
||
- Quick VM run: `./target/release/nyash --backend vm apps/APP/main.nyash`
|
||
- Emit + link (LLVM): `tools/build_llvm.sh apps/APP/main.nyash -o app`
|
||
- Smokes: `./tools/llvm_smoke.sh release` (use env toggles like `NYASH_LLVM_VINVOKE_RET_SMOKE=1`)
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Rust style (rustfmt defaults): 4‑space indent, `snake_case` for functions/vars, `CamelCase` for types.
|
||
- Keep patches focused; align with existing modules and file layout.
|
||
- New public APIs: document minimal usage and expected ABI (if exposed to NyRT/plug‑ins).
|
||
|
||
## Testing Guidelines
|
||
- Rust tests: `cargo test` (add targeted unit tests near code).
|
||
- Smoke scripts validate end‑to‑end AOT/JIT (`tools/llvm_smoke.sh`).
|
||
- Test naming: prefer `*_test.rs` for Rust and descriptive `.nyash` files under `apps/` or `tests/`.
|
||
- For LLVM tests, ensure LLVM 18 is installed and set `LLVM_SYS_180_PREFIX`.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Commits: concise imperative subject; scope the change (e.g., "llvm: fix argc handling in nyrt").
|
||
- PRs must include: description, rationale, reproduction (if bug), and run instructions.
|
||
- Link issues (`docs/issues/*.md`) and reference affected scripts (e.g., `tools/llvm_smoke.sh`).
|
||
- CI: ensure smokes pass; use env toggles in the workflow as needed.
|
||
|
||
## Security & Configuration Tips
|
||
- Do not commit secrets. Plug‑in paths and native libs are configured via `nyash.toml`.
|
||
- LLVM builds require system LLVM 18; install via apt.llvm.org in CI.
|
||
- Optional logs: enable `NYASH_CLI_VERBOSE=1` for detailed emit diagnostics.
|