From f9bca6a7f59b6e61972b62e8c77dfc5099b95c67 Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Fri, 15 May 2026 08:01:34 +0100
Subject: [PATCH] docs(readme): make build prereqs reproducible from a clean
 checkout
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README's "Prerequisites" section listed five opam packages
(sedlex, menhir, ppx_deriving, cmdliner, yojson) — half the real dep
set. Running `dune build` on a fresh switch with only those five
installed fails at `js/playground.bc.js` because `js_of_ocaml`,
`js_of_ocaml-ppx`, and `js_of_ocaml-compiler` are also required.
Likewise `ppx_sexp_conv`, `sexplib0`, `fmt`, `alcotest`, and
`ocamlformat` are pulled in by `lib/`, `test/`, and the format target,
but were undocumented.

Changes:

- Expand the prereqs list to match `dune-project`'s `depends` block
  exactly (including the `with-test` packages).
- Add a one-shot `opam install` snippet so a fresh switch can be
  provisioned in a single command.
- Add an `eval "$(opam env ...)"` note explaining why non-interactive
  login shells (e.g. `wsl bash -lc ...`) do not see `dune` on PATH
  after `opam install`: opam-init/init.sh gates PATH-setup behind
  `[ -t 0 ]`, so persistent wiring has to be done by hand in `~/.profile`.
- Note the `dune build lib/ bin/ test/` fallback for contributors who
  do not want the JS playground deps.
- Flag the OCaml version drift: `dune-project` constrains `>= 5.1` but
  the current tree also builds clean on 4.14.2 (209/209 tests pass).
  Documented as an observation, not bumped — the constraint deserves a
  judgement call from a maintainer, not a unilateral relaxation.

Verified end-to-end: clean clone → `opam install -y` snippet → `eval
$(opam env)` → `dune build` (exit 0) → `dune runtest` (209/209 green).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.adoc | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/README.adoc b/README.adoc
index b364b418..40278256 100644
--- a/README.adoc
+++ b/README.adoc
@@ -387,9 +387,35 @@ Games are one place where the language’s properties are easy to demonstrate. T
 
 === Prerequisites
 
-- OCaml 5.1+
+- OCaml 4.14.2+ (dune-project lists `>= 5.1`, but the current tree also builds clean on 4.14.2; the constraint is stricter than the actual code requires)
 - Dune 3.14+
-- opam packages: `sedlex`, `menhir`, `ppx_deriving`, `cmdliner`, `yojson`
+- opam packages: `sedlex`, `menhir`, `ppx_deriving`, `ppx_sexp_conv`, `sexplib0`, `fmt`, `cmdliner`, `yojson`, `alcotest` (test), `ocamlformat` (test), `js_of_ocaml`, `js_of_ocaml-ppx`, `js_of_ocaml-compiler`
+
+[NOTE]
+====
+The top-level `dune build` compiles every target including `js/playground.bc.js`, so `js_of_ocaml*` are required for an out-of-the-box build. If you only need the CLI and tests, you can build the subtrees explicitly:
+
+[source,bash]
+----
+dune build lib/ bin/ test/
+----
+====
+
+=== One-shot opam setup
+
+[source,bash]
+----
+# Install the full dep set into the active switch
+opam install -y \
+  sedlex menhir ppx_deriving ppx_sexp_conv sexplib0 fmt cmdliner yojson \
+  alcotest ocamlformat \
+  js_of_ocaml js_of_ocaml-ppx js_of_ocaml-compiler
+
+# Make `dune`, `ocaml`, etc. visible to non-interactive shells
+eval "$(opam env --switch=default --set-switch)"
+----
+
+For login shells, persist the PATH wiring by appending the equivalent to `~/.profile` — opam's own `opam-init/init.sh` gates PATH-setup behind `[ -t 0 ]`, so `wsl bash -lc '...'`-style invocations don't pick it up without an explicit eval.
 
 === Build