mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-10-26 15:49:50 +03:00
Post more link fixes.
This commit is contained in:
Sigilante
parent
ce80448695
commit
6613329878
24
content/blog/duo-announce.md
Normal file
24
content/blog/duo-announce.md
Normal file
@ -0,0 +1,24 @@
|
||||
+++
|
||||
title = "(Re)Launching developers.urbit.org"
|
||||
date = "2022-06-29"
|
||||
description = "We’ve revamped the documentation and guides."
|
||||
[extra]
|
||||
author = "N E Davis"
|
||||
ship = "~lagrev-nocfep"
|
||||
image = "TODO"
|
||||
+++
|
||||
|
||||
The Urbit docs have evolved a lot over the years. Some of this has been due to changes in the audience—for instance, early docs were voiced towards core kernel developers. Other changes have been made as we've rolled out new features, such as the 2020 Ford Fusion project or the more recent Azimuth L2 implementation. As the docs have continued to evolve, we've worked hard on putting out quality tutorials and curriculum that make Urbit easier for new developers and old alike to figure out what they need to take their projects forward. We've also seen a growing fractionation of the Urbit userbase into regular users, power users, and developers, all of whom have slightly different requirements.
|
||||
|
||||
We have migrated and reorganized our coursework, our reference documentation, and our developer site to better reflect the needs of these communities. The upgraded `developers.urbit.org` now houses the one-stop-shop for programmers, allowing `urbit.org` and `operators.urbit.org` to better speak to particular user groups besides Hoon programmers.
|
||||
|
||||
This site now contains:
|
||||
|
||||
1. [Overview](/overview) outlines the Urbit project from a technical standpoint.
|
||||
2. [Guides](/guides) span the written Hoon School and App School (formerly Gall Guides), as well as a new feature we're introducing called Lightning Tutorials, which will discuss how to quickly implement basic app functionality.
|
||||
3. [Reference](/reference) hosts the language and standard library documentation: Nock, Hoon runes and standard library, Arvo, Azimuth, and the runtime.
|
||||
4. [Courses](/courses) are landing pages for Hoon School Live and App School Live, the cohort-based versions of Hoon School and App School.
|
||||
5. [Community](/community) includes developer events and support.
|
||||
|
||||
There are often growing pains with new websites, so if you find a dead link or are certain there was a reference for something and you just can't put your finger on it anymore, drop us a line on Github or Urbit.
|
||||
|
||||
@ -1,21 +1,21 @@
|
||||
+++
|
||||
title = "Guides"
|
||||
title = "Additional Guides"
|
||||
weight = 20
|
||||
sort_by = "weight"
|
||||
template = "sections/docs/chapters.html"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
||||
## [Writing Aqua Tests](/docs/hoon/guides/aqua)
|
||||
## [Writing Aqua Tests](/guides/additional/aqua)
|
||||
|
||||
## [CLI Apps](/docs/hoon/guides/cli-tutorial)
|
||||
## [CLI Apps](/guides/additional/cli-tutorial)
|
||||
|
||||
## [Parsing](/docs/hoon/guides/parsing)
|
||||
## [Parsing](/guides/additional/parsing)
|
||||
|
||||
## [Strings](/docs/hoon/guides/strings)
|
||||
## [Strings](/guides/additional/strings)
|
||||
|
||||
## [JSON](/docs/hoon/guides/json-guide)
|
||||
## [JSON](/guides/additional/json-guide)
|
||||
|
||||
## [Sail](/docs/hoon/guides/sail)
|
||||
## [Sail](/guides/additional/sail)
|
||||
|
||||
## [Unit tests](/docs/hoon/guides/unit-tests)
|
||||
## [Unit tests](/guides/additional/unit-tests)
|
||||
|
||||
@ -6,22 +6,19 @@ template = "sections/docs/chapters.html"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
||||
## [Overview](/docs/userspace/threads/overview)
|
||||
## [Overview](/guides/additional/threads/overview)
|
||||
|
||||
Overview of threads.
|
||||
|
||||
## [Basics](/docs/userspace/threads/basics/)
|
||||
## [Basics](/guides/additional/threads/basics/)
|
||||
|
||||
Tutorial and explanation of the basics of writing threads.
|
||||
|
||||
## [Gall](/docs/userspace/threads/gall/)
|
||||
## [Gall](/guides/additional/threads/gall/)
|
||||
|
||||
Tutorial and explanation of interacting with threads from agents.
|
||||
|
||||
## [Examples](/docs/userspace/threads/examples/)
|
||||
## [Examples](/guides/additional/threads/examples/)
|
||||
|
||||
A collection of example threads and how-tos.
|
||||
|
||||
## [Reference](/docs/userspace/threads/reference)
|
||||
|
||||
Basic reference for interacting with threads via the Gall agent Spider.
|
||||
|
||||
@ -1,87 +0,0 @@
|
||||
+++
|
||||
title = "Reference"
|
||||
weight = 50
|
||||
template = "doc.html"
|
||||
+++
|
||||
|
||||
## Start thread
|
||||
|
||||
Poke `spider` with mark `%spider-start` and a vase containing `start-args`:
|
||||
|
||||
```hoon
|
||||
+$ start-args
|
||||
[parent=(unit tid) use=(unit tid) =beak file=term =vase]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `parent` - optional `tid` of parent thread if the thread is a child. If specified, the child thread will be killed with the parent thread ends.
|
||||
- `use` - `tid` (thread ID) to give the new thread. Can be generated with something like `(scot %ta (cat 3 'my-agent_' (scot %uv (sham eny))))`. However you do it, make sure it's unique.
|
||||
- `beak` - A `$beak` is a triple of `[p=ship q=desk r=case]`. `p` is always our ship, `q` is the desk which contains the thread we want to run. `r` is a `case`, which specifies a desk revision and is a tagged union of:
|
||||
```hoon
|
||||
+$ case
|
||||
$% [%da p=@da] :: date
|
||||
[%tas p=@tas] :: label
|
||||
[%ud p=@ud] :: number
|
||||
==
|
||||
```
|
||||
You'll almost always just want the current revision, so you can specify the `case` as `da+now.bowl`. If the thread is on the same desk as the agent you can also just use `byk.bowl(r da+now)` for the `beak`.
|
||||
- `file` - name of the thread file in `/ted`. For example, if the thread you want to start is `/ted/foo/hoon` you'd specify `%foo`.
|
||||
- `vase` - `vase` to be given to the thread when it's started. Can be whatever or just `!>(~)` if it doesn't need any args.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %poke %spider-start !>([~ `tid byk.bowl %foo !>(~)])]
|
||||
```
|
||||
|
||||
## Stop thread
|
||||
|
||||
Poke `spider` with mark `%spider-stop` and a vase containing `[tid ?]`, where:
|
||||
|
||||
- `tid` - the `tid` of the thread you want to stop
|
||||
- `?` - whether thread should end nicely. If `%.y` it'll end with mark `%thread-done` and the bunt value of a vase. If `%.n` it'll end with mark `%thread-fail` and a `[term tang]` where `term` is `%cancelled` and `tang` is `~`.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %poke %spider-stop !>([tid %.y)]
|
||||
```
|
||||
|
||||
## Subscribe for result
|
||||
|
||||
Spider will send the result on `/thread-result/[tid]` so you can subscribe there for the result. You should subscribe before starting the thread.
|
||||
|
||||
The result will have a mark of either `%thread-fail` or `%thread-done`.
|
||||
|
||||
- `%thread-fail` - has a vase containing a `[term tang]` where `term` is an error message and `tang` is a traceback.
|
||||
- `%thread-done` - has a vase of the result of the thread.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %watch /thread-result/[tid]]
|
||||
```
|
||||
|
||||
## Subscribe to thread
|
||||
|
||||
You can subscribe to a thread on `/thread/[tid]/path`. Note this is for facts sent off by the thread while it's running, not the final result. The path depends on the particular thread.
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %watch /thread/[tid]/thread-path]
|
||||
```
|
||||
|
||||
## Poke thread
|
||||
|
||||
To poke a thread you poke spider with a mark of `%spider-input` and a vase of `[tid cage]`.
|
||||
|
||||
- `tid` is the tid of the thread you want to poke
|
||||
- `cage` is whatever mark and vase you want to poke it with
|
||||
|
||||
#### Example
|
||||
|
||||
```hoon
|
||||
[%pass /some-path %agent [our.bowl %spider] %poke %spider-input !>([tid %foo !>('foooo')])]
|
||||
```
|
||||
@ -1,52 +1,52 @@
|
||||
+++
|
||||
title = "Full-Stack Walkthrough"
|
||||
title = "App School II (Full-Stack Walkthrough)"
|
||||
weight = 10
|
||||
sort_by = "weight"
|
||||
template = "sections/docs/chapters.html"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
||||
#### [1. Introduction](/docs/userspace/gall-2/1-intro)
|
||||
#### [1. Introduction](/guides/core/app-school-full-stack/1-intro)
|
||||
|
||||
An overview of the guide and table of contents.
|
||||
|
||||
#### [2. Types](/docs/userspace/gall-2/2-types)
|
||||
#### [2. Types](/guides/core/app-school-full-stack/2-types)
|
||||
|
||||
Creating the `/sur` structure file for our `%journal` agent.
|
||||
|
||||
#### [3. Agent](/docs/userspace/gall-2/3-agent)
|
||||
#### [3. Agent](/guides/core/app-school-full-stack/3-agent)
|
||||
|
||||
Creating the `%journal` agent itself.
|
||||
|
||||
#### [4. JSON](/docs/userspace/gall-2/5-json)
|
||||
#### [4. JSON](/guides/core/app-school-full-stack/5-json)
|
||||
|
||||
Writing a library to convert between our agent's marks and JSON. This lets our
|
||||
React front-end poke our agent, and our agent send updates back to it.
|
||||
|
||||
#### [5. Marks](/docs/userspace/gall-2/4-marks)
|
||||
#### [5. Marks](/guides/core/app-school-full-stack/4-marks)
|
||||
|
||||
Creating the mark files for the pokes our agent takes and updates it sends out.
|
||||
|
||||
#### [6. Eyre](/docs/userspace/gall-2/6-eyre)
|
||||
#### [6. Eyre](/guides/core/app-school-full-stack/6-eyre)
|
||||
|
||||
A brief overview of how the webserver vane Eyre works.
|
||||
|
||||
#### [7. React App Setup](/docs/userspace/gall-2/7-react-setup)
|
||||
#### [7. React App Setup](/guides/core/app-school-full-stack/7-react-setup)
|
||||
|
||||
Creating a new React app, installing the required packages, and setting up some
|
||||
basic things for our front-end.
|
||||
|
||||
#### [8. React App Logic](/docs/userspace/gall-2/8-http-api)
|
||||
#### [8. React App Logic](/guides/core/app-school-full-stack/8-http-api)
|
||||
|
||||
Analysing the core logic of our React app, with particular focus on using
|
||||
methods of the `Urbit` class from `@urbit/http-api` to communicate with our
|
||||
agent.
|
||||
|
||||
#### [9. Desk and Glob](/docs/userspace/gall-2/9-web-scries)
|
||||
#### [9. Desk and Glob](/guides/core/app-school-full-stack/9-web-scries)
|
||||
|
||||
Building and "globbing" our front-end, and putting together a desk for
|
||||
distribution.
|
||||
|
||||
#### [10. Summary](/docs/userspace/gall-2/10-final)
|
||||
#### [10. Summary](/guides/core/app-school-full-stack/10-final)
|
||||
|
||||
Some final comments and additional resources.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
+++
|
||||
title = "Gall Guide"
|
||||
title = "App School I"
|
||||
weight = 5
|
||||
sort_by = "weight"
|
||||
template = "sections/docs/chapters.html"
|
||||
@ -8,38 +8,38 @@ insert_anchor_links = "right"
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Introduction](/docs/userspace/gall-guide/intro)
|
||||
- [Introduction](guides/core/app-school/intro)
|
||||
|
||||
#### Lessons
|
||||
|
||||
1. [Arvo](/docs/userspace/gall-guide/1-arvo) - This lesson provides an
|
||||
1. [Arvo](guides/core/app-school/1-arvo) - This lesson provides an
|
||||
overview of the Arvo operating system, and some other useful background
|
||||
information.
|
||||
2. [The Agent Core](/docs/userspace/gall-guide/2-agent) - This lesson goes over
|
||||
2. [The Agent Core](guides/core/app-school/2-agent) - This lesson goes over
|
||||
the basic structure of a Gall agent.
|
||||
3. [Imports and Aliases](/docs/userspace/gall-guide/3-imports-and-aliases) -
|
||||
3. [Imports and Aliases](guides/core/app-school/3-imports-and-aliases) -
|
||||
This lesson covers some useful libraries, concepts and boilerplate commonly
|
||||
used when writing Gall agents.
|
||||
4. [Lifecycle](/docs/userspace/gall-guide/4-lifecycle) - This lesson introduces
|
||||
4. [Lifecycle](guides/core/app-school/4-lifecycle) - This lesson introduces
|
||||
the state management arms of an agent.
|
||||
5. [Cards](/docs/userspace/gall-guide/5-cards) - This lesson covers `card`s -
|
||||
5. [Cards](guides/core/app-school/5-cards) - This lesson covers `card`s -
|
||||
the structure used to pass messages to other agents and vanes.
|
||||
6. [Pokes](/docs/userspace/gall-guide/6-pokes) - This lesson covers sending and
|
||||
6. [Pokes](guides/core/app-school/6-pokes) - This lesson covers sending and
|
||||
receiving one-off messages called "pokes" between agents.
|
||||
7. [Structures and Marks](/docs/userspace/gall-guide/7-sur-and-marks) - This
|
||||
7. [Structures and Marks](guides/core/app-school/7-sur-and-marks) - This
|
||||
lesson talks about importing type defintions, and writing `mark` files.
|
||||
8. [Subscriptions](/docs/userspace/gall-guide/8-subscriptions) - This lesson
|
||||
8. [Subscriptions](guides/core/app-school/8-subscriptions) - This lesson
|
||||
goes through the mechanics of subscriptions - both inbound and outbound.
|
||||
9. [Vanes](/docs/userspace/gall-guide/9-vanes) - This lesson explains how to
|
||||
9. [Vanes](guides/core/app-school/9-vanes) - This lesson explains how to
|
||||
interact with vanes (kernel modules) from an agent.
|
||||
10. [Scries](/docs/userspace/gall-guide/10-scry) - This lesson gives an overview
|
||||
10. [Scries](guides/core/app-school/10-scry) - This lesson gives an overview
|
||||
of scrying Gall agents, and how scry endpoints are defined in agents.
|
||||
11. [Failure](/docs/userspace/gall-guide/11-fail) - This lesson covers how Gall
|
||||
11. [Failure](guides/core/app-school/11-fail) - This lesson covers how Gall
|
||||
handles certain errors and crashes, as well as the concept of a helper core.
|
||||
12. [Next Steps](/docs/userspace/gall-guide/12-next-steps) - The Gall Guide is
|
||||
12. [Next Steps](guides/core/app-school/12-next-steps) - The Gall Guide is
|
||||
now complete - here are some things you can look at next.
|
||||
|
||||
#### Appendix
|
||||
|
||||
- [Types](/docs/userspace/gall-guide/types) - A reference for a few of
|
||||
the types used in the Gall Guide.
|
||||
- [Types](guides/core/app-school/types) - A reference for a few of
|
||||
the types used in App School.
|
||||
|
||||
@ -180,6 +180,97 @@ The `++equ:rs` arm checks for complete equality of two values. The downside of
|
||||
|
||||
<img src="https://latex.codecogs.com/svg.image?\large&space;|a-b|&space;\leq&space;\texttt{atol}" title="https://latex.codecogs.com/svg.image?\large |a-b| \leq \texttt{atol}" />
|
||||
|
||||
#### Tutorial: Length Converter
|
||||
|
||||
- Write a generator to take a `@tas` input measurement unit of length, a `@rs` value, and a `@tas` output unit to which we will convert the input measurement. For instance, this generator could convert a number of imperial feet to metric decameters.
|
||||
|
||||
```hoon
|
||||
|= [fr-meas=@tas num=@rs to-meas=@tas]
|
||||
=<
|
||||
^- @rs
|
||||
?. (check fr-meas to-meas)
|
||||
~|("Invalid Measures" !!)
|
||||
(output (meters fr-meas num) to-meas)
|
||||
::
|
||||
|%
|
||||
+$ allowed ?(%inch %foot %yard %furlong %chain %link %rod %fathom %shackle %cable %nautical-mile %hand %span %cubit %ell %bolt %league %megalithic-yard %smoot %barleycorn %poppy-seed %atto %femto %pico %nano %micro %milli %centi %deci %meter %deca %hecto %kilo %mega %giga %tera %peta %exa)
|
||||
::
|
||||
++ check
|
||||
|= [fr-meas=@tas to-meas=@tas]
|
||||
&(?=(allowed fr-meas) ?=(allowed to-meas))
|
||||
::
|
||||
++ meters
|
||||
|= [in=@tas value=@rs]
|
||||
=/ factor-one
|
||||
(~(got by convert-to-map) in)
|
||||
(mul:rs value factor-one)
|
||||
::
|
||||
++ output
|
||||
|= [in=@rs out=@tas]
|
||||
?: =(out %meter)
|
||||
in
|
||||
(div:rs in (~(got by convert-to-map) out))
|
||||
::
|
||||
++ convert-to-map
|
||||
^- (map @tas @rs)
|
||||
%- malt
|
||||
^- (list [@tas @rs])
|
||||
:~ :- %atto .1e-18
|
||||
:- %femto .1e-15
|
||||
:- %pico .1e-12
|
||||
:- %nano .1e-8
|
||||
:- %micro .1e-6
|
||||
:- %milli .1e-3
|
||||
:- %poppy-seed .2.212e-2
|
||||
:- %barleycorn .8.47e-2
|
||||
:- %centi .1e-2
|
||||
:- %inch .2.54e-2
|
||||
:- %deci .1e-1
|
||||
:- %hand .1.016e-1
|
||||
:- %link .2.012e-1
|
||||
:- %span .2.228e-1
|
||||
:- %foot .3.048e-1
|
||||
:- %cubit .4.472e-1
|
||||
:- %megalithic-yard .8.291e-1
|
||||
:- %yard .9.145e-1
|
||||
:- %ell .1.143
|
||||
:- %smoot .1.7
|
||||
:- %fathom .1.83
|
||||
:- %rod .5.03
|
||||
:- %deca .1e1
|
||||
:- %chain .2.012e1
|
||||
:- %shackle .2.743e1
|
||||
:- %bolt .3.658e1
|
||||
:- %hecto .1e2
|
||||
:- %cable .1.8532e2
|
||||
:- %furlong .2.0117e2
|
||||
:- %kilo .1e3
|
||||
:- %mile .1.609e3
|
||||
:- %nautical-mile .1.850e3
|
||||
:- %league .4.830e3
|
||||
:- %mega .1e6
|
||||
:- %giga .1e8
|
||||
:- %tera .1e12
|
||||
:- %peta .1e15
|
||||
:- %exa .1e18
|
||||
:- %meter .1
|
||||
==
|
||||
--
|
||||
```
|
||||
|
||||
This program shows several interesting aspects, which we've covered before but highlight here:
|
||||
|
||||
- Meters form the standard unit of length.
|
||||
- [`~|` sigbar](https://urbit.org/docs/hoon/reference/rune/sig#-sigbar) produces an error message in case of a bad input.
|
||||
- [`+$` lusbuc](https://urbit.org/docs/hoon/reference/rune/lus#-lusbuc) is a type constructor arm, here for a type union over units of length.
|
||||
|
||||
#### Exercise: Measurement Converter
|
||||
|
||||
- Add to this generator the ability to convert some other measurement (volume, mass, force, or another of your choosing).
|
||||
- Add an argument to the cell required by the gate that indicates whether the measurements are distance or your new measurement.
|
||||
- Enforce strictly that the `fr-meas` and `to-meas` values are either lengths or your new type.
|
||||
- Create a new map of conversion values to handle your new measurement conversion method.
|
||||
- Convert the functionality into a library.
|
||||
|
||||
### `++rs` as a Door
|
||||
|
||||
|
||||
0
content/guides/quickstart/.gitkeep
Normal file
0
content/guides/quickstart/.gitkeep
Normal file
@ -7,37 +7,42 @@ template = "sections/docs/chapters.html"
|
||||
|
||||
Urbit is a clean-slate software stack designed to implement an encrypted P2P
|
||||
network of general-purpose personal servers. Each server on this network is a
|
||||
deterministic computer called an 'urbit' that runs on a Unix-based virtual
|
||||
deterministic computer called an ‘urbit’ that runs on a Unix-based virtual
|
||||
machine.
|
||||
|
||||
The Urbit stack primarily comprises:
|
||||
|
||||
- [Arvo](/docs/system-overview/arvo): the functional operating system of
|
||||
each urbit, written in Hoon.
|
||||
- [Hoon](/docs/system-overview/hoon): a strictly typed functional
|
||||
- [Arvo](/overview/arvo): the functional operating system of
|
||||
each Urbit instance, written in Hoon.
|
||||
- [Hoon](/overview/hoon): a strictly typed functional
|
||||
programming language whose standard library includes a Hoon-to-Nock compiler.
|
||||
- [Nock](/docs/system-overview/nock): a low-level combinator language whose
|
||||
- [Nock](/overview/nock): a low-level combinator language whose
|
||||
formal specification fits readably on a t-shirt.
|
||||
- [Vere](/docs/system-overview/vere): a Nock interpreter and Unix-based
|
||||
- [Vere](/overview/vere): a Nock interpreter and Unix-based
|
||||
virtual machine that mediates between each urbit and the Unix software layer.
|
||||
- [Azimuth](/docs/system-overview/azimuth): the Urbit identity layer, built
|
||||
on the Ethereum blockchain.
|
||||
- [Azimuth](/overview/azimuth): the Urbit identity layer, built
|
||||
on the Ethereum blockchain as a public-key infrastructure.
|
||||
- [Dojo](/overview/shell): the
|
||||
[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)
|
||||
command-line interface to your Urbit instance.
|
||||
|
||||
Central to the operation of Urbit are cryptographic methods. We give a
|
||||
high-level overview on the usage of cryptography in Urbit and how it is
|
||||
implemented [here](/docs/system-overview/cryptography).
|
||||
implemented [here](/overview/cryptography).
|
||||
|
||||
## Anatomy of a personal server
|
||||
|
||||
Your urbit is a deterministic computer in the sense that its state is a pure
|
||||
function of its event history. Every event in this history is a
|
||||
## Anatomy of a Personal Server
|
||||
|
||||
Your Urbit instance is a deterministic computer in the sense that its state is
|
||||
a pure function of its event history. Every event in this history is a
|
||||
[transaction](https://en.wikipedia.org/wiki/Transaction_processing); your
|
||||
urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).
|
||||
Urbit instance's state is effectively an
|
||||
[ACID database](https://en.wikipedia.org/wiki/ACID).
|
||||
|
||||
Because each urbit is deterministic we can describe its role appropriately in
|
||||
purely functional terms: it maps an input event and the old urbit state to a
|
||||
list of output actions and the subsequent state. This is the Urbit transition
|
||||
function.
|
||||
Because each Urbit instance is deterministic we can describe its role
|
||||
appropriately in purely functional terms: it maps an input event and the old
|
||||
Urbit instance's state to a list of output actions and the subsequent state.
|
||||
This is the Urbit transition function.
|
||||
|
||||
```
|
||||
<input event, old state> -> <output actions, new state>
|
||||
@ -47,31 +52,32 @@ For example, one input event could be a keystroke from the terminal, say
|
||||
`[enter]` after having already typed `(add 2 2)`; and an output action could be
|
||||
to print in the terminal window the resulting value of a computation performed
|
||||
when the user hit `[enter]`, in this case `4`. The input event is stored in the
|
||||
urbit's event history.
|
||||
Urbit instance's event history.
|
||||
|
||||
Events always start from outside of your urbit, whether they're local to the
|
||||
computer running the urbit (e.g., a keystroke in the terminal) or they originate
|
||||
elsewhere (e.g., a packet received from another urbit). When an event is
|
||||
processed, various parts of the urbit state can be modified before the resulting
|
||||
list of output actions is returned.
|
||||
Events always start from outside of your Urbit instance, whether they're local
|
||||
to the computer running the urbit (e.g., a keystroke in the terminal) or they
|
||||
originate elsewhere (e.g., a packet received from another Urbit instance). When
|
||||
an event is processed, various parts of the Urbit instance's state can be
|
||||
modified before the resulting list of output actions is returned.
|
||||
|
||||
Can output actions from your urbit cause side-effects in the outside world?
|
||||
The answer had better be "yes," because a personal server without side effects
|
||||
isn't useful for much. In another sense the answer had better be "no," or else
|
||||
there is a risk of losing functional purity; your urbit cannot _guarantee_ that
|
||||
the side effects in question actually occur. What's the solution?
|
||||
there is a risk of losing functional purity; your Urbit instance cannot
|
||||
_guarantee_ that the side effects in question actually occur. What's the
|
||||
solution?
|
||||
|
||||
Each urbit is
|
||||
[sandboxed](https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29) in a
|
||||
virtual machine, Vere, which runs on Unix. Code running in your urbit cannot
|
||||
make Unix system calls or otherwise directly affect the underlying platform.
|
||||
Strictly speaking, internal urbit code can only change internal urbit state; it
|
||||
Strictly speaking, internal Urbit code can only change internal Urbit state; it
|
||||
has no way of sending events outside of its runtime environment. Functional
|
||||
purity is preserved.
|
||||
|
||||
In practical terms, however, you don't want your urbit to be an impotent
|
||||
[brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why
|
||||
Vere also serves as the intermediary between your urbit and Unix. Vere observes
|
||||
the list of output events, and when external action is called for makes the
|
||||
appropriate system calls itself. When external events relevant to your urbit
|
||||
In practical terms, however, you don't want your Urbit instance to be an
|
||||
impotent [brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's
|
||||
why Vere also serves as the intermediary between your urbit and Unix. Vere
|
||||
observes the list of output events, and when external action is called for makes
|
||||
the appropriate system calls itself. When external events relevant to your Urbit
|
||||
occur in the Unix layer, Vere encodes and delivers them as input events.
|
||||
|
||||
343
content/overview/shell.md
Normal file
343
content/overview/shell.md
Normal file
@ -0,0 +1,343 @@
|
||||
+++
|
||||
title = "Shell"
|
||||
template = "doc.html"
|
||||
weight = 2
|
||||
+++
|
||||
|
||||
The Dojo is our shell; it processes system commands and returns output. It's a
|
||||
good place to quickly experiment with Urbit. On the surface the Dojo is just a
|
||||
Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
|
||||
data in Urbit.
|
||||
|
||||
### Quickstart
|
||||
|
||||
You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
|
||||
commands.
|
||||
|
||||
#### Math
|
||||
|
||||
Evaluate a Hoon expression (whitespace matters):
|
||||
|
||||
```
|
||||
~your-urbit:dojo> (add 2 2)
|
||||
~your-urbit:dojo> %+ add 2 2
|
||||
```
|
||||
|
||||
Tall-form Hoon may require multiple lines:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> %+ add
|
||||
~your-urbit:dojo< 2
|
||||
~your-urbit:dojo< 2
|
||||
```
|
||||
|
||||
Hoon uses something called [the subject](/docs/hoon/hoon-school/the-subject-and-its-legs).
|
||||
The Dojo has its own subject and that's where Hoon's equivalent of variables,
|
||||
called faces, are stored.
|
||||
|
||||
Use `=var` to save faces to the Dojo subject.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> =foo (add 2 2)
|
||||
```
|
||||
|
||||
Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
|
||||
face in a `.hoon` file in this way.
|
||||
|
||||
#### System commands
|
||||
|
||||
Use `=dir` to set the current working directory:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> =dir %/gen
|
||||
```
|
||||
|
||||
(`%` represents your current directory. For a complete explanation on urbit
|
||||
paths, see the [filesystem section](#filesystem).)
|
||||
|
||||
Generators (files in `/gen`) are run with `+`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> +hello 'world'
|
||||
```
|
||||
|
||||
Save output to a file in `%clay` with `*`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> *some/file/path/hoon 'hello world'
|
||||
```
|
||||
|
||||
Run system commands from `:hood`, like `reload`, using `|`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> |reload %eyre
|
||||
```
|
||||
|
||||
### Generators
|
||||
|
||||
Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
|
||||
directory. Many Dojo commands exist in the form of generators. The syntax for
|
||||
running a generator is `+genname` for a generator saved as `genname.hoon` in the
|
||||
`%base` desk. For generators on other desks, you can use the syntax
|
||||
`+desk!genname`.
|
||||
|
||||
#### `+cat`
|
||||
|
||||
Accepts a path and displays the file. Similar to Unix `cat`.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> +cat %/gen/curl/hoon
|
||||
```
|
||||
|
||||
#### `+code`
|
||||
|
||||
Generates a code that is used to remotely log into your ship. No
|
||||
arguments.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> +code
|
||||
```
|
||||
|
||||
You can change your code to a new randomly generated one by entering `|code %reset`. Please note that this will prevent [Bridge](/docs/glossary/bridge)
|
||||
from being able to derive your code in the future.
|
||||
|
||||
#### `+ls`
|
||||
|
||||
Similar to Unix `ls`. Accepts a path.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> +ls %/gen
|
||||
~your-urbit:dojo> +ls /~talsur-todres/base/2/gen/program
|
||||
```
|
||||
|
||||
#### `+solid`
|
||||
|
||||
Compile the current state of the kernel and output a noun. Usually downloaded to
|
||||
a file in unix. This generator takes a series of desks to include as its
|
||||
argument. The first desk must be the base desk that contains the Arvo kernel,
|
||||
standard library and related files - typically `%base`.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> .urbit/pill +solid %base %garden %landscape %webterm %bitcoin
|
||||
```
|
||||
|
||||
#### `+tree`
|
||||
|
||||
Generate a recursive directory listing. Takes a path.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> +tree %/sys
|
||||
```
|
||||
|
||||
### Hood
|
||||
|
||||
The hood is the system daemon. See `gen/hood` and `app/hood`.
|
||||
|
||||
`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
|
||||
an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
|
||||
|
||||
```
|
||||
~your-urbit:dojo> |hi ~binzod "you there?"
|
||||
```
|
||||
|
||||
`|link` / `|unlink` - Link / unlink a CLI app - may or may not be remote.
|
||||
Accepts an optional ship name and a mandatory app name.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> |link ~talsur-todres %octo
|
||||
|
||||
~your-urbit:dojo> |link %chat-cli
|
||||
```
|
||||
|
||||
`|mass` - Prints the current memory usage of all the kernel modules.
|
||||
No arguments.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> |mass
|
||||
```
|
||||
|
||||
`|breload` - Reloads a kernel module (vane) from source. Accepts any
|
||||
number of vane names.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> |breload %clay %eyre
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Dojo manual
|
||||
|
||||
#### Sources and sinks
|
||||
|
||||
A Dojo command is either a **source** or a **sink**. A source is just something
|
||||
that can be printed to your console or the result of some computation. A
|
||||
sink is an **effect**: a change to the filesystem, a network message, a
|
||||
change to your environment, or a typed message to an app.
|
||||
|
||||
Sources can be chained together, but we can only produce one effect per
|
||||
command.
|
||||
|
||||
#### Sinks
|
||||
|
||||
#### `=` - Set variable
|
||||
|
||||
Set any environment variable:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> =foo 42
|
||||
~your-urbit:dojo> (add 2 foo)
|
||||
|
||||
44
|
||||
```
|
||||
|
||||
Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
|
||||
variable in a `.hoon` file in this way.
|
||||
|
||||
#### Special variables
|
||||
|
||||
There are a few special variables that the Dojo maintains.
|
||||
|
||||
#### `:` - Send to app
|
||||
|
||||
`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
|
||||
|
||||
Send a `helm-hi` message to `hood`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> :hood &helm-hi 'hi'
|
||||
```
|
||||
|
||||
Apps usually expect marked data, so `&` is often used here.
|
||||
|
||||
#### `*` - Save in `%clay`
|
||||
|
||||
Save a new `.hoon` file in `gen`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> *%/gen/foo/hoon '# hello'
|
||||
```
|
||||
|
||||
The last component of the path is expected to be the mark (or mime
|
||||
type).
|
||||
|
||||
#### `.` - Export to Unix
|
||||
|
||||
Export a noun to Unix with `.`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> .foo/bar/baz (add 2 2)
|
||||
```
|
||||
|
||||
Which creates a file at `pier/.urb/put/foo/bar.baz`.
|
||||
|
||||
This is very often used with `+solid`:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> .urbit/pill +solid
|
||||
```
|
||||
|
||||
Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
|
||||
|
||||
### Sources
|
||||
|
||||
#### `_` - Run a function
|
||||
|
||||
Use `_` to run a gate (or function):
|
||||
|
||||
Write an arbitrary function and pass data to it:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
|
||||
9
|
||||
```
|
||||
|
||||
Use a function to get the status code from an http request:
|
||||
|
||||
```
|
||||
~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
|
||||
301
|
||||
```
|
||||
|
||||
#### `+` `-` - HTTP requests
|
||||
|
||||
`+http[s]://example.com` - sends a GET request
|
||||
|
||||
`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
|
||||
JSON `"hi"` in the body.
|
||||
|
||||
`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
|
||||
JSON `"hi"` in the body.
|
||||
|
||||
Note that the first of these is a source while the last two are sinks.
|
||||
|
||||
#### `+` - Generators
|
||||
|
||||
Generators are simple Hoon scripts loaded from the filesystem. They live
|
||||
in `gen/`.
|
||||
|
||||
An example of a generator that is built into your urbit is `+code`. It produces
|
||||
the code needed to log into your ship remotely.
|
||||
|
||||
```
|
||||
~your-urbit:dojo> +code
|
||||
fintyr-haldet-fassev-solhex
|
||||
```
|
||||
|
||||
Generators on desks other than `%base` can be run with the syntax
|
||||
`+desk!generator`.
|
||||
|
||||
### Variables
|
||||
|
||||
You can use `=` to set an environment variable in Dojo, but there are
|
||||
a few reserved names that have special uses.
|
||||
|
||||
#### `dir`
|
||||
|
||||
Current working `%clay` desk and revision. Read / write.
|
||||
|
||||
**Examples:**
|
||||
|
||||
```
|
||||
~your-urbit:dojo> =dir %/gen
|
||||
~your-urbit:dojo> +ls %
|
||||
404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
|
||||
```
|
||||
|
||||
#### `now`
|
||||
|
||||
The current (128-bit `@da`) time. Read-only.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
~your-urbit:dojo> now
|
||||
~2016.3.21..21.10.57..429a
|
||||
```
|
||||
|
||||
#### `our`
|
||||
|
||||
The current urbit ship. Read-only.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
~your-urbit:dojo> our
|
||||
~your-urbit
|
||||
```
|
||||
|
||||
#### `eny`
|
||||
|
||||
512 bits of entropy. Read-only.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
~your-urbit:dojo> eny
|
||||
0v27k.n4atp.fovm6.f7ggm.jdkn5.elct5.11tna.4qtid.g4so7.a1h6g.grp7u.qml4i.0ed1v.sl0r0.97d4b.6aepr.6v6qm.ls5ve.60kgb.j6521.2fqcb
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If you encounter `%dy-edit-busy` while entering commands, it is
|
||||
because your Dojo is blocked on a timer or an HTTP request. Type backspace
|
||||
and your Dojo will end the blocked command.
|
||||
Loading…
Reference in New Issue
Block a user