Skip to content

development.md

Latest commit

 

History

History
103 lines (77 loc) · 4.66 KB

development.md

File metadata and controls

103 lines (77 loc) · 4.66 KB
Raw

Development

Build and validate httpkit from a repository checkout. For usage, start with the README and new-application guide. The documentation index separates usage, validation and historical plans.

Toolchain and dependencies

Install mise, a C build toolchain and Git. The pinned chain is mise → opam 2.5.2 → Dune 3.24.1 → OCaml 5.5.0 and the locked project dependencies. Setup uses local switches/caches and leaves global opam switches and shell profiles unchanged.

mise trust
mise install opam
mise run setup
tools/harness doctor
mise run test

Only OCaml 5.5.0 is supported. Dependencies are declared in dune-project; the .opam files are generated. dune.lock/ records the compiler/dependency solution, source checksums, and platform-specific actions for Linux and macOS on x86_64 and arm64. Keep it in version control. httpkit-harness owns test and documentation dependencies; production packages have separate dependency closures.

mise trust approves this repository's tool/task configuration. The opam switch's OCaml compiler exists only to build Dune; the Dune lock selects OCaml 5.5.0 for httpkit. CI follows the same mise → opam → Dune setup.

The workspace explicitly enables package management. Regular setup and CI consume the existing lock; they never refresh dependency versions. The wrapper rejects a missing lock rather than silently resolving a new one. To deliberately update dependencies, edit dune-project (or the repository revision in the workspace files), then run:

tools/dune-pkg pkg lock
tools/dune-pkg pkg validate-lockdir
tools/dune-pkg build @opam --auto-promote

Review the lock diffs and rerun the compiler validation and fuzz smoke. The wrapper selects Dune 3.24.1, a project-local cache, and the workspace/build directory. With that version installed, plain dune build also uses the default lock. See Dune's locking documentation.

The workspace pins both opam-repository and Dune's official compatibility overlay. The normal and coverage locks select ocamlfind.1.9.8+dune, whose relocatable configuration avoids temporary sandbox paths in Topkg builds. This is a solver constraint; generated lock files are never patched by hand.

Dune 3.24.1's standalone pkg validate-lockdir rejects the coverage lock's selected optional Bisect packages as unused. Its dependency-closure validation does not include the workspace-selected depopts; enabling instrumentation on that command does not fix it. The instrumented build succeeds with the existing lock. Preserve this diagnostic, validate the regular lock normally, and use the instrumented build and coverage runs for coverage-workspace evidence. Do not remove Bisect or regenerate the lock merely to silence this validator limitation.

Everyday commands

Run commands from the repository root:

mise run test
mise run docs
mise run bench

Tests use the fast harness tier. Benchmarks retain reports under _artifacts/benchmarks/; timing comparisons are advisory. After generating API documentation, open _build-pkg-5.5.0/default/_doc/_html/httpkit-core/index.html.

For broader local validation, run the locked compiler, docs, CLI and installed-consumer checks:

tools/dev validate

Focused checks

tools/harness run --suite core --count 1000
tools/harness run --suite http1 --count 1000
tools/harness run --suite engine
tools/dune-pkg runtest test/adapter
tools/dev consumer adapter

To inspect the harness and reproduce a deliberately broken subject:

mkdir -p _artifacts
tools/harness registry
tools/harness example drop-write _artifacts/drop.json
tools/harness replay _artifacts/drop.json
tools/harness replay _artifacts/drop.json --subject drop-write
tools/harness shrink _artifacts/drop.json --subject drop-write --output _artifacts/drop.min.json

The correct subject passes; drop-write fails with OUTPUT.EXACT. Shrinking preserves the failure category and leaves the original fixture unchanged.

Further validation

Evidence is source-matched: changes to implementation, tests, toolchain, locks or API documentation invalidate earlier reports. Local validation and remote CI are separate results. Release readiness remains incomplete until all required gates have current evidence.

See Developer tooling for the consolidated OCaml CLI and command inventory.