mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-09-11 10:46:43 +03:00
Fix up README and CONTRIBUTING for new world order
This commit is contained in:
parent
bb5e995202
commit
e31723f077
100
CONTRIBUTING.md
100
CONTRIBUTING.md
@ -7,12 +7,23 @@ Thank you for your interest in contributing to urbit.
|
||||
You may have an identity on the live network, but doing all your
|
||||
development on the live network would be cumbersome and unnecessary.
|
||||
Standard practice in urbit development is to work on a fake `~zod`. A
|
||||
fake `~zod` will get its initial files from the `urb/zod/` directory
|
||||
rather than trying to sync them over the network, which is invaluable
|
||||
for working in Hoon. Also, a fake `~zod` or any fake urbit instances you
|
||||
fake `~zod` will get its initial files from the `arvo/` directory rather
|
||||
than trying to sync them over the network, which is invaluable for
|
||||
working in Hoon. Also, a fake `~zod` or any fake urbit instances you
|
||||
start do not talk to the live network, but to a fake network that exists
|
||||
only on your computer.
|
||||
|
||||
First, you'll want to get an `arvo/` directory. Arvo is kept in its own
|
||||
repository, and changes more rapidly than the main C project does.
|
||||
|
||||
From inside your `urbit` directory, do:
|
||||
|
||||
git clone https://github.com/urbit/arvo
|
||||
|
||||
The arvo repository can live safely inside the main urbit repository,
|
||||
since it's listed in .gitignore. However, vere will try to find the
|
||||
arvo directory in the current directory when starting a fake `~zod`.
|
||||
|
||||
To start a fake `~zod`, the command is:
|
||||
|
||||
bin/urbit -F -I zod -c [pier directory]
|
||||
@ -25,23 +36,24 @@ galaxy.
|
||||
## Kernel development
|
||||
|
||||
Working on either C or non-kernel Hoon should not bring any surprises,
|
||||
but the Hoon kernel (anything under `urb/zod/arvo/`) is bootstrapped
|
||||
from `urbit.pill` in `urb/`, and must be manually recompiled if any
|
||||
changes are made. The command to manually recompile the kernel and
|
||||
install the new kernel is `|reset` in `dojo`. This rebuilds from the
|
||||
`arvo` directory in the `home` desk in `%clay`. Currently, `|reset`
|
||||
does not reload apps like `dojo` itself, which will still reference the
|
||||
old kernel. To force them to reload, make a trivial edit to their main
|
||||
source file (under the `app` directory) in `%clay`.
|
||||
but the Hoon kernel (anything under `arvo/arvo/`) is bootstrapped
|
||||
from `urbit.pill`, and must be recompiled if any changes are made. This
|
||||
should happen automatically when you make changes, but if it doesn't,
|
||||
the command to manually recompile the kernel and install the new kernel
|
||||
is `|reset` in `dojo`. This rebuilds from the `arvo` directory in the
|
||||
`home` desk in `%clay`. Currently, `|reset` does not reload apps like
|
||||
`dojo` itself, which will still reference the old kernel. To force them
|
||||
to reload, make a trivial edit to their main source file (under the
|
||||
`app` directory) in `%clay`.
|
||||
|
||||
If you do any kernel development, be sure to read the section below about
|
||||
pills.
|
||||
|
||||
## Git practice
|
||||
|
||||
Since we use the GitHub issue tracker, it is helpful to contribute via a
|
||||
GitHub pull request. If you already know what you are doing, skip down
|
||||
to the Style section.
|
||||
Since we use the GitHub issue tracker, it is helpful (though not
|
||||
required) to contribute via a GitHub pull request. If you already know
|
||||
what you are doing, skip down to the Style section.
|
||||
|
||||
Start by cloning the repository on your work machine:
|
||||
|
||||
@ -106,12 +118,11 @@ less obvious stylistic rules are:
|
||||
|
||||
## The kernel and pills
|
||||
|
||||
urbit bootstraps itself using a binary blob called `urbit.pill`, which
|
||||
we do indeed keep in version control. This creates some special
|
||||
requirements. If you are not changing anything in the kernel (everything
|
||||
under `urb/zod/arvo/`) then you can skim this section (please do not
|
||||
skip it entirely, though). If you *are* working there, then this
|
||||
section is critically important!
|
||||
urbit bootstraps itself using a binary blob called `urbit.pill`. You
|
||||
probably remember fetching it from `bootstrap.urbit.org` before your
|
||||
first boot. This is just the compiled version of the kernel, which you
|
||||
can find in the `arvo/arvo/` directory - `hoon.hoon`, `zuse.hoon`, and
|
||||
so on.
|
||||
|
||||
The procedure for creating `urbit.pill` is often called "soliding". It
|
||||
is somewhat similar to `|reset`, but instead of replacing your running
|
||||
@ -121,28 +132,16 @@ is, on a fakezod:
|
||||
.urbit/pill +solid
|
||||
|
||||
When the compilation finishes, your `urbit.pill` will be found in the
|
||||
`[pier]/.urb/put/` directory. Copy it into `urb/` and add it to your
|
||||
commit.
|
||||
`[pier]/.urb/put/` directory.
|
||||
|
||||
The requirement here is that every commit that changes the kernel must
|
||||
come with an `urbit.pill` built from the same code in `urb/zod/arvo/`
|
||||
for that commit. (Only changing the actual Hoon code counts, so a change
|
||||
to a jet with no corresponding Hoon change does not require a new pill.)
|
||||
This is so that checking out an arbitrary revision and starting up a
|
||||
fakezod actually works as expected. However you do this is fine, but I
|
||||
like to do it as part of my committing process - just before `git
|
||||
commit`, I fire up a new fakezod. This will use the previous
|
||||
`urbit.pill`, but the kernel code in `%clay` will be copied from
|
||||
`urb/zod/arvo/`, so `+solid` will compile it. Then I copy `urbit.pill`
|
||||
into `urb/` and make my commit.
|
||||
Ordinarily, `http://bootstrap.urbit.org/latest.pill` will be updated
|
||||
to match whatever's on `master` in the `arvo` repository with every
|
||||
merge to `master`. Older pills will be stored with the `git` SHA1 of the
|
||||
relevant commit as `[sha1].pill`.
|
||||
|
||||
If you rebase or interactive rebase your commits, be sure to preserve
|
||||
this property on all the commits you end up with. If multiple people
|
||||
were collaborating on your branch, you may end up with conflicts in
|
||||
`urbit.pill` and have to merge the branch into itself to resolve them.
|
||||
Just do the same procedure to create a new, merged pill before
|
||||
committing the merge. Otherwise, just make sure to use the correct
|
||||
`urbit.pill` for each commit.
|
||||
If you're doing heavy kernel hacking and want to submit intermediate
|
||||
pills for your branch, please include them with your pull request, and
|
||||
they'll be uploaded to `bootstrap.urbit.org` when your branch is merged.
|
||||
|
||||
## Debug urbit with `gdb`
|
||||
|
||||
@ -188,20 +187,7 @@ The urbit developers communicate on urbit itself. Joining the
|
||||
Subscribing to `urbit-dev` on Google Groups is also recommended, since
|
||||
this is where continuity breach notifications are sent.
|
||||
|
||||
You can also contact one of the following people:
|
||||
|
||||
- Philip Monk
|
||||
|
||||
email: philip.monk@tlon.io
|
||||
|
||||
urbit: `~wictuc-folrex`
|
||||
|
||||
GitHub: [@philipcmonk](https://github.com/philipcmonk/)
|
||||
|
||||
- Raymond Pasco
|
||||
|
||||
email: ray@the.ug
|
||||
|
||||
urbit: `~ramtev-wisbyt`
|
||||
|
||||
GitHub: [@juped](https://github.com/juped/)
|
||||
Pull requests in non-GitHub forms can go to Raymond Pasco
|
||||
([ray@the.ug](mailto:ray@the.ug)). Questions or other communications
|
||||
about contributing to Urbit can go to Raymond Pasco or Philip Monk
|
||||
([philip.monk@tlon.io](mailto:philip.monk@tlon.io)).
|
||||
|
15
README.md
15
README.md
@ -145,7 +145,7 @@ three packages, at least with Homebrew. Your mileage may vary.
|
||||
|
||||
Clone the repo:
|
||||
|
||||
git clone git://github.com/urbit/urbit.git
|
||||
git clone https://github.com/urbit/urbit.git
|
||||
|
||||
`cd` to the directory you just created:
|
||||
|
||||
@ -157,8 +157,17 @@ Run `make`:
|
||||
|
||||
(On FreeBSD, use `gmake` instead.)
|
||||
|
||||
The executable is `bin/urbit`. Install it somewhere, or just use it
|
||||
where it is.
|
||||
The executable is `bin/urbit`.
|
||||
|
||||
Fetch the latest bootstrapping pill:
|
||||
|
||||
curl -o urbit.pill http://bootstrap.urbit.org/latest.pill
|
||||
|
||||
You can use your preferred way to fetch things from the web here.
|
||||
Urbit looks for a pill named `urbit.pill` in the current directory
|
||||
by default, so if you have anything different, you'll need to tell
|
||||
Urbit where it is (on first launch only) with the `-B` command-line
|
||||
option.
|
||||
|
||||
Launch
|
||||
======
|
||||
|
Loading…
Reference in New Issue
Block a user