Add HACKING.md with hints for working on Eio

HACKING.md

@@ -0,0 +1,106 @@
+## Installing Eio from Git
+
+If you want to run the latest development version from Git, run these commands:
+
+```
+git clone --recursive https://github.com/ocaml-multicore/eio.git
+cd eio
+opam pin -yn .
+opam install eio_main
+```
+
+The `--recursive` flag is useful because we sometimes use Git submodules
+to vendor libraries that haven't been released yet.
+
+## Layout of the code
+
+`lib_eio/core` contains the core logic about fibers, promises, switches, etc.
+`lib_eio` extends this with e.g. streams, buffered readers, buffered writers,
+and a load of types for OS resources (files, networks, etc).
+
+There is one directory for each backend (e.g. `eio_linux`).
+Each backend provides a scheduler that integrates with a particular platform,
+and implements some or all of the cross-platform resource APIs.
+For example, `eio_linux` implements the network interface using `io_uring` to send data.
+
+`lib_main` just selects an appropriate backend for the current system.
+
+## Writing a backend
+
+It's best to start by reading `lib_eio/mock/backend.ml`, which implements a mock backend with no actual IO.
+You can then read one of the real backends to see how to integrate this with the OS.
+
+Most backends are built in two layers:
+
+- A "low-level" module directly wraps the platform's own API, just adding support for suspending fibers for concurrency
+  and basic safety features (such wrapping `Unix.file_descr` to prevent use-after-close races).
+
+- An implementation of the cross-platform API defined in the `eio` package that uses the low-level API internally.
+  This should ensure that errors are reported using the `Eio.Io` exception.
+
+## Tests
+
+Eio has tests in many places...
+
+### Cross-platform unit tests
+
+These are in the top-level `tests` directory.
+They are run against whichever backend `Eio_main.run` selects, and therefore must get the same result for all backends.
+
+### Concurrency primitives
+
+`lib_eio/tests` tests some internal data structures, such as the lock-free cells abstraction.
+The `.md` files in that directory provide a simple walk-through to demonstrate the basic operation,
+while `lib_eio/tests/dscheck` uses [dscheck][] to perform exhaustive testing of all atomic interleavings
+
+At the time of writing, dscheck has some performance problems that make it unusable by default, so
+you must use the version in https://github.com/ocaml-multicore/dscheck/pull/3 instead.
+
+### Benchmarks
+
+The `bench` directory contains various speed tests.
+`make bench` is a convenient way to run all of them.
+This is useful to check for regressions.
+
+If you want to contibute an optimisation, please add a benchmark so that we can measure the improvement.
+If you are changing something, make sure the benchmark doesn't get significantly worse.
+
+### Stress and fuzz testing
+
+The `fuzz` directory uses afl-fuzz to search for bugs.
+
+Using it properly requires an instrumented version of the OCaml compiler
+(see https://v2.ocaml.org/manual/afl-fuzz.html for instructions).
+The `dune` build rules don't use afl-fuzz; they just do a few random tests and then stop.
+
+To run e.g. the `fuzz_buf_read` tests with afl-fuzz:
+
+```
+mkdir input
+date > input/seed
+afl-fuzz -m 1000 -i input -o output ./_build/default/fuzz/fuzz_buf_read.exe @@
+```
+
+- `Fork server handshake failed` indicates that you are not using an AFL-enabled version of OCaml.
+- `The current memory limit (75.0 MB) is too restrictive` means you forgot to use `-m`.
+
+The `stress` directory contains stress tests (that try to trigger races by brute force).
+
+### Backend-specific tests
+
+There are also backend-specific tests, e.g.
+
+- `lib_eio_linux/tests`
+- `lib_eio_luv/tests`
+
+Use these for tests that only make sense for one platform.
+
+## Code formatting
+
+Eio's code is indented using ocp-indent.
+When making PRs, please do not apply other formatting tools to existing code unrelated to your PR.
+Try to avoid making unnecessary changes; this makes review harder and clutters up the Git history.
+`ocamlformat` may be useful to get badly messed up code to a baseline unformatted state,
+from which human formatting can be added where needed.
+
+[dscheck]: https://github.com/ocaml-multicore/dscheck

README.md

@@ -113,21 +113,14 @@ To install it yourself:
 
 ## Getting Eio
 
-If you want to run the latest development version from Git, run these commands
-(otherwise, skip them and you'll get the latest release from opam):
-
-```
-git clone https://github.com/ocaml-multicore/eio.git
-cd eio
-opam pin -yn .
-```
-
-Either way, install `eio_main` (and `utop` if you want to try it interactively):
+Install `eio_main` (and `utop` if you want to try it interactively):
 
 ```
 opam install eio_main utop
 ```
 
+If you want to install the latest unreleased development version of Eio, see [HACKING.md](./HACKING.md).
+
 ## Running Eio
 
 Try out the examples interactively by running `utop` in the shell.
@@ -1698,7 +1691,7 @@ end
 
 - [lib_eio/eio.mli](lib_eio/eio.mli) documents Eio's public API.
 - [doc/rationale.md](doc/rationale.md) describes some of Eio's design tradeoffs in more detail.
-- [lib_eio/mock/backend.ml](lib_eio/mock/backend.ml) is a skeleton Eio backend with no actual IO.
+- [HACKING.md](./HACKING.md) describes how to work with the Eio source code.
 
 Some background about the effects system can be found in:
 

tests/flow.md

@@ -153,7 +153,7 @@ Make sure we don't crash on SIGPIPE:
     Eio.Flow.copy_string "Test" w;
     assert false
   with Eio.Io (Eio.Net.E Connection_reset _, _) ->
-    traceln "Connection_reset (good)"
+    traceln "Connection_reset (good)";;
 +Connection_reset (good)
 - : unit = ()
 ```