diff --git a/.github/scripts/hoon/setup-ship.sh b/.github/scripts/hoon/setup-ship.sh index 5bb682c..9f99c00 100755 --- a/.github/scripts/hoon/setup-ship.sh +++ b/.github/scripts/hoon/setup-ship.sh @@ -39,19 +39,19 @@ lensapp 'hood' "+hood/rm /=$DESK=/sys/vane/khan/hoon" lensapp 'hood' "+hood/mount %$DESK" -cp -rfL ./hoon/scaffolding/azimuth-pill.hoon $DESK_DIR -cp -rfL ./hoon/scaffolding/baby.hoon $DESK_DIR +cp -rfL ./resources/pills/src/baby/baby.hoon $DESK_DIR +cp -rfL ./resources/pills/src/azimuth/azimuth-pill.hoon $DESK_DIR -cp -rfL ./hoon/scaffolding/cradle.hoon $DESK_LIB_DIR -cp -rfL ./hoon/scaffolding/naive-cradle.hoon $DESK_LIB_DIR -cp -rfL ./hoon/scaffolding/logs.jam $DESK_LIB_DIR -cp -rfL ./hoon/scaffolding/mainnet.azimuth-snapshot $DESK_LIB_DIR +cp -rfL ./resources/pills/src/baby/cradle.hoon $DESK_LIB_DIR +cp -rfL ./resources/pills/src/azimuth/naive-cradle.hoon $DESK_LIB_DIR +cp -rfL ./resources/pills/src/azimuth/logs.jam $DESK_LIB_DIR +cp -rfL ./resources/pills/src/azimuth/mainnet.azimuth-snapshot $DESK_LIB_DIR lensapp 'hood' "+hood/commit %$DESK" # XX: No tests yet #mkdir $DESK_TST_DIR -# cp -rfL ./hoon/scaffolding/tests/* $DESK_TST_DIR +# cp -rfL ./resources/pills/src/azimuth/tests/* $DESK_TST_DIR # XX: redo when conn.c cli available check() { diff --git a/DEVELOPERS.md b/DEVELOPERS.md index dbbe1d1..e82ac33 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 dd6cf30..e4b149a 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 -... +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 ``` -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 - -``` -.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! diff --git a/rust/ares/test_data/decfast.jam b/resources/jam/decfast.jam similarity index 100% rename from rust/ares/test_data/decfast.jam rename to resources/jam/decfast.jam diff --git a/rust/ares/test_data/decflow.jam b/resources/jam/decflow.jam similarity index 100% rename from rust/ares/test_data/decflow.jam rename to resources/jam/decflow.jam diff --git a/rust/ares/test_data/decrement.jam b/resources/jam/decrement.jam similarity index 100% rename from rust/ares/test_data/decrement.jam rename to resources/jam/decrement.jam diff --git a/rust/ares/test_data/decrement2.jam b/resources/jam/decrement2.jam similarity index 100% rename from rust/ares/test_data/decrement2.jam rename to resources/jam/decrement2.jam diff --git a/rust/ares/test_data/decslow.jam b/resources/jam/decslow.jam similarity index 100% rename from rust/ares/test_data/decslow.jam rename to resources/jam/decslow.jam diff --git a/rust/ares/test_data/hurray.jam b/resources/jam/hurray.jam similarity index 100% rename from rust/ares/test_data/hurray.jam rename to resources/jam/hurray.jam diff --git a/rust/ares/test_data/repeat5_10.jam b/resources/jam/repeat5_10.jam similarity index 100% rename from rust/ares/test_data/repeat5_10.jam rename to resources/jam/repeat5_10.jam diff --git a/rust/ares/test_data/repeat5_100.jam b/resources/jam/repeat5_100.jam similarity index 100% rename from rust/ares/test_data/repeat5_100.jam rename to resources/jam/repeat5_100.jam diff --git a/rust/ares/test_data/repeat5_1000.jam b/resources/jam/repeat5_1000.jam similarity index 100% rename from rust/ares/test_data/repeat5_1000.jam rename to resources/jam/repeat5_1000.jam diff --git a/rust/ares/test_data/repeat5_1000_tc.jam b/resources/jam/repeat5_1000_tc.jam similarity index 100% rename from rust/ares/test_data/repeat5_1000_tc.jam rename to resources/jam/repeat5_1000_tc.jam diff --git a/rust/ares/test_data/repeat5_100_tc.jam b/resources/jam/repeat5_100_tc.jam similarity index 100% rename from rust/ares/test_data/repeat5_100_tc.jam rename to resources/jam/repeat5_100_tc.jam diff --git a/rust/ares/test_data/repeat5_10_tc.jam b/resources/jam/repeat5_10_tc.jam similarity index 100% rename from rust/ares/test_data/repeat5_10_tc.jam rename to resources/jam/repeat5_10_tc.jam diff --git a/rust/ares/test_data/shax.jam b/resources/jam/shax.jam similarity index 100% rename from rust/ares/test_data/shax.jam rename to resources/jam/shax.jam diff --git a/resources/pills/azimuth.pill b/resources/pills/azimuth.pill new file mode 100644 index 0000000..169008b Binary files /dev/null and b/resources/pills/azimuth.pill differ diff --git a/resources/pills/baby.pill b/resources/pills/baby.pill new file mode 100644 index 0000000..fe25992 Binary files /dev/null and b/resources/pills/baby.pill differ diff --git a/resources/pills/full.pill b/resources/pills/full.pill new file mode 100755 index 0000000..fb7e966 Binary files /dev/null and b/resources/pills/full.pill differ diff --git a/resources/pills/slim.pill b/resources/pills/slim.pill new file mode 100644 index 0000000..f75c1a2 Binary files /dev/null and b/resources/pills/slim.pill differ diff --git a/hoon/scaffolding/azimuth-pill.hoon b/resources/pills/src/azimuth/azimuth-pill.hoon similarity index 100% rename from hoon/scaffolding/azimuth-pill.hoon rename to resources/pills/src/azimuth/azimuth-pill.hoon diff --git a/hoon/scaffolding/logs.jam b/resources/pills/src/azimuth/logs.jam similarity index 100% rename from hoon/scaffolding/logs.jam rename to resources/pills/src/azimuth/logs.jam diff --git a/hoon/scaffolding/mainnet.azimuth-snapshot b/resources/pills/src/azimuth/mainnet.azimuth-snapshot similarity index 100% rename from hoon/scaffolding/mainnet.azimuth-snapshot rename to resources/pills/src/azimuth/mainnet.azimuth-snapshot diff --git a/hoon/scaffolding/naive-cradle.hoon b/resources/pills/src/azimuth/naive-cradle.hoon similarity index 100% rename from hoon/scaffolding/naive-cradle.hoon rename to resources/pills/src/azimuth/naive-cradle.hoon diff --git a/hoon/scaffolding/baby.hoon b/resources/pills/src/baby/baby.hoon similarity index 100% rename from hoon/scaffolding/baby.hoon rename to resources/pills/src/baby/baby.hoon diff --git a/hoon/scaffolding/cradle.hoon b/resources/pills/src/baby/cradle.hoon similarity index 100% rename from hoon/scaffolding/cradle.hoon rename to resources/pills/src/baby/cradle.hoon diff --git a/hoon/scaffolding/playpen.hoon b/resources/pills/src/toddler/playpen.hoon similarity index 100% rename from hoon/scaffolding/playpen.hoon rename to resources/pills/src/toddler/playpen.hoon diff --git a/hoon/scaffolding/toddler.hoon b/resources/pills/src/toddler/toddler.hoon similarity index 100% rename from hoon/scaffolding/toddler.hoon rename to resources/pills/src/toddler/toddler.hoon diff --git a/resources/pills/toddler.pill b/resources/pills/toddler.pill new file mode 100644 index 0000000..5a6858a Binary files /dev/null and b/resources/pills/toddler.pill differ diff --git a/rust/ares/test_data/baby.pill b/rust/ares/test_data/baby.pill deleted file mode 100644 index 10079a6..0000000 Binary files a/rust/ares/test_data/baby.pill and /dev/null differ