diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8d38734 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- `ocaml/` contains the OCaml Nock interpreter: core modules in `lib/`, tests in `test/`, benchmarks in `bench_*`, plus pills and scripts for experiments. +- `vere/` hosts the Zig runtime: `pkg/` implements packages such as `noun` and `vere`, `ext/` bundles C dependencies, and `doc/`/`docker/` provide references and tooling. +- Root `flake.nix` defines the shared Nix dev shell; keep repo-level scripts executable and language-agnostic so both stacks can reuse them. + +## Build, Test, and Development Commands +- `nix develop` seeds an environment with OCaml 5.3, Zig 0.14, dune, sqlite, and the tooling pinned in `flake.nix`. +- `dune build` (from `ocaml/`) compiles the interpreter; `dune exec ./test_nock.exe` or `make -C ocaml test` runs the opcode regression tests with logs. +- `make -C ocaml bench` benchmarks the OCaml implementation; capture the output when tuning performance-sensitive code. +- `zig build` (inside `vere/`) produces a debug `urbit`; append `-Doptimize=ReleaseFast` for release-grade binaries or `-Dall` for cross compilation. +- `zig build nock-test ames-test --summary all` exercises the key runtime suites; invoke additional named targets when modifying other packages. + +## Coding Style & Naming Conventions +- OCaml files use two-space indentation, modules in `Camel_case`, values/functions `snake_case`; run `dune fmt --auto-promote` (ocamlformat) before committing. +- Zig sources rely on `zig fmt`; keep functions `lower_snake_case`, types `UpperCamelCase`, and mirror existing spacing in `vere/pkg/*`. +- Bench C helpers under `ocaml/bench_*` should stick to the supplied `gcc` flags and simple `snake_case` utilities. + +## Testing Guidelines +- Extend OCaml coverage under `ocaml/test/`, mirroring the `test_<feature>` functions already in `test_nock.ml`; ensure failures exit non-zero for CI scripts. +- Add Zig tests next to the package being touched (e.g., `vere/pkg/noun/test_*.zig`) and register them in `build.zig` so `zig build <target>` exposes them. +- When altering benchmarks or runtime behavior, include before/after metrics from `make -C ocaml bench` or the relevant `zig build` target. + +## Commit & Pull Request Guidelines +- Commits follow the repository’s short, lowercase subject line pattern (`moar docs`, `iris and dill`); keep them under ~60 characters and expand detail in the body when necessary. +- Name branches `i/<issue>/<topic>` consistent with `vere/CONTRIBUTING.md`; open PRs with `Resolves #<issue>` plus the commands and fake-ship steps used for validation. +- PRs should flag test coverage, benchmark deltas, and pill or configuration updates; attach screenshots only when developer UX changes are visible. + + + +codex resume 0199b79c-dc49-7563-8dc4-bf017dbf45a6 |