urbit/ares
1
1
Fork 0
mirror of https://github.com/urbit/ares.git synced 2024-12-23 05:12:15 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: minor refactor of pill documentation location and contents

Browse Source
This commit is contained in:
Alex Shelkovnykov 2023-11-28 12:12:56 -03:00
parent dcda5759d5
commit e507b579b4
2 changed files with 49 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
DEVELOPERS.md
View File

@ -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

107
docs/pills.md
View File

@ -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!