Skip to content

Commit

Permalink
docs: minor refactor of pill documentation location and contents
Browse files Browse the repository at this point in the history
  • Loading branch information
@ashelkovnykov
ashelkovnykov committed Nov 28, 2023
1 parent dcda575 commit e507b57
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 92 deletions.
35 changes: 34 additions & 1 deletion DEVELOPERS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
105 changes: 14 additions & 91 deletions docs/pills.md
View file
Original file line number Diff line number Diff line change
@@ -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!

0 comments on commit e507b57

Please sign in to comment.