mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
Merge pull request #309 from urbit/i/290/fix-software-dist-tutorial
fix and update software dist guide
This commit is contained in:
Sigilante
GitHub
commit
d906f530cb
@ -6,62 +6,104 @@ weight = 98
|
||||
|
||||
In this document we'll walk through an example of creating and publishing a desk that others can install. We'll create a simple "Hello World!" front-end with a "Hello" tile to launch it. For simplicity, the desk won't include an actual Gall agent, but we'll note everything necessary if there were one.
|
||||
|
||||
## Install binary
|
||||
|
||||
*Note: You can skip this step if you already have the latest binary installed.*
|
||||
|
||||
Follow the [CLI install
|
||||
instructions](https://urbit.org/getting-started/cli#2-install-urbit) appropriate
|
||||
for your OS to download the `urbit` binary.
|
||||
|
||||
## Spin up fake ship
|
||||
|
||||
*Note: You can skip this step if you already have a fake `zod`.*
|
||||
|
||||
With the `urbit` binary installed, run the following in the terminal to spin up
|
||||
a fake `zod`:
|
||||
|
||||
```sh
|
||||
./urbit -F zod
|
||||
```
|
||||
|
||||
It will take a couple of minutes to spin up, but it should eventually take you
|
||||
to a Dojo prompt like:
|
||||
|
||||
```
|
||||
~zod:dojo>
|
||||
```
|
||||
|
||||
## Create desk
|
||||
|
||||
To begin, we'll need to clone the [Urbit OS repo](https://github.com/urbit/urbit) from the Unix terminal:
|
||||
In the Dojo of your fake `zod`, run the following to create a new desk called `%hello`:
|
||||
|
||||
```sh
|
||||
[user@host ~]$ git clone https://github.com/urbit/urbit urbit-git
|
||||
```
|
||||
|new-desk %hello
|
||||
```
|
||||
|
||||
Once that's done, we can navigate to the `pkg` directory in our cloned repo:
|
||||
If you now run `+tree` on the desk, you'll see it now exists and has a handful
|
||||
of files in it:
|
||||
|
||||
```sh
|
||||
[user@host ~]$ cd urbit-git/pkg
|
||||
[user@host pkg]$ ls .
|
||||
arvo btc-wallet garden grid interface npm webterm
|
||||
base-dev docker-image garden-dev herb landscape symbolic-merge.sh
|
||||
bitcoin ent ge-additions hs libaes_siv urbit
|
||||
```
|
||||
> +tree /=hello=
|
||||
/mar/hoon/hoon
|
||||
/mar/kelvin/hoon
|
||||
/mar/noun/hoon
|
||||
/mar/txt/hoon
|
||||
/sys/kelvin
|
||||
```
|
||||
|
||||
Each desk defines its own `mark`s, in its `/mar` folder. There are no longer shared system marks that all userspace code knows, nor common libraries in `/lib` or `/sur`. Each desk is completely self-contained. This means any new desk will need a number of base files.
|
||||
## Copy in extra files
|
||||
|
||||
To make the creation of a new desk easier, `base-dev` and `garden-dev` contain symlinks to all `/sur`, `/lib` and `/mar` files necessary for interacting with the `%base` and `%garden` desks respectively. These dev desks can be copied and merged with the `symbolic-merge.sh` included.
|
||||
Each desk must be self-contained in terms of its `mark` files and libraries.
|
||||
There's a couple of extra mark files and such that we'll need to add, so run the
|
||||
following commands in the Dojo:
|
||||
|
||||
Let's create a new `hello` desk:
|
||||
```
|
||||
|cp %/mar/mime/hoon /=hello=/mar/mime/hoon
|
||||
|cp %/mar/txt-diff/hoon /=hello=/mar/txt-diff/hoon
|
||||
|cp %/mar/ship/hoon /=hello=/mar/ship/hoon
|
||||
|cp %/mar/bill/hoon /=hello=/mar/bill/hoon
|
||||
|cp /=garden=/mar/docket-0/hoon /=hello=/mar/docket-0/hoon
|
||||
|cp /=garden=/sur/docket/hoon /=hello=/sur/docket/hoon
|
||||
|cp /=garden=/lib/docket/hoon /=hello=/lib/docket/hoon
|
||||
```
|
||||
|
||||
## Mount the desk
|
||||
|
||||
Now we have all the basic files we need, we can mount the desk to the host. Run the following in the Dojo:
|
||||
|
||||
```
|
||||
|mount %hello
|
||||
```
|
||||
|
||||
Now, in an ordinary terminal (not the Dojo), navigate to the mounted desk:
|
||||
|
||||
```sh
|
||||
[user@host pkg]$ mkdir hello
|
||||
[user@host pkg]$ ./symbolic-merge.sh base-dev hello
|
||||
[user@host pkg]$ ./symbolic-merge.sh garden-dev hello
|
||||
[user@host pkg]$ cd hello
|
||||
[user@host hello]$ ls
|
||||
lib mar sur
|
||||
cd zod/hello
|
||||
```
|
||||
|
||||
## Config files
|
||||
|
||||
### `sys.kelvin`
|
||||
|
||||
Our desk must include a `sys.kelvin` file which specifies the kernel version it's compatible with. Let's create that:
|
||||
|
||||
```sh
|
||||
[user@host hello]$ echo "[%zuse 417]" > sys.kelvin
|
||||
[user@host hello]$ cat sys.kelvin
|
||||
[%zuse 417]
|
||||
```
|
||||
Our desk must include a `sys.kelvin` file which specifies the kernel version
|
||||
it's compatible with. The `|new-desk` generator automatically added that, so we
|
||||
can leave it as-is.
|
||||
|
||||
### `desk.ship`
|
||||
|
||||
We can also add a `desk.ship` file to specify the original publisher of this desk. We'll try this on a fakezod so let's just add `~zod` as the publisher:
|
||||
We can optionally add a `desk.ship` file to specify the original publisher of
|
||||
this desk. We're using a fake `zod` so let's just add `~zod` as the publisher:
|
||||
|
||||
```sh
|
||||
[user@host hello]$ echo "~zod" > desk.ship
|
||||
[user@host hello]$ cat desk.ship
|
||||
~zod
|
||||
echo "~zod" > desk.ship
|
||||
```
|
||||
|
||||
### `desk.bill`
|
||||
|
||||
If we had Gall agents in this desk which should be automatically started when the desk is installed, we'd add them to a `hoon` list in the `desk.bill` file. It would look something like this:
|
||||
If we had Gall agents in this desk which should be automatically started when
|
||||
the desk is installed, we'd add them to a `hoon` list in the `desk.bill` file.
|
||||
It would look something like this:
|
||||
|
||||
```hoon
|
||||
:~ %some-app
|
||||
@ -73,15 +115,16 @@ In this example we're not adding any agents, so we'll simply omit the `desk.bill
|
||||
|
||||
### `desk.docket-0`
|
||||
|
||||
The final file we need is `desk.docket-0`. This one's more complicated, so we'll open it in our preferred text editor:
|
||||
The final file we need is `desk.docket-0`. This one's more complicated, so we'll
|
||||
open it in our preferred text editor:
|
||||
|
||||
```
|
||||
[user@host hello]$ nano desk.docket-0
|
||||
```sh
|
||||
nano desk.docket-0
|
||||
```
|
||||
|
||||
In the text editor, we'll add the following:
|
||||
|
||||
```hoon
|
||||
|
||||
:~ title+'Hello'
|
||||
info+'A simple hello world app.'
|
||||
color+0x81.88c9
|
||||
@ -89,106 +132,118 @@ In the text editor, we'll add the following:
|
||||
base+'hello'
|
||||
glob-ames+[~zod 0v0]
|
||||
version+[0 0 1]
|
||||
website+'https://developers.urbit.org/guides/additional/dist/guide'
|
||||
website+'https://developers.urbit.org/guides/additional/software-distribution'
|
||||
license+'MIT'
|
||||
==
|
||||
```
|
||||
|
||||
You can refer to the [Docket File](/reference/additional/dist/docket) documentation for more details of what is required. In brief, the `desk.docket-0` file contains a `hoon` list of [clauses](/reference/additional/dist/docket) which configure the appearance of the app tile, the source of the [glob](/reference/additional/dist/glob), and some other metadata.
|
||||
You can refer to the [Docket File](/reference/additional/dist/docket)
|
||||
documentation for more details of what is required. In brief, the
|
||||
`desk.docket-0` file contains a `hoon` list of
|
||||
[clauses](/reference/additional/dist/docket) which configure the appearance of
|
||||
the app tile, the source of the [glob](/reference/additional/dist/glob), and
|
||||
some other metadata.
|
||||
|
||||
We've given the app a [`%title`](/reference/additional/dist/docket#title) of "Hello", which will be displayed on the app tile and will be the name of the app when others browse to install it. We've given the app tile a [`%color`](/reference/additional/dist/docket#color) of `#8188C9`, and also specified the URL of an [`%image`](/reference/additional/dist/docket#image) to display on the tile.
|
||||
We've given the app a [`%title`](/reference/additional/dist/docket#title) of
|
||||
"Hello", which will be displayed on the app tile and will be the name of the app
|
||||
when others browse to install it. We've given the app tile a
|
||||
[`%color`](/reference/additional/dist/docket#color) of `#8188C9`, and also
|
||||
specified the URL of an [`%image`](/reference/additional/dist/docket#image) to
|
||||
display on the tile.
|
||||
|
||||
The [`%base`](/reference/additional/dist/docket#base) clause specifies the base URL path for the app. We've specified "hello" so it'll be `http://localhost:8080/apps/hello/...` in the browser. For the [glob](/reference/additional/dist/glob), we've used a clause of [`%glob-ames`](/reference/additional/dist/docket#glob-ames), which means the glob will be served from a ship over Ames, as opposed to being served over HTTP with a [`%glob-http`](/reference/additional/dist/docket#glob-http) clause or having an Eyre binding with a [`%site`](/reference/additional/dist/docket#site) clause. You can refer to the [glob](/reference/additional/dist/glob) documentation for more details of the glob options. In our case we've specified `[~zod 0v0]`. Since `~zod` is the fakeship we'll install it on, the `%docket` agent will await a separate upload of the `glob`, so we can just specify `0v0` here as it'll get overwritten later.
|
||||
The [`%base`](/reference/additional/dist/docket#base) clause specifies the base
|
||||
URL path for the app. We've specified "hello" so it'll be
|
||||
`http://localhost:8080/apps/hello/...` in the browser. For the
|
||||
[glob](/reference/additional/dist/glob), we've used a clause of
|
||||
[`%glob-ames`](/reference/additional/dist/docket#glob-ames), which means the
|
||||
glob will be served from a ship over Ames, as opposed to being served over HTTP
|
||||
with a [`%glob-http`](/reference/additional/dist/docket#glob-http) clause or
|
||||
having an Eyre binding with a [`%site`](/reference/additional/dist/docket#site)
|
||||
clause. You can refer to the [glob](/reference/additional/dist/glob)
|
||||
documentation for more details of the glob options. In our case we've specified
|
||||
`[~zod 0v0]`. Since `~zod` is the fakeship we'll install it on, the `%docket`
|
||||
agent will await a separate upload of the `glob`, so we can just specify `0v0`
|
||||
here as it'll get overwritten later.
|
||||
|
||||
The [`%version`](/reference/additional/dist/docket#version) clause specifies the version as a triple of major version, minor version and patch version. The rest is just some additional informative metadata which will be displayed in _App Info_.
|
||||
The [`%version`](/reference/additional/dist/docket#version) clause specifies the
|
||||
version as a triple of major version, minor version and patch version. The rest
|
||||
is just some additional informative metadata which will be displayed in _App
|
||||
Info_.
|
||||
|
||||
So let's save that to the `desk.docket-0` file and have a look at our desk:
|
||||
|
||||
```
|
||||
[user@host hello]$ ls
|
||||
```sh
|
||||
ls
|
||||
desk.docket-0 desk.ship lib mar sur sys.kelvin
|
||||
```
|
||||
|
||||
That's everything we need for now.
|
||||
## Commit
|
||||
|
||||
Now we've added out configuration files, we can commit them to the desk. Back in
|
||||
the fake `zod`'s Dojo, run the following:
|
||||
|
||||
```
|
||||
|commit %hello
|
||||
```
|
||||
|
||||
You should see something like this as the result:
|
||||
|
||||
```
|
||||
>=
|
||||
+ /~zod/hello/9/desk/ship
|
||||
+ /~zod/hello/9/desk/docket-0
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
Let's spin up a fakezod in which we can install our desk. By default a fakezod will be out of date, so we need to bootstrap with a pill from our urbit-git repo. The pills are stored in git lfs and need to be pulled into our repo first:
|
||||
The next step is to install the desk as an app. Run the following in the Dojo:
|
||||
|
||||
```
|
||||
[user@host hello]$ cd ~/urbit-git
|
||||
[user@host urbit-git]$ git lfs install
|
||||
[user@host urbit-git]$ git lfs pull
|
||||
[user@host urbit-git]$ cd ~/piers/fake
|
||||
[user@host fake]$ urbit -F zod -B ~/urbit-git/bin/multi-brass.pill
|
||||
|install our %hello
|
||||
```
|
||||
|
||||
Once our fakezod is booted, we'll need to create a new `%hello` desk for our app and mount it. We can do this in the dojo like so:
|
||||
You should see a message like:
|
||||
|
||||
```
|
||||
> |merge %hello our %base
|
||||
>=
|
||||
> |mount %hello
|
||||
>=
|
||||
```
|
||||
|
||||
Now, back in the Unix terminal, we should see the new desk mounted:
|
||||
|
||||
```
|
||||
[user@host fake]$ cd zod
|
||||
[user@host zod]$ ls
|
||||
hello
|
||||
```
|
||||
|
||||
Currently it's just a clone of the `%base` desk, so let's delete its contents:
|
||||
|
||||
```
|
||||
[user@host zod]$ rm -r hello/*
|
||||
```
|
||||
|
||||
Next, we'll copy in the contents of the `hello` desk we created earlier. We must use `cp -LR` to resolve all the symlinks:
|
||||
|
||||
```
|
||||
[user@host zod]$ cp -LR ~/urbit-git/pkg/hello/* hello/
|
||||
```
|
||||
|
||||
Back in the dojo we can commit the changes and install the desk:
|
||||
|
||||
```
|
||||
> |commit %hello
|
||||
> |install our %hello
|
||||
kiln: installing %hello locally
|
||||
docket: awaiting manual glob for %hello desk
|
||||
```
|
||||
|
||||
The `docket: awaiting manual glob for %hello desk` message is because our `desk.docket-0` file includes a [`%glob-ames`](/reference/additional/dist/docket#glob-ames) clause which specifies our ship as the source, so it's waiting for us to upload the glob.
|
||||
|
||||
If we open a browser now, navigate to `http://localhost:8080` and login with the default fakezod code `lidlut-tabwed-pillex-ridrup`, we'll see our tile's appeared but it says "installing" with a spinner due to the missing glob:
|
||||
|
||||
|
||||
That's because our `desk.docket-0` file includes a
|
||||
[`%glob-ames`](/reference/additional/dist/docket#glob-ames) clause which
|
||||
specifies our ship as the source, so it's waiting for us to upload the glob of
|
||||
front-end files.
|
||||
|
||||
## Create files for glob
|
||||
|
||||
We'll now create the files for the glob. We'll use a very simple static HTML page that just displayes "Hello World!" and an image. Typically we'd have a more complex JS web app that talked to apps on our ship through Eyre's channel system, but for the sake of simplicity we'll forgo that. Let's hop back in the Unix terminal:
|
||||
We'll now create the files for the glob. We'll use a very simple static HTML
|
||||
page that just displayes "Hello World!" and an image. Typically we'd have a more
|
||||
complex JS web app that talked to apps on our ship through Eyre's channel
|
||||
system, but for the sake of simplicity we'll forgo that. Let's hop back in the
|
||||
Unix terminal and run a few commands:
|
||||
|
||||
```sh
|
||||
cd ~
|
||||
mkdir hello-glob
|
||||
cd hello-glob
|
||||
mkdir img
|
||||
wget -P img https://media.urbit.org/guides/additional/dist/pot.svg
|
||||
```
|
||||
|
||||
We should now have the following file structure in our home directory:
|
||||
|
||||
```
|
||||
[user@host zod]$ cd ~
|
||||
[user@host ~]$ mkdir hello-glob
|
||||
[user@host ~]$ cd hello-glob
|
||||
[user@host hello-glob]$ mkdir img
|
||||
[user@host hello-glob]$ wget -P img https://media.urbit.org/guides/additional/dist/pot.svg
|
||||
[user@host hello-glob]$ tree
|
||||
.
|
||||
hello-glob
|
||||
└── img
|
||||
└── pot.svg
|
||||
|
||||
1 directory, 1 file
|
||||
```
|
||||
|
||||
We've grabbed an image to use in our "Hello world!" page. The next thing we need to add is an `index.html` file in the root of the folder. The `index.html` file is mandatory; it's what will be loaded when the app's tile is clicked. Let's open our preferred editor and create it:
|
||||
We've grabbed an image to use in our "Hello world!" page. The next thing we need
|
||||
to add is an `index.html` file in the root of the folder. The `index.html` file
|
||||
is mandatory; it's what will be loaded when the app's tile is clicked. Let's
|
||||
open our preferred editor and create it:
|
||||
|
||||
```
|
||||
[user@host hello-glob]$ nano index.html
|
||||
```sh
|
||||
nano index.html
|
||||
```
|
||||
|
||||
In the editor, paste in the following HTML and save it:
|
||||
@ -216,67 +271,90 @@ In the editor, paste in the following HTML and save it:
|
||||
Our `hello-glob` folder should now look like this:
|
||||
|
||||
```
|
||||
[user@host hello-glob]$ tree
|
||||
.
|
||||
hello-glob
|
||||
├── img
|
||||
│ └── pot.svg
|
||||
└── index.html
|
||||
|
||||
1 directory, 2 files
|
||||
```
|
||||
|
||||
## Login to Landscape
|
||||
|
||||
Open a web browser and navigate to `localhost:8080`, or just `localhost` if port
|
||||
`8080` doesn't work. It should take you to the fake `zod`'s login screen. Login
|
||||
with the default code of `lidlut-tabwed-pillex-ridrup`.
|
||||
|
||||
Once you login, you'll notice you have the `Hello` app tile, but it still says
|
||||
"installing" because we haven't uploaded the glob yet:
|
||||
|
||||
|
||||
|
||||
## Upload to glob
|
||||
|
||||
We can now create a glob from the directory. To do so, navigate to `http://localhost:8080/docket/upload` in the browser. This will bring up the `%docket` app's [Globulator](/reference/additional/dist/glob#globulator) tool:
|
||||
We can now create a glob from the `hello-glob` directory we previously created.
|
||||
To do so, navigate to `http://localhost:8080/docket/upload` in the browser. This
|
||||
will bring up the `%docket` app's
|
||||
[Globulator](/reference/additional/dist/glob#globulator) tool:
|
||||
|
||||
|
||||
|
||||
|
||||
Simply select the `hello` desk from the drop-down, click `Choose file` and select the `hello-glob` folder in the the file browser, then hit `glob!`.
|
||||
Simply select the `hello` desk from the drop-down, click `Choose file` and
|
||||
select the `hello-glob` folder in the the file browser, then hit `glob!`.
|
||||
|
||||
Now if we return to our ship's homescreen, we should see the tile looks as we specified in the docket file:
|
||||
Now if we return to our ship's homescreen, we should see the tile looks as we
|
||||
specified in the docket file:
|
||||
|
||||
|
||||
|
||||
|
||||
And if we click on the tile, it'll load the `index.html` in our glob:
|
||||
|
||||
|
||||
|
||||
|
||||
Our app is working!
|
||||
|
||||
## Publish
|
||||
|
||||
The final step is publishing our desk with the `%treaty` agent so others can install it. To do this, there's a simple command in the dojo:
|
||||
The final step is publishing our desk with the `%treaty` agent so others can
|
||||
install it. To do this, there's a simple command in the dojo:
|
||||
|
||||
```
|
||||
> :treaty|publish %hello
|
||||
>=
|
||||
```
|
||||
|
||||
Note: For desks without a docket file (and therefore without a tile and glob), treaty can't be used. Instead you can make the desk public with `|public %desk-name`.
|
||||
Note: For desks without a docket file (and therefore without a tile and glob),
|
||||
treaty can't be used. Instead you can make the desk public with `|public
|
||||
%desk-name`.
|
||||
|
||||
## Remote install
|
||||
|
||||
Let's spin up another fake ship so we can try install it:
|
||||
Let's spin up another fake ship in the terminal so we can try install it:
|
||||
|
||||
```
|
||||
[user@host hello-glob]$ cd ~/piers/fake
|
||||
[user@host fake]$ urbit -F bus
|
||||
```sh
|
||||
cd ~
|
||||
./urbit -F bus
|
||||
```
|
||||
|
||||
Note: For desks without a docket file (and therefore without a tile and glob), users cannot install them through the web interface. Instead remote users can install it from the dojo with `|install ~our-ship %desk-name`.
|
||||
Note: For desks without a docket file (and therefore without a tile and glob),
|
||||
users cannot install them through the web interface. Instead remote users can
|
||||
install it from the dojo with `|install ~our-ship %desk-name`.
|
||||
|
||||
In the browser, navigate to `http://localhost:8081` and login with `~bus`'s code `riddec-bicrym-ridlev-pocsef`. Next, type `~zod/` in the search bar, and it should pop up a list of `~zod`'s published apps, which in this case is our `Hello` app:
|
||||
In the browser, navigate to `localhost:8081` (or `localhost:8080` if that
|
||||
doesn't work) and login with `~bus`'s code `riddec-bicrym-ridlev-pocsef`. Next,
|
||||
type `~zod` in the search bar and click on the matching result. It should pop up
|
||||
a list of `zod`'s published apps, which in this case is our `Hello` app:
|
||||
|
||||
|
||||
|
||||
|
||||
When we click on the app, it'll show some of the information from the clauses in the docket file:
|
||||
When we click on the app, it'll show some of the information from the clauses in
|
||||
the docket file:
|
||||
|
||||
|
||||
|
||||
|
||||
Click `Get App` and it'll ask as if we want to install it:
|
||||
|
||||
|
||||
|
||||
|
||||
Finally, click `Get "Hello"` and it'll be installed as a tile on `~bus` which can then be opened:
|
||||
Finally, click `Get "Hello"` and it'll be installed as a tile on `~bus` which
|
||||
can then be opened:
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user