diff --git a/content/get-on-urbit.md b/content/get-on-urbit.md index 7c903766..352f10a5 100644 --- a/content/get-on-urbit.md +++ b/content/get-on-urbit.md @@ -278,7 +278,7 @@ For ease of portability the Urbit runtime has made a copy of itself in the `myco Spin up your comet again by running `mycomet/.run`, and you'll be back at the Dojo. -Comets don't receive software updates by default. If you intend on running this comet for a while and you want to receive updates, run `|ota` in the Dojo. +Comets don't receive software updates by default. If you intend on running this comet for a while and you want to receive updates, run `|ota (sein:title our now our)` in the Dojo. Next, you'll want to get the web login code so you can login to your Urbit's web interface in a browser. diff --git a/content/user-manual/os/dojo-tools.md b/content/user-manual/os/dojo-tools.md index 4ce51bdd..ff81930c 100644 --- a/content/user-manual/os/dojo-tools.md +++ b/content/user-manual/os/dojo-tools.md @@ -68,6 +68,39 @@ Try to apply update, suspending any incompatible desks: --- +### `|essential-desk` {#essential-desk} + +Mark a desk as essential, or unmark it. + +An essential desk is one the system will not suspend when a kernel update arrives. +Non-essential desks whose kelvin set does not include the incoming `%zuse` are +suspended so that the update can proceed; essential desks are left running. +The current setting is shown as the `essential desk` field in +[`+vats`](#vats) output. + +#### Arguments + +``` +desk, ? +``` + +Both arguments are positional: the desk, then a loobean — `&` to mark the desk +essential, `|` to unmark it. + +#### Examples + +``` +> |essential-desk %mydesk & +>= +``` + +``` +> |essential-desk %mydesk | +>= +``` + +--- + ### `|install` {#install} Install a desk, starting its agents and listening for updates. @@ -107,9 +140,14 @@ The default behaviour is to shut down the specified Gall agent and discard its s #### Arguments ``` -@tas, =desk ? +@tas, =desk ?, =hard ? ``` +`=hard &` **skips the confirmation prompt** and nukes immediately. Since `|nuke` +irreversibly discards agent state, this flag removes the only safeguard against a +mistyped agent or desk name; use it only in scripts where you have already +verified the argument. + #### Examples Nuke a single agent: @@ -258,15 +296,21 @@ The tile in the homescreen (if it has one) will turn gray and say "Suspended" in #### Arguments ``` -desk +(list desk) ``` +One or more desks may be given; they are all suspended together. + #### Examples ``` |suspend %bitcoin ``` +``` +|suspend %bitcoin %landscape +``` + --- ### `|uninstall` {#uninstall} @@ -297,88 +341,90 @@ Print out the status of each installed desk. Also see the related [`+vat`](#vat) command, which prints the status of a single desk rather than all desks. -Fields: +By default the output is terse. Passing `=verb &` prints the full detail. + +Fields shown in the default (terse) output: - `/sys/kelvin` - The kernel version(s) the desk is compatible with. +- `%cz hash ends in` - The last five characters of the desk hash. +- `essential desk` - `yes` or `no`; whether the desk is marked essential and so survives a kernel upgrade without being suspended. See [`|essential-desk`](#essential-desk). +- `app status` - One of `running`, `suspended`, or `suspended until next update`. +- `source ship` - The ship the desk updates from, or `~` for a local desk. +- `pending updates` - Updates waiting to be applied due to kernel incompatibility. +- `/desk/bill` - The desk's agent manifest, or `missing` if the desk has no `desk.bill`. + +Passing `=verb &` replaces `%cz hash ends in` and `/desk/bill` with the following +additional fields: + +- `%cz hash` - The full hash of the desk. - `base hash` - The merge base (common ancestor) between the desk and its upstream source. -- `%cz hash` - The hash of the desk. -- `app status` - May be `suspended` or `running`. - `force on` - The set of agents on the desk which have been manually started despite not being on the `desk.bill` manifest. - `force off` - The set of agents on the desk which have been manually stopped despite being on the `desk.bill` manifest. - `publishing ship` - The original publisher if the source ship is republishing the desk. -- `updates` - May be `local`, `remote` or `paused`. Local means it will receive updates via commits on the local ship. Remote means it will receive updates from the `source ship`. Paused means it will not receive updates. +- `updates` - Either `local` or `remote`. Local means it will receive updates via commits on the local ship; remote means it will receive updates from the `source ship`. - `source desk` - The desk on the `source ship`. - `source aeon` - The revision number of the desk on the `source ship`. -- `pending updates` - Updates waiting to be applied due to kernel incompatibility. +- `kids desk` - The desk published to the ship's children, if any. #### Arguments ``` -?(%suspended %running %blocking %nonexistent), =verb ?, =show-suspended ?, =show-running ?, =show-blocking ?, =show-nonexistent ? +(list desk), =filt ?(%running %suspended %exists %exists-not %blocking), =verb ? ``` All arguments are optional. -With no arguments, it prints verbose details for all desks. If the optional `.verb` argument is set to `|`, verbosity is reduced. - -It may optionally take one of four filters as a primary argument: +The positional argument is a list of desks; with none, every desk is reported. +Note that the filter is a *named* argument — `+vats %suspended` is parsed as a +desk named `%suspended` and reports `desk does not yet exist: %suspended`. -- `%suspended`: filter for suspended desks only. -- `%running`: filter for desks that are installed and running. -- `%blocking`: filter for desks that are blocking a kernel update due to incompatibility. -- `%nonexistent`: filter for desks we should have but don't yet. +- `=filt %running`: desks that are installed and running. +- `=filt %suspended`: suspended desks only. +- `=filt %exists`: desks that exist. +- `=filt %exists-not`: desks we should have but don't yet. +- `=filt %blocking`: desks blocking a kernel update due to incompatibility. This filter always reports all matching desks, even if a desk list was also given. -Alternatively, these filters can be *excluded* from the default output of everything by setting one or more of the `=show-*` arguments to `|`. +If both a desk list and a filter are given, the output is the desks in the list +that also match the filter — except for `%blocking`, as noted above. #### Examples -Print everything verbosely (no arguments): +Print all desks (default, terse): ``` > +vats - %base - /sys/kelvin: [%zuse 414] - base hash: 0v8.n40h1.hjn8c.e762q.ncgh0.e4gq3.6n3l5.5kt8l.6gtdr.ovbah.u3avd - %cz hash: 0v8.n40h1.hjn8c.e762q.ncgh0.e4gq3.6n3l5.5kt8l.6gtdr.ovbah.u3avd - app status: running - force on: ~ - force off: ~ - publishing ship: ~ - updates: local - source ship: ~ - source desk: ~ - source aeon: ~ - kids desk: ~ - pending updates: ~ +%base + /sys/kelvin: [%zuse 408] + %cz hash ends in: 71c37 + essential desk: yes + app status: running + source ship: ~ + pending updates: ~ + /desk/bill: ~[%acme %azimuth %dbug %dojo %eth-watcher %hood %herm %lens %ping %spider] :: - %landscape - /sys/kelvin: [%zuse 416] [%zuse 415] [%zuse 414] - base hash: ~ - %cz hash: 0v18.hnfi7.tps9t.0bv04.ikolg.ge98v.6f24v.a65m7.hlicn.rcl98.3skdu - app status: running - force on: ~ - force off: ~ - publishing ship: [~ ~lander-dister-dozzod-dozzod] - updates: remote - source ship: ~lander-dister-dozzod-dozzod - source desk: %landscape - source aeon: 0 - kids desk: ~ - pending updates: ~ +%webterm + /sys/kelvin: [%zuse 408] [%zuse 409] [%zuse 410] [%zuse 411] [%zuse 412] [%zuse 413] [%zuse 414] [%zuse 415] [%zuse 416] + %cz hash ends in: ge4a9 + essential desk: yes + app status: running + source ship: ~mister-dister-dozzod-dozzod + pending updates: ~ + /desk/bill: ~ :: ....... ``` -Print suspended desks: +Print a single desk with full detail: ``` -> +vats %suspended - %foo - /sys/kelvin: [%zuse 415] - base hash: 0vo.9f28r.java2.qnmqf.b3t1l.65mlu.8qsql.hq0cv.fpmdr.vuo1e.iehht - %cz hash: 0vo.9f28r.java2.qnmqf.b3t1l.65mlu.8qsql.hq0cv.fpmdr.vuo1e.iehht - app status: suspended +> +vats %base, =verb & +%base + /sys/kelvin: [%zuse 408] + base hash: 0v1f.8rfhf.gck0h.bdgic.td3kk.muapf.ett6q.q8sra.188jt.hlai3.71c37 + %cz hash: 0v1f.8rfhf.gck0h.bdgic.td3kk.muapf.ett6q.q8sra.188jt.hlai3.71c37 + essential desk: yes + app status: running force on: ~ force off: ~ publishing ship: ~ @@ -391,43 +437,23 @@ Print suspended desks: :: ``` -Print suspended desks with low verbosity: +Print only suspended desks. Note that the filter must be given as the named +argument `=filt`; a bare `+vats %suspended` would look for a *desk* called +`%suspended` and report `desk does not yet exist: %suspended`. ``` -> +vats %suspended, =verb | - %foo - /sys/kelvin: [%zuse 415] - app status: suspended - publishing ship: ~ - pending updates: ~ +> +vats, =filt %suspended +%testdesk + /sys/kelvin: [%zuse 408] + %cz hash ends in: vtk9h + essential desk: no + app status: suspended + source ship: ~ + pending updates: ~ + /desk/bill: missing :: ``` -Print everything with low verbosity except suspended desks and blocking desks: - -``` -> +vats, =verb |, =show-blocking |, =show-suspended | - %groups - /sys/kelvin: [%zuse 417] [%zuse 416] [%zuse 415] [%zuse 414] - app status: running - publishing ship: [~ ~sogryp-dister-dozzod-dozzod] - pending updates: ~ -:: - %base - /sys/kelvin: [%zuse 414] - app status: running - publishing ship: ~ - pending updates: ~ -:: - %landscape - /sys/kelvin: [%zuse 416] [%zuse 415] [%zuse 414] - app status: running - publishing ship: [~ ~lander-dister-dozzod-dozzod] - pending updates: ~ -:: -......... -``` - --- ### `+trouble` {#trouble} @@ -2094,14 +2120,22 @@ Create a new desk: The desk is now created in Clay. -Create a new desk from the `%base` desk: +Create a new desk, reading the template files from a desk other than the default: ``` > |new-desk %pahoehoe, =from %base >= ``` -The desk is now created in Clay and filled with the contents of `%base`. (Note that you would want to clear the `desk.bill` file or never `|install` such a desk, since the `%base` agents would be erroneously superseded.) +`=from` selects **which desk the template files are read from**; it does not copy +that desk. `|new-desk` always writes the same short, fixed file list — +`/mar/noun/hoon`, `/mar/hoon/hoon`, `/mar/txt/hoon`, `/mar/kelvin/hoon` and +`/sys/kelvin`, plus the extra Gall files if `=gall &` is given — and `=from` only +changes where those files are sourced. The default is already `%base`, so the +command above is equivalent to a bare `|new-desk %pahoehoe`. + +For comparison, on a fresh ship `%base` contains `{app sur gen lib mar ted desk sys}`, +while a desk created this way contains only `{mar sys}`. Create a new desk, overwriting any existing desk and including useful Gall files: diff --git a/content/user-manual/os/shell.md b/content/user-manual/os/shell.md index 7ba18677..465946cb 100644 --- a/content/user-manual/os/shell.md +++ b/content/user-manual/os/shell.md @@ -70,10 +70,10 @@ 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 `|`: +Run system commands from `:hood`, like `mass`, using `|`: ``` -~your-urbit:dojo> |reload %eyre +~your-urbit:dojo> |mass ``` ### Generators {#generators} @@ -147,12 +147,6 @@ The hood is the system daemon. See `gen/hood` and `app/hood`. ~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 {#dojo-manual} diff --git a/content/user-manual/os/updates.md b/content/user-manual/os/updates.md index e087b01e..6333c7d7 100644 --- a/content/user-manual/os/updates.md +++ b/content/user-manual/os/updates.md @@ -79,30 +79,38 @@ All apps you install (such as Groups, Studio, Pals, etc) specify the kernel vers This means that both the runtime and all apps must be up-to-date in order to apply a kernel update. If either of these conditions are not met, you will be notified in landscape as described in the [update notifications](updates.md#update-notifications) section above, and you will need to take the actions described. -If you have apps installed that simply don't have kernel-compatible updates available, you can force the kernel update by clicking the button in the notification [described above](updates.md#update-notifications), or by running `|bump, =force &` in the dojo. Doing so will suspend the incompatible apps until they receive compatible updates. +If you have apps installed that simply don't have kernel-compatible updates available, you can force the kernel update by clicking the button in the notification [described above](updates.md#update-notifications), or by running `|bump` in the dojo. Doing so will suspend the incompatible apps until they receive compatible updates. If the kernel update was blocked by an outdated runtime and you've since updated the runtime, you can tell it to try applying the update again by running `|bump` in the dojo. -To check if you have unapplied kernel updates queued, you can run `+vats %base` in the dojo. You'll see an output like this: +To check if you have unapplied kernel updates queued, you can run `+vats %base, =verb &` in the dojo. The `=verb &` is needed because the default output is terse and omits the `updates` entry. You'll see an output like this: ``` +> +vats %base, =verb & %base - /sys/kelvin: [%zuse 418] - base hash: 0vu.fptbs.6f05p.c9ghb.qfh7e.sbhum.vfnnr.osfs7.vv1i1.qveva.dfvli - %cz hash: 0vu.fptbs.6f05p.c9ghb.qfh7e.sbhum.vfnnr.osfs7.vv1i1.qveva.dfvli + /sys/kelvin: [%zuse 408] + base hash: 0v1f.8rfhf.gck0h.bdgic.td3kk.muapf.ett6q.q8sra.188jt.hlai3.71c37 + %cz hash: 0v1f.8rfhf.gck0h.bdgic.td3kk.muapf.ett6q.q8sra.188jt.hlai3.71c37 + essential desk: yes app status: running force on: ~ force off: ~ publishing ship: ~ - updates: tracking - source ship: ~marzod - source desk: %kids - source aeon: 8 + updates: local + source ship: ~ + source desk: ~ + source aeon: ~ + kids desk: ~ pending updates: ~ :: ``` -The `updates` entry says whether automatic updates are enabled. If it doesn't say `tracking`, you can run `|ota (sein:title our now our)` to enable them. The `pending updates` section will list any blocked updates, it'll look something like `~[[%zuse 417]]`. The `/sys/kelvin` line says the version it's currently on. +The `updates` entry is either `local` or `remote`. `remote` means the desk tracks +a `source ship` and receives updates from it; `local` means it has no upstream +source and only changes through commits on this ship. If `%base` says `local` and +you expected it to track your sponsor, run `|ota (sein:title our now our)`. The +`pending updates` section will list any blocked updates, it'll look something like +`~[[%zuse 407]]`. The `/sys/kelvin` line says the version it's currently on. ## App updates @@ -110,31 +118,33 @@ Apps (such as Groups, Studio, Pals, etc) receive OTA (over-the-air) updates from When there are kernel updates, app developers are encouraged to push updates for their apps before the kernel update itself is deployed. This means you'll probably see a bunch of notifications about app updates being blocked by the `%base` desk in the days before the kernel update ships. You don't need to worry about these - the updates will be queued and automatically applied when the kernel update arrives. -Sometimes, app developers may not get a kernel-compatible update out in time, or else they have simply stopped maintaining the app. In this case, such apps will block kernel updates, and you'll see the "The following (n) apps blocked a System Update" notification [described above](updates.md#update-notifications). In this case, the app will need to be suspended in order for the kernel update to complete. You can do this either by clicking the button in that notification or running `|bump, =force &` in the dojo. You should not manually suspend apps via their tile menu or the `|suspend` command, because they will not be automatically revived if they later receive a kernel-compatible update. +Sometimes, app developers may not get a kernel-compatible update out in time, or else they have simply stopped maintaining the app. In this case, such apps will block kernel updates, and you'll see the "The following (n) apps blocked a System Update" notification [described above](updates.md#update-notifications). In this case, the app will need to be suspended in order for the kernel update to complete. You can do this either by clicking the button in that notification or running `|bump` in the dojo. You should not manually suspend apps via their tile menu or the `|suspend` command, because they will not be automatically revived if they later receive a kernel-compatible update. Automatic app updates can be paused with the `|pause %the-desk` command in the dojo. The desk name may differ from the app name - you can find the desk name by clicking on "App Info" in the app tile's hamburger menu and looking for the "Installed into" entry. -To check the update status of an app, you can run the `+vats %the-desk` command in the dojo. It will give you a print-out like this: +To check the update status of an app, you can run the `+vats %the-desk, =verb &` command in the dojo. It will give you a print-out like this: ``` -> +vats %docs -%docs - /sys/kelvin: [%zuse 418] - base hash: 0vu.moe96.kmq1d.a0nen.76vf6.t5qbc.aokqv.89fg5.avctv.pvq08.pdio0 - %cz hash: 0vu.moe96.kmq1d.a0nen.76vf6.t5qbc.aokqv.89fg5.avctv.pvq08.pdio0 +> +vats %webterm, =verb & +%webterm + /sys/kelvin: [%zuse 408] [%zuse 409] [%zuse 410] [%zuse 411] [%zuse 412] [%zuse 413] [%zuse 414] [%zuse 415] [%zuse 416] + base hash: ~ + %cz hash: 0v5.vqi3m.o4jpl.8i5tk.qn4h3.5272h.tie2f.degcr.ptngr.cnjbl.ge4a9 + essential desk: yes app status: running force on: ~ force off: ~ - publishing ship: ~ - updates: tracking - source ship: ~pocwet - source desk: %docs - source aeon: 30 + publishing ship: ~mister-dister-dozzod-dozzod + updates: remote + source ship: ~mister-dister-dozzod-dozzod + source desk: %webterm + source aeon: 0 + kids desk: ~ pending updates: ~ :: ``` -If there are `pending updates`, it usually means they're waiting for a kernel update before they can be applied. The `updates` entry tells you whether automatic updates are enabled. +If there are `pending updates`, it usually means they're waiting for a kernel update before they can be applied. The `updates` entry is `remote` when the desk tracks a `source ship`, and `local` when it does not. ## Further reading