@@ -6,99 +6,112 @@ template = "doc.html"
66aliases = ["/docs/using/creating-a-development-ship/", "/docs/getting-started/contributing"]
77+++
88
9−You can develop on Urbit in three ways:
9+There are many ways to get involved as a developer. This guide serves to give
10+you a "lay of the land" for developing on Urbit. Let's start with what you can
11+contribute to. At a high level, you can:
12+
13+- [Build clients](#clients), which use Urbit as their back-end to store data and
14+ interact with the network
15+- [Develop agents](#agents), or more precisely [*gall*
16+ agents](@/docs/arvo/gall/gall.md), which are written in [Hoon](/docs/hoon/)
17+ and can best be thought of as microservices
18+- [Contribute to Urbit's core](#core), which involves contributing to Urbit
19+ itself — either the operating system
20+ ([Arvo](https://github.com/urbit/urbit/tree/master/pkg/arvo)), runtime
21+ ([Vere](https://github.com/urbit/urbit/tree/master/pkg/urbit)), or public key
22+ infrastructure ([Azimuth](https://github.com/urbit/azimuth))
23+
24+Below we'll go into more detail about each of these options and do our best to
25+point you towards a number of additional helpful resources that can be found
26+throughout the docs.
27+
28+### Build Clients {#clients}
29+
30+Urbit ships with [Landscape](@/docs/landscape/overview.md), which can be thought
31+of as its flagship client. Landscape can be broken into two different technical
32+components: there's the collection of [services](#services) that utilize the
33+Urbit for networking and data persistence, and the JavaScript client, which is
34+an [interface](https://github.com/urbit/urbit/tree/master/pkg/interface) built
35+with [React](https://reactjs.org).
36+
37+Additionally, you can [contribute to
38+Landscape](https://github.com/urbit/urbit/blob/master/pkg/interface/CONTRIBUTING.md)
39+by tackling issues in its [issue
40+tracker](https://github.com/urbit/landscape/issues) and/or running the the
41+[development stream](https://groups.google.com/a/urbit.org/g/dev/c/r2hv4ajCLwk).
42+
43+You can create your own clients that uses Urbit to store data and interact with
44+other Urbit ships without writing any Hoon code thanks to Urbit's HTTP APIs.
45+This could be a chat client, a writing app, a game, or anything else that can
46+communicate over HTTP.
47+
48+To get started quickly with the language of your choice, see the list
49+libraries that provide HTTP interfaces to Urbit [here](https://github.com/urbit/awesome-urbit#http-apis-airlock).
50+
51+To learn more about how to work with Urbit's HTTP interface, follow [this
52+guide](@/docs/arvo/eyre/using-eyre.md).
53+
54+Alternatively, command-line interface (CLI) applications can be built using a
55+library called `shoe`, which you can learn more about
56+[here](@/docs/hoon/guides/cli-tutorial.md). This does require Hoon knowledge.
57+
58+### Develop Agents {#agents}
59+
60+Gall agents can be best thought of as individual services with a
61+statically-typed interface and built-in database. They're written in
62+[Hoon](@/docs/hoon/overview.md) and all conform to a specific
63+[interface](@/docs/arvo/gall/gall-api.md) that's defined by the kernel vane
64+called [Gall](@/docs/arvo/gall/gall.md).
65+
66+Applications built on Urbit utilize a collection of different agents, each of
67+which handle specific functionality. The [Landscape
68+architecture](@/docs/landscape/overview.md) is a good reference implementation
69+to see how this pattern works in practice.
70+
71+If you want to learn how to build gall agents, your best bet is to first [learn
72+the Hoon programming language](@/docs/hoon/hoon-school/_index.md), and then follow that
73+up with the [Gall guide](@/docs/arvo/gall/tutorial.md).
74+
75+### Contribute to Urbit Core {#core}
76+
77+Working on the core means improving the Urbit project itself, working with the
78+existing community of Urbit developers. The kernel is much more stable, but
79+generally more challenging from an engineering standpoint.
80+
81+Just arrived and unsure what to work on? An ideal way to get started is by
82+experimenting with the system, talking to other developers, and reading (or
83+[contributing to](https://github.com/urbit/docs)) the [documentation](/docs/).
84+
85+Prefer learning with an instructor? Our community runs an online course that
86+covers the basics of Urbit development called
87+[Hooniversity](https://hooniversity.org/). If course-based learning works well
88+for you, we recommend you sign up.
89+
90+The Urbit developer community congregates around [the urbit-dev mailing
91+list](https://groups.google.com/a/urbit.org/forum/#!forum/dev), the
92+`~bitbet-bolbel/urbit-community` group on Landscape, and [Urbit’s GitHub
93+repository](https://github.com/urbit/urbit). It’s a good idea to sign up, see
94+what people are talking about, and introduce yourself.
95+
96+Once you’re comfortable working with Urbit, check out the [project’s issues on
97+GitHub](https://github.com/urbit/urbit/issues) or some of our [contribution
98+bounties](https://grants.urbit.org/).
99+
100+If you’re looking for some guidance, need help, or would prefer direct
101+communication for your ideas, you can also always reach out to us directly at
102+[support@urbit.org](mailto:support@urbit.org).
103+
104+## Next Steps
105+
106+From here, you'll probably want to learn more about:
107+
108+- How to set up a [development environment](@/docs/development/environment.md)
109+- Our [grants program](@/docs/development/grants.md), where you can earn address
110+ space for helping the project grow
111+- The different [project
112+ repositories](@/docs/development/project-repositories.md), both official and
113+ community-maintained
114+- Our development [Precepts](@/docs/development/precepts.md), which outline the
115+ philosophies that drive Urbit development
10116
11−- [Applications using Urbit](#api), which use Urbit as the back-end to store data and communicate with others
12−- [Urbit Applications](#application), which are written in [Hoon](/docs/hoon/), and run as part of Urbit
13−- [Urbit Core](#core), which involves contributing to Urbit's operating system ([Arvo](https://github.com/urbit/urbit/tree/master/pkg/arvo)) or runtime ([Vere](https://github.com/urbit/urbit/tree/master/pkg/urbit))
14117
15−This guide will start by getting you set up to run an Urbit ship, and then tell you everything you need to know to do either.
16−
17−### Setting up your environment
18−
19−We assume you’ve gotten a basic introduction to Urbit. If you haven’t, read the [Understanding Urbit](@/understanding-urbit/_index.md) series.
20−
21−Once you’re ready, you can get started on the network right away and take some first steps, without acquiring an identity, by [creating a comet](@/using/install.md#comet).
22−
23−When developing, however, we recommend [booting a development ship](#creating-a-development-ship) and working locally -- you may need to make changes that could, in the wrong hands, destroy the ship’s environment, and it’s best to do so in a safe, separate place.
24−
25−## Applications using Urbit {#api}
26−
27−Urbit ships with its own set of apps written in its own language, Hoon. However it is also meant to integrate with applications written in other languages via an API. The clearest example of an application using Urbit is Landscape, the default client. Although it does currently ship with Urbit, its front-end is a separate piece of software that uses Urbit's HTTP APIs to interact with an Urbit ship. You can create your own application that uses Urbit to store data and interact with other Urbit ships without writing any Hoon code thanks to Urbit's HTTP APIs. This could be a chat client, a writing app, a game, or anything else that can communicate over HTTP.
28−
29−To get started quickly with the language of your choice, see the following libraries that provide HTTP interfaces to Urbit:
30−
31− - [Python](https://github.com/baudtack/urlock-py) (Stable)
32− - [Swift](https://github.com/dclelland/UrsusAirlock) (Under development)
33− - [Haskell](https://github.com/bsima/urbit-airlock) (Under active development)
34− - [JavaScript](https://www.npmjs.com/package/urbit) (Under active development)
35− - Go (Pending release)
36−
37−[View details about using the API or creating your own implementation here.](@/docs/development/integrating-api.md)
38−
39−## Urbit Applications {#application}
40−
41−Urbit applications are still young, but can be fun to experiment with.
42−
43−When creating user applications on Urbit, you aren’t tied to any particular user interface. They can work without providing a response to the user, or by printing to the Dojo, or with an interface in Landscape, which uses [Eyre](@/docs/arvo/eyre/eyre.md) (the Arvo vane that serves HTTP to serve a React-based interface to the application through a web browser).
44−
45−When writing applications, you will often make use of [Gall](@/docs/hoon/hoon-school/gall.md), the Arvo vane that manages user applications.
46−
47−If you want to see examples of Urbit applications with common functionality requirements, you can see our [examples](https://github.com/urbit/examples) repository. If you want to get started building applications with a Landscape interface, check out our [create-landscape-app](https://github.com/urbit/create-landscape-app) repository.
48−
49−## Urbit Core {#core}
50−
51−Working on the core means improving the Urbit project itself, working with the existing community of Urbit developers. The kernel is much more stable, but generally more challenging from an engineering standpoint.
52−
53−Just arrived and unsure what to work on? An ideal way to get started is by experimenting with the system, talking to other developers, and reading (or [contributing to](https://github.com/urbit/docs)) the [documentation](/docs/).
54−
55−Prefer learning with an instructor? Our community runs an online course that covers the basics of Urbit development called [Hooniversity](https://hooniversity.org/). If course-based learning works well for you, we recommend you sign up.
56−
57−The Urbit developer community congregates around [the urbit-dev mailing list](https://groups.google.com/a/urbit.org/forum/#!forum/dev), the `~bitbet-bolbel/urbit-community` group on Landscape, and [Urbit’s GitHub repository](https://github.com/urbit/urbit). It’s a good idea to sign up, see what people are talking about, and introduce yourself.
58−
59−Once you’re comfortable working with Urbit, check out the [project’s issues on GitHub](https://github.com/urbit/urbit/issues) or some of our [contribution bounties](https://grants.urbit.org/).
60−
61−If you’re looking for some guidance, need help, or would prefer direct communication for your ideas, you can also always reach out to us directly at [support@urbit.org](mailto:support@urbit.org).
62−
63−## Creating a development ship {#creating-a-development-ship}
64−
65−To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.
66−
67−Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have [installed our software](/using/install).
68−
69−To create a fake ship named `~zod`, run the command below. You can replace `zod` with any valid Urbit ship-name.
70−
71−```
72−./urbit -F zod
73−```
74−
75−Now you should see a block of boot messages, starting with the Urbit version number. Welcome!
76−
77−
78−## How else can I contribute? {#how}
79−
80−The Urbit project is a global community of developers, users, and fans. If you’re interested in getting involved, there’s space for you; you don’t have to be a developer to be a part of the project.
81−
82−### Running stars and galaxies
83−
84−There are two ways to participate in the Arvo network: as a user running a planet and as an infrastructure provider running a galaxy or a star.
85−
86−For planets, Urbit is a peer-to-peer network where users can interact with each other via Landscape, or using custom applications that anyone can write.
87−
88−Running a planet helps build Urbit’s community, surfaces bugs, and helps core developers improve Urbit under realistic conditions.
89−
90−Stars and galaxies, however, have additional responsibilities and play a role in peer discovery as well as star and planet distribution. You can think of stars and galaxies as similar to the DNS system in the modern Internet. Most users don’t know it exists, but without it, the web wouldn’t work at all.
91−
92−Running a reliable galaxy or star, and spawning stars and planets from them, are excellent ways to help bootstrap the Urbit network.
93−
94−If you’re interested in running a galaxy or star, you’ll be reliably providing peer discovery for your children just by running your node – and we’re doing our best to make this both easy and profitable. If you’re interested in this, see [Star and Galaxy Operations](@/using/os/stars-and-galaxies.md).
95−
96−If you’re interested in distributing planets, read on.
97−
98−### Distribute points
99−
100−Want to get your friends and family into Urbit? Distribute planets using Bridge with a feature called **delegated sending**.
101−
102−Here’s how it works: any star can grant a number of invites to any of its child planets. Those planets can then send one-time-use invite codes via email to anyone of their choosing.
103−
104−For instructions on how to grant and send invites, check out [Using Bridge](@/using/id/using-bridge.md).