git.iko.soy/urbit.org
on master help sign in
add mount management doc
4da6b7etinnus-napbus
arvo/clay/_index.md+4
compare with master
unifiedsplit
@@ -34,3 +34,7 @@ How to read files and subscribe for changes.
34[Write and Modify](@/docs/arvo/clay/write.md)
34[Write and Modify](@/docs/arvo/clay/write.md)
35
35
36How to add, delete and modify files.
36How to add, delete and modify files.
37+
38+[Manage Mounts](@/docs/arvo/clay/mounts.md)
39+
40+How to manage clay unix mounts programmatically.
arvo/clay/clay.md+4
@@ -63,3 +63,7 @@ How to read files and subscribe for changes.
63[Write and Modify](@/docs/arvo/clay/write.md)
63[Write and Modify](@/docs/arvo/clay/write.md)
64
64
65How to add, delete and modify files.
65How to add, delete and modify files.
66+
67+[Manage Mounts](@/docs/arvo/clay/mounts.md)
68+
69+How to manage clay unix mounts programmatically.
arvo/clay/mounts.mdnew file+195
@@ -0,0 +1,195 @@
1++++
2+title = "Manage Mounts"
3+weight = 8
4+template = "doc.html"
5++++
6+
7+Here we'll look at managing clay unix mounts programmatically.
8+
9+## Contents
10+
11+There are four `task:clay` tags relevant to mounts:
12+
13+- [%boat](#boat) - List mounts.
14+- [%mont](#mont) - Mount something.
15+- [%ogre](#ogre) - Unmount something.
16+- [%dirk](#dirk) - Commit changes.
17+
18+## %boat
19+
20+This type of `task:clay` will request the list of existing mounts. It looks like:
21+
22+```hoon
23+[%boat ~]
24+```
25+
26+Pretty simple. The type it returns is a `%hill` tagged `gift:clay`, which looks like:
27+
28+```hoon
29+[%hill p=(list @tas)]
30+```
31+
32+...where the `@tas` is the name of the mount point.
33+
34+Example:
35+
36+Here's a thread that sends a `task:clay` and takes a `gift:clay` in response:
37+
38+**`send-task-take-gift.hoon`**
39+
40+```hoon
41+/- spider
42+/+ strandio
43+=, strand=strand:spider
44+^- thread:spider
45+|= arg=vase
46+=/ m (strand ,vase)
47+^- form:m
48+=/ uarg !< (unit task:clay) arg
49+?~ uarg
50+ (strand-fail:strand %no-arg ~)
51+=/ =task:clay u.uarg
52+=/ =card:agent:gall [%pass /foo %arvo %c task]
53+;< ~ bind:m (send-raw-card:strandio card)
54+;< res=[wire sign-arvo] bind:m take-sign-arvo:strandio
55+~& +>:res
56+(pure:m !>(~))
57+```
58+
59+Save it to `ted/send-task-take-gift.hoon`, `|commit %home`, and run it like:
60+
61+```hoon
62+> -send-task-take-gift [%boat ~]
63+[%hill p=~[%home]]
64+```
65+
66+## %mont
67+
68+This type of `task:clay` mounts the specified `beam:clay` to the specified `term` mount point. It looks like:
69+
70+```hoon
71+[%mont pot=term bem=beam]
72+```
73+
74+A `beam:clay` is the following structure:
75+
76+```hoon
77++$ beam [[p=ship q=desk r=case] s=path] :: global name
78+```
79+
80+You can mount the whole desk with a `path` of `/`, and you can also mount subdirectories or even individual files. If you want to mount an individual file, you must exclude its `mark` from the path. For example, if you want to mount `/gen/hood/hi/hoon`, you'd specify `/gen/hood/hi`. It will automatically be given the correct file extension when mounted. If you include the `hoon` mark it will crash (and currently crash your ship).
81+
82+Example:
83+
84+Here's a thread which will send the given `task:clay` to clay.
85+
86+**`send-task.hoon`**
87+
88+```hoon
89+/- spider
90+/+ strandio
91+=, strand=strand:spider
92+^- thread:spider
93+|= arg=vase
94+=/ m (strand ,vase)
95+^- form:m
96+=/ uarg !< (unit task:clay) arg
97+?~ uarg
98+ (strand-fail:strand %no-arg ~)
99+=/ =task:clay u.uarg
100+=/ =card:agent:gall [%pass /foo %arvo %c task]
101+;< ~ bind:m (send-raw-card:strandio card)
102+(pure:m !>(~))
103+```
104+
105+Save it to `ted/send-task.hoon`, `|commit %home` and run it like:
106+
107+```hoon
108+> -send-task [%mont %kids [our %kids da+now] /]
109+```
110+
111+If you look in your pier, you should now see a `kids` folder which contains the contents of that desk.
112+
113+If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll now see the mount point listed:
114+
115+```hoon
116+> -send-task-take-gift [%boat ~]
117+[%hill p=~[%kids %home]]
118+```
119+
120+Note the mount point doesn't need to match a desk, file or directory. We can also do:
121+
122+```hoon
123+> -send-task [%mont %wibbly-wobbly [our %home da+now] /]
124+```
125+
126+And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` desk. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.
127+
128+Let's try mounting a subdirectory and a single folder:
129+
130+```hoon
131+> -send-task [%mont %gen [our %home da+now] /gen]
132+> -send-task [%mont %hi [our %home da+now] /gen/hood/hi]
133+```
134+
135+If you look in your pier you'll now see a `gen` folder with the contents of `/gen` and a `hi.hoon` file by itself. Notice how the file extension has been automatically added.
136+
137+## %ogre
138+
139+This type of `task:clay` unmounts the specified mount. It's defined in `lull.hoon` as:
140+
141+```hoon
142+[%ogre pot=$@(desk beam)]
143+```
144+
145+But in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the desk but otherwise it won't work. Passing it a `beam:clay` will simply not work.
146+
147+Using the thread from the [%mont](#mont) section, we can unmount `%kids` like:
148+
149+```hoon
150+-send-task [%ogre %kids]
151+```
152+
153+Our custom mount point `%wibbly-wobbly` like:
154+
155+```hoon
156+-send-task [%ogre %wibbly-wobbly]
157+```
158+
159+And the single `hi.hoon` we previously mounted by specifying its mount point `%hi`:
160+
161+```hoon
162+-send-task [%ogre %hi]
163+```
164+
165+If we specify a non-existent mount point it will fail with an error printed to the dojo like:
166+
167+```hoon
168+> -send-task [%ogre %kids]
169+[%not-mounted %kids]
170+```
171+
172+If we give it an unmounted `beam:clay` it will not print an error but still won't work.
173+
174+## %dirk
175+
176+This type of `task:clay` commits changes in the target mount. It's defined in `lull.hoon` as:
177+
178+```hoon
179+[%dirk des=desk]
180+```
181+
182+... but like [%ogre](#ogre), it actually takes the name of a mount point rather than a `desk` as is specified.
183+
184+Example:
185+
186+With your `%home` desk mounted, try adding a file and, using the thread from the [%mont](#mont) section, send a `%dirk` to commit the change:
187+
188+```hoon
189+> -send-task [%dirk %home]
190++ /~zod/home/12/foo/txt
191+```
192+
193+Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.
194+
195+If you have the same desk mounted to multiple points, a committed change in one mount will also update the others.