From 25a8391c6570a4cbc22ef25879bd2dc405482ce9 Mon Sep 17 00:00:00 2001 From: Edward Amsden Date: Fri, 24 Nov 2023 11:38:51 -0600 Subject: [PATCH] docs: developer intro --- CONTRIBUTING.md | 7 +++++-- DEVELOPERS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 5 ++++- 3 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 DEVELOPERS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 084b066..557d7ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,9 @@ -# Contributing to New Mars +# Contributing to Ares + +Below are guidelines for contributions to Ares. For information on building and hacking on ares, see [DEVELOPERS.md](DEVELOPERS.md). ## Style -Hoon should generally follow the kernel style. +Hoon should generally follow the [Hoon Style Guide](https://docs.urbit.org/language/hoon/guides/style). Rust code must pass `cargo fmt --check`. @@ -19,3 +21,4 @@ Examples: ## PR reviews Don't merge without them, don't forget to do them for others. + diff --git a/DEVELOPERS.md b/DEVELOPERS.md new file mode 100644 index 0000000..7bca10d --- /dev/null +++ b/DEVELOPERS.md @@ -0,0 +1,45 @@ +# Developing Ares + +## Nix +Ares uses a Nix developer shell to set up the environment for rust builds. Please [Install Nix](https://nixos.org/download#download-nix). +With Nix installed, you can run + +```bash +nix develop +``` + +in `rust/` or any subdirectory, and you will be dropped into a BASH shell with the build environment set up. This will provide proper versions of non-rust dependencies, as well as the rust environment. + +## Rust + +To build Ares, start a nix development shell as above. Within the shell, in the `rust/ares` directory, you can run: + +```bash +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. + +To watch rust and check for errors, run + +```bash +cargo watch --clear +``` + +Until terminated with ctrl-c, this will rebuild Ares library on any change to the underlying source files and report any warnings and errors. It will *not* produce the executable. You must run the build command above to rebuild the executable. + +## Hoon + +The Nock analysis and lowering for Ares is written in Hoon, and lives at `hoon/codegen.` It is meant to be jammed and included in the Ares binary. (See [`src/load.rs`](rust/ares/src/load.rs) in the Rust sources for details.) + +If the hoon source has been synced to a desk, e.g. `sandbox`, on a fakezod, then the build generator can be invoked as: + +``` +.cg/jam +sandbox!cg-make +``` + +This will build the Hoon standard library and the Ares Nock analysis as a "trap" meant to be run by Ares. The jammed output can be found at `/.urb/put/cg.jam`, and should be copied to the `rust/ares/bin` directory, from whence the rust build will include it in the executable. + +Instructions on testing the analysis in a fakezod are forthcoming. diff --git a/README.md b/README.md index 007e8fd..51d4431 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,7 @@ A redesigned Mars for the Urth/Mars Urbit runtime. Currently WIP. -Read the [proposal](docs/proposal/proposal-nock-performance.md) and [hypotheses](docs/proposal/hypotheses.md) for an overview. Before branching or opening a PR please review the [contribution guidelines](CONTRIBUTING.md). +Read the [proposal](docs/proposal/proposal-nock-performance.md) and [hypotheses](docs/proposal/hypotheses.md) for an overview. + +If you want to hack on Ares, read the [developer guide](DEVELOPERS.md). +Before branching or opening a PR please review the [contribution guidelines](CONTRIBUTING.md).