8Thank you for your interest in contributing to urbit.
10## Development practice
12You may have an identity on the live network, but doing all your
13development on the live network would be cumbersome and unnecessary.
14Standard practice in urbit development is to work on a fake `~zod`. A
15fake `~zod` will get its initial files from the `urb/zod/` directory
16rather than trying to sync them over the network, which is invaluable
17for working in Hoon. Also, a fake `~zod` or any fake urbit instances you
18start do not talk to the live network, but to a fake network that exists
21To start a fake `~zod`, the command is:
23 bin/urbit -F -I zod -c [pier directory]
25To resume one that was already created, just as on the live network,
26remove `-c` (but leave the rest of the options there). `-F` uses the
27fake network, and `-I` starts an "imperial" instance - that is, an 8-bit
32Working on either C or non-kernel Hoon should not bring any surprises,
33but the Hoon kernel (anything under `urb/zod/arvo/`) is bootstrapped
34from `urbit.pill` in `urb/`, and must be manually recompiled if any
35changes are made. The command to manually recompile the kernel and
36install the new kernel is `|reset` in `dojo`. This rebuilds from the
37`arvo` directory in the `home` desk in `%clay`. Currently, `|reset`
38does not reload apps like `dojo` itself, which will still reference the
39old kernel. To force them to reload, make a trivial edit to their main
40source file (under the `ape` directory) in `%clay`.
42If you do any kernel development, be sure to read the section below about
47Since we use the GitHub issue tracker, it is helpful to contribute via a
48GitHub pull request. If you already know what you are doing, skip down
51Start by cloning the repository on your work machine:
53 git clone https://github.com/urbit/urbit
55And, additionally, fork the repository on GitHub by clicking the "Fork"
56button. Add your fork as a remote:
58 git remote add [username] https://github.com/[username]/urbit
60and set it as the default remote to push to:
62 git config --local remote.pushDefault [username]
64This is good practice for any project that uses git. You will pull
65upstream branches from urbit/urbit and push to your personal urbit fork
68Next, check out `test`, which is the mainline development branch, and
69base a new branch on it to do your work on:
72 git checkout -b [branch name]
74Now you are free to do your work on this branch. When finished, you may
75want to clean up your commits:
79Then you can push to your public fork with `git push` and make a pull
80request via the GitHub UI. Make sure you request to merge your branch
81into `test`, not `master`.
83After your changes are merged upstream, you can delete your branch (via
84github UI or `git push :[branch]` remotely, and with `git branch -d`
89The urbit project uses two-space indentation and avoids tab characters.
90In C code, it should not be too difficult to mimic the style of the code
91around you, which is just fairly standard K&R with braces on every
92compound statement. One thing to watch out for is top-level sections in
93source files that are denoted by comments and are actually indented one
96Hoon will be a less familiar language to many contributors. Some of our
97less obvious stylistic rules are:
99- Keep your source files 80 characters or less wide. Many urbit
100 developers use 80 character terminals/tmux panes/&c.
101- Tab characters are actually a syntax error, so be extra sure your
102 editor is not inserting any. Trailing whitespace is *usually* not a
103 syntax error, but avoiding it is encouraged.
104- The kernel convention is that line comments start at column 57 with
105 the `::` followed by 2 spaces. This leaves 20 characters for the
106 comment. Outside the kernel, things are less strict.
107- Tall arms within a core are conventionally separated by empty comments
108 (just `::`) at the same indentation level as the initial `++` or `+-`.
109 The last arm in a core is not followed by an empty comment, because it
110 is visually closed by the `--` that closes the core. The empty comment
111 is also sometimes omitted in data structure definitions.
113## The kernel and pills
115urbit bootstraps itself using a binary blob called `urbit.pill`, which
116we do indeed keep in version control. This creates some special
117requirements. If you are not changing anything in the kernel (everything
118under `urb/zod/arvo/`) then you can skim this section (please do not
119skip it entirely, though). If you *are* working there, then this
120section is critically important!
122The procedure for creating `urbit.pill` is often called "soliding". It
123is somewhat similar to `|reset`, but instead of replacing your running
124kernel, it writes the compiled kernel to a file. The command to solid
129When the compilation finishes, your `urbit.pill` will be found in the
130`[pier]/.urb/put/` directory. Copy it into `urb/` and add it to your
133The requirement here is that every commit that changes the kernel must
134come with an `urbit.pill` built from the same code in `urb/zod/arvo/`
135for that commit. (Only changing the actual Hoon code counts, so a change
136to a jet with no corresponding Hoon change does not require a new pill.)
137This is so that checking out an arbitrary revision and starting up a
138fakezod actually works as expected. However you do this is fine, but I
139like to do it as part of my committing process - just before `git
140commit`, I fire up a new fakezod. This will use the previous
141`urbit.pill`, but the kernel code in `%clay` will be copied from
142`urb/zod/arvo/`, so `+solid` will compile it. Then I copy `urbit.pill`
143into `urb/` and make my commit.
145If you rebase or interactive rebase your commits, be sure to preserve
146this property on all the commits you end up with. If multiple people
147were collaborating on your branch, you may end up with conflicts in
148`urbit.pill` and have to merge the branch into itself to resolve them.
149Just do the same procedure to create a new, merged pill before
150committing the merge. Otherwise, just make sure to use the correct
151`urbit.pill` for each commit.
153## Debug urbit with `gdb`
155Follow the build instructions in README.md but run `make` with argument `DEBUG=yes`:
157(If you've already built urbit first run `make clean`.)
161Run `gdb`, while loading `bin/urbit` and its symbol table:
165Set a breakpoint on `main()` (optional):
169Run your urbit comet `mycomet`:
173Continue from the breakpoint on `main()`:
179If you are not thinking of contributing with a specific goal in mind,
180the GitHub issue tracker is the first place you should look for ideas.
181Issues are tagged with a priority and a difficulty. A good place to
182start is on either a low-difficulty issue or a low-priority issue.
183Higher priority issues are likely to be assigned to someone - if this is
184the case, then contacting that person to coordinate before starting to
185work is probably a good idea.
187There is also a "help wanted" tag for things that we are especially
188eager to have outside contributions on. Check here first!
192The urbit developers communicate on urbit itself. Joining the
193`~doznec/urbit-meta` channel on `talk` is highly recommended.
194Subscribing to `urbit-dev` on Google Groups is also recommended, since
195this is where continuity breach notifications are sent.
197You can also contact one of the following people:
201 email: philip.monk@tlon.io
203 urbit: `~wictuc-folrex`
205 GitHub: [@philipcmonk](https://github.com/philipcmonk/)
211 urbit: `~ramtev-wisbyt`
213 GitHub: [@juped](https://github.com/juped/)
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list