|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | +- lib/: Core OCANNL library (tensors, shape inference, ppx helpers). |
| 5 | +- arrayjit/: Optimizing compiler subpackage (low-level backends, lowering). |
| 6 | +- bin/: Executable examples and demos (e.g., `hello_world.ml`, `moons_benchmark.ml`). |
| 7 | +- test/: Expect and inline tests grouped by topic (`einsum/`, `operations/`, `training/`, `ppx/`). |
| 8 | +- docs/: Slides and reference docs; datasets/: helper data; build_files/ and log_files/: generated artifacts. |
| 9 | +- Key config: copy `ocannl_config.example` to `ocannl_config` and adjust backend. |
| 10 | + |
| 11 | +## Build, Test, and Development Commands |
| 12 | +- opam deps: `opam install . --deps-only` (OCaml ≥ 5.3 per `dune-project`). |
| 13 | +- Build: `dune build` or `dune build @all`. |
| 14 | +- Run examples: `dune exec bin/hello_world.exe` (see more in `bin/dune`). |
| 15 | +- Test all: `OCANNL_BACKEND=sync_cc dune runtest` (valid backends include `sync_cc`, `multicore_cc`, `cuda`, `metal`). Tests read `test/config/ocannl_config` and if configured for it, generate files under `build_files/` and `log_files/`. |
| 16 | +- Format: `dune fmt` (uses `.ocamlformat`). |
| 17 | + |
| 18 | +## Coding Style & Naming Conventions |
| 19 | +- OCaml formatting enforced by `.ocamlformat` (margin 100, parse/wrap docstrings). Run `dune fmt` before pushing. |
| 20 | +- Overall preference for snake_case (e.g. files `my_module.ml`); OCaml enforces capitalized modules and constructors (`My_module`, `My_variant`). |
| 21 | +- Prefer small, composable functions; avoid needless global state. PPX usage (`%op`, `%cd`) is described in `lib/syntax_extensions.md`. |
| 22 | + |
| 23 | +## Testing Guidelines |
| 24 | +- Frameworks: `ppx_expect` for inline `%expect` tests, and Dune `test` stanzas for tests with output targets in `.expected` files. Tests live under `test/<area>/*.ml` with paired `*.expected` where applicable. |
| 25 | +- Run subset: `dune runtest test/einsum`. |
| 26 | +- Tests may diff emitted `.ll` (low-level intermediate representation), `.c`, `.cu`, `.metal` files. |
| 27 | + |
| 28 | +## Commit & Pull Request Guidelines |
| 29 | +- Commits: imperative, concise subject; reference issues when relevant (e.g., “Fixes #358: …”). Include scope if helpful (einsum/ops/train). |
| 30 | +- PRs: clear description, linked issues, reproduction or `dune runtest` output, and mention backend(s) exercised. Include any new example commands. |
| 31 | + |
| 32 | +## Configuration & Backends |
| 33 | +- Backend selection and runtime options are read from `ocannl_config` and `OCANNL_BACKEND`. See `ocannl_config.example` for available keys (debug logging, device, precision). |
| 34 | +- For CUDA/Metal specifics and debugging, consult README “Using the tracing debugger” and adjust config accordingly. |
| 35 | + |
0 commit comments