From e507b579b45a002cdd71c69229617e7b6d21b8a4 Mon Sep 17 00:00:00 2001 From: Alex Shelkovnykov Date: Tue, 28 Nov 2023 12:12:56 -0300 Subject: [PATCH] docs: minor refactor of pill documentation location and contents --- DEVELOPERS.md | 35 ++++++++++++++++- docs/pills.md | 105 +++++++------------------------------------------- 2 files changed, 48 insertions(+), 92 deletions(-) diff --git a/DEVELOPERS.md b/DEVELOPERS.md index dbbe1d1f..e82ac33f 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -22,7 +22,40 @@ cargo build to build the Ares executable. This will place the built executable at `target/debug/ares` under the `rust/ares` directory. -Ares is made to run as an urbit "serf", meaning it is intended to be invoked by a "king" which sends it commands and performs side-effects specified by its output. We use the vere king. Special instructions for building the vere king to invoke Ares are forthcoming. +### Run + +Ares is made to run as an urbit "serf", meaning it is intended to be invoked by a "king" which sends it commands and performs side-effects specified by its output. We use the Vere king. + +To run the Vere king with Ares as serf, it's necessary to modify the Vere king to launch Ares instead of its own serf. This is done by modifying the executable of the serf protocol in the `u3_lord_init` function in `lord.c` of the Vere source: + +```C +// arg_c[0] = god_u->bin_c; +arg_c[0] = "/path/to/ares/repo/rust/ares/target/debug/ares"; +``` + +Then, it is necessary to follow the [Vere build instrcutions](https://github.com/urbit/vere/blob/develop/INSTALL.md). Afterwards, it's possible to launch Vere with Ares as the serf using the usual commands: + +```bash +bazel-bin/pkg/vere/urbit -F zod +``` + +#### Pills + +Ares development and testing, unlike regular development and ship operation, currently requires careful control over what pill is used to launch a ship. Currently, there are several pills available in `resources/pills/`: +* baby.pill: an extremely minimal Arvo-shaped core and Hoon standard library (`~wicdev-wisryt` [streamed a +video of its development](https://youtu.be/fOVhCx1a-9A)) +* toddler.pill: a slightly more complex Arvo and Hoon than `baby`, which runs slow recursive operations for testing jets +* azimuth.pill: a pill that processes an Azimuth snapshot +* full.pill: the complete Urbit `v2.11` pill +* slim.pill: a slimmed down version of the Urbit `v2.11` pill that has had every desk and agent not necessary for booting to dojo removed + +More information on the pills used by Ares can be found [here](https://github.com/urbit/ares/blob/status/docs/pills.md). + +To launch a ship with a local pill (instead of downloading the default pill from urbit.org), the `-B` option is used: + +```bash +bazel-bin/pkg/vere/urbit -F zod -B /path/to/ares/repo/resources/pills/baby.pill +``` ### Test diff --git a/docs/pills.md b/docs/pills.md index dd6cf302..e4b149aa 100644 --- a/docs/pills.md +++ b/docs/pills.md @@ -1,99 +1,22 @@ -# Running a pill with Ares +# Making your own pill to run 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. +Ares development and testing, unlike regular development and ship operation, currently requires careful control over what pill is used to launch a ship. This document details how pills are created for the purposes of development and testing. -We first cover how to run `rust/ares/test_data/baby.pill`, then -`hoon/scaffolding/azimuth-pill.hoon`, and finally some information on how to -make your own pill. +## Example: `baby.pill` -## Modify Vere +`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 source Hoon for `baby.pill` in `resources/pills/src/baby/baby.hoon`, and the limited version of Hoon that it uses in `resources/pills/src/baby/cradle.hoon`. A pre-compiled `baby.pill` is already available at `resources/pills/baby.pill`. However, the steps to compile it yourself are documented below. -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 +1. Boot a fake `zod` using an ordinary Urbit executable (not the one you created +to run Ares as serf) +2. Run `|mount %base` +3. Copy the contents of `resources/pills/src/baby/` to `/path/to/fake/zod/base/lib/` +4. Run `|commit %base` +5. Run `.baby/pill -build-file %/lib/baby/hoon`. This will make a file named `baby.pill` in `/path/to/fake/zod/.urb/put/` -``` - 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 -as a string literal (probably something like `rust/ares/target/debug/ares`): - -``` -arg_c[0] = "/path/to/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/repo/bazel-bin/pkg/vere/urbit ares-urbit -``` - -## 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: - -``` -./ares-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! - -## 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 +You can now use this pill to boot a ship using your Vere + Ares executable: +```bash +./ares-urbit -F dev -B /path/to/fake/zod/.urb/put/baby.pill ``` -.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: - -``` -./ares-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. +If it writes `effect` to the terminal with every keystroke, you have succeeded!