docs: run a pill with Ares as serf

docs/pills.md

@@ -0,0 +1,98 @@
+# Running a pill with Ares
+
+We can run a pill with Ares by performing a one-line modification to Vere in order
+to use Ares as a serf. This is accurate as of August 2023 - details may have
+changed since then.
+
+We first cover how to run `rust/ares/test_data/baby.pill`, then
+`hoon/scaffolding/azimuth-pill.hoon`, then how to run your own pill.
+
+## Step 1: Modify Vere
+
+Download the Vere repo and open `/pkg/vere/lord.c`. Search for `u3_lord_init()`.
+In this function definition, you will find several lines that look something
+like
+
+```
+    arg_c[0] = god_u->bin_c;            //  executable
+    arg_c[1] = "serf";                  //  protocol
+    arg_c[2] = god_u->pax_c;            //  path to checkpoint directory
+    arg_c[3] = key_c;                   //  disk key
+    arg_c[4] = wag_c;                   //  runtime config
+...
+```
+
+Change the right hand side of the first line to the path of the Ares executable
+inside a string literal (probably something like `rust/ares/target/debug/ares`):
+
+```
+arg_c[0] = "/path/to/ares/rust/ares/target/debug/ares";
+```
+
+Next we need to compile the new version of Vere that uses Ares as a serf. See
+[INSTALL.md](https://github.com/urbit/vere/blob/develop/INSTALL.md) in the Vere
+repo on how to do this. Now `cd` to the directory you'd like this version of
+Vere to reside in and make a symlink to the `urbit` executable you just
+created like so:
+
+```
+ln -s path/to/vere/bazel-bin/pkg/vere/urbit urbit
+```
+
+## Step 2: Run `baby.pill`
+
+`baby.pill` is an extremely minimal Arvo-shaped core and Hoon standard library
+equipped with `%sham` jets needed to run it. ~wicdev-wisryt [streamed a
+video](https://youtu.be/fOVhCx1a-9A) of its development. You can find the Hoon
+for `baby.pill` in the Ares repo at `/hoon/scaffolding/baby.hoon`, and the
+library is `hoon/scaffolding/cradle.hoon`.
+
+The jammed pill is already in the Ares repo at `rust/ares/test_data/baby.pill`.
+To run it with our new version of Vere, we make a fakezod with `baby.pill` as
+the pill:
+
+```
+./urbit -F zod -B /path/to/ares/rust/ares/test_data/baby.pill
+```
+
+This will boot a fakezod. If it writes `effect` to the terminal with every
+keystroke, you have succeeded!
+
+## Step 3: Run `azimuth-pill.pill`
+
+Next we will show how to build a pill that processes an Azimuth snapshot, called
+`azimuth-pill.pill`.
+
+Boot a fakezod using the ordinary Urbit executable (not the one you created
+above) and run `|mount %`.
+
+Next, copy the contents of the `hoon/scaffolding/` folder from the Ares repo to
+`path/to/fakezod/base/lib` and run `|commit %base`, then
+
+```
+.azimuth-pill/pill -build-file %/lib/azimuth-pill/hoon
+```
+
+This will make a file `azimuth-pill.pill` in `path/to/fakezod/.urb/put`.
+
+Now we can run this pill with the version of Vere we built above:
+
+```
+./urbit -F dev -B /path/to/fakezod/.urb/put/azimuth-pill.pill
+```
+
+If you succeeded, you should see the standard boot header followed by `ran a
+thousand logs` every few moments. If you're running an optimized build (e.g.
+`opt-level = 3`) of Ares this should finish in a few minutes or less. If you're
+running an unoptimized build (e.g. `opt-level = 0`) this could take much longer.
+
+## Making your own pill
+
+At time of writing, most jets have not yet been ported to Ares and so you cannot
+boot a typical solid pill. However, following the example of `baby.pill` and the
+development video linked above, and making use of the simplified standard libary
+`cradle.hoon`, you can still get Ares to run some interesting non-trivial Hoon.
+
+After making your own pill, you can write it to disk with `.my-pill/pill
+-build-file /path/to/my/pill` from a fakezod, and then run it just like you did
+with `baby.pill` and `azimuth-pill.pill` above.