@@ -8,19 +8,19 @@
88
99A guide for new Urbit developers.
1010
11−Problem statement: coder A has written some hoon, and you - coder B - need to jet it.
11+Problem statement: coder A has written some Hoon and you, coder B, need to jet it.
1212
1313Preconditions:
1414
1515- You have a pill `jetted.pill`, located in ~/tlon.
16−- You have an example of hoon code that, executed in dojo, does the right thing.
16+- You have an example of Hoon code that, executed in dojo, does the right thing.
1717
1818## Get all the source code you need.
1919
2020The source code you will need to modify lives in two different repos:
2121urbit and arvo. The urbit repo has the source code for the
2222interpreter / personal server, written in C. The arvo repo has the
23−operating system, written in hoon. Since you're jetting the hoon, you
23+operating system, written in Hoon. Since you're jetting the Hoon, you
2424need to modify both.
2525
2626For simplicity, I'm going to assume that you are doing all of your
@@ -45,25 +45,24 @@ your development elsewhere, if you like, and make a symbolic link.
4545
4646## Add new subprojects / libraries to urbit, if necessary
4747
48−If we have a complicated hoon function that, say, computes square
48+If we have a complicated Hoon function that, say, computes square
4949roots, we need to speed it up, and there is an open source library
5050libsquareroots, adding libsquareroots to our build might solve 90% of
5151our problems.
5252
53−If this describes your task, read this section. If not, skip to the next section - none of this is necessary.
53+If this describes your task, read this section. If not, skip to the next section -- none of this is necessary.
5454
5555+ have someone with github.com/urbit repo privileges fork libsquareroots into github.com/urbit
5656+ fork this new repo github.com/urbit/libsquareroots
5757+ cd ~tlon/urbit/subprojects
5858+ git submodule add <url>
5959+ edit ~tlon/urbit/subprojects/meson.build
60− - add a line `<foo>_dep = dependency('<foo>', version: '>=0.1.0', fallback: ['<foo>', '<foo>_dep'])`
61− - add `<foo>_dep` to the list of dependencies at the bottom of the file. Remember to use a comma.
62−
60+ + add a line `<foo>_dep = dependency('<foo>', version: '>=0.1.0', fallback: ['<foo>', '<foo>_dep'])`
61+ + add `<foo>_dep` to the list of dependencies at the bottom of the file. Remember to use a comma.
6362+ generate a meson.build for the new subproject: cd subprojects/<new directory>; meson wrap promote subprojects/secp256k1
6463+ edit the meson.build until it works ("works" is defined as "in the top level ~/tlon/urbit invoking scripts/build builds the library and links it into the urbit executable")
65−+ git add meson.build ; git commit -m"now builds with meson for Tlon" .
66−+ cd .. ; git add .gitmodules ; git commit -m"added submodule" .
64++ git add meson.build ; git commit -m "now builds with meson for Tlon" .
65++ cd .. ; git add .gitmodules ; git commit -m "added submodule" .
6766+ test the whole thing by
6867 + cd /tmp
6968 + rm -rf urbit
@@ -76,35 +75,42 @@ If this describes your task, read this section. If not, skip to the next sectio
7675+ submit a pull request from your copy of <libsquareroots> to the urbit copy
7776+ submit a pull request from your copy of urbit to the urbit copy
7877
79−
8078### If the submodule is modified
8179
8280The steps above add a submodule to the urbit repo. Or, more specifically, they add a specific version of the submodule to the repo.
8381
84−If the submodule has commits made to it (perhaps, the urbit repo will not track those new commits. XXXX)
82+If the submodule has commits made to it after that point in time, the urbit repo will not automatically track those new commits.
83+
84+To make urbit use an updated version of the submodule:
85+
86++ change to the submodule directory: `cd submodule_dir`
87++ checkout desired branch: `git checkout master`
88++ update: `git pull`
89++ get back to your project root : `cd ..`
90++ now the submodules are in the state you want, so: `git commit -am "Pulled down update to submodule_dir"`
8591
8692## Edit the source code
8793
8894There are several things you're going to do:
8995
90−+ hint the hoon code, so that the urbit interpreter will know to look for C code
96++ hint the Hoon code, so that the urbit interpreter will know to look for C code
9197+ for each jet you want you're going to declare two functions in two .h files (one takes the arguments as separate arguments, one takes them as one big tree)
9298+ then implement the two C functions in a single .c file
93−+ register the new C jet functions so the urbit interpretter knows the names / function pointers of the C funcs
99++ register the new C jet functions so the urbit interpreter knows the names / function pointers of the C funcs
94100
95101### Edit the Hoon Source code
96102
97−Let's edit the hoon source code first.
103+Let's edit the Hoon source code first.
98104
99105There are multiple runes to do hinting, but we're going to concentrate
100106on three. All hinting runes start with a tilda ("sig"). A mnemonic
101−is "we're signalling some information to the interpretter".
107+is "we're signaling some information to the interpreter".
102108
103−+ ~/ sigfas: simple jet registration, using defaults for some arguments
104−+ ~% sigcen: more complicated jet registration, specifying all arguments
105−+ ~& sigpam: debugging printf
109++ `~/` "signet": simple jet registration, using defaults for some arguments
110++ `~%` "sigcen": more complicated jet registration, specifying all arguments
111++ `~&` "sigpad": debugging printf
106112
107−Feel free to use ~& liberally! (Just remove them when you're done).
113+Feel free to use `~&` liberally! (Just remove them when you're done).
108114
109115Let's use the three to jet some code. Starting with this example:
110116
@@ -135,30 +141,30 @@ What we're doing here is hinting `ccc`, and then adding a string of
135141hints up the enclosing tree of arms. Each of these hints is
136142implemented w the simple / minimalist `~/` rune, which takes one
137143argument: the symbol that should be used to label the hint (these
138−symbols will be used later in the C code to match up C code with hoon code).
144+symbols will be used later in the C code to match up C code with Hoon code).
139145
140146The top hint (for `aaa`) uses the more verbose `~%` hint syntax, which
141−specifies two additional fields: `...is` means "parent jet can not be
147+specifies two additional fields: `..is` means "parent jet can not be
142148determined by context, so use 'is' as the parent" ("is" is the name of a system-supplied jet).
143149
144−[ N.B. saying " `is` is the parent " is a quick-and-dirty lie. The
150+[N.B. saying " `is` is the parent " is a quick-and-dirty lie. The
145151fuller version is: `+is` is an arm of the Arvo core, so `..is` is a
146152reference to the entire Arvo core. The whole Arvo core is hinted with
147153the jet label `%hex`, which is used as the parent for all the
148−top-level jet hints in %zuse. ]
154+top-level jet hints in %zuse.]
149155
150156When hinting your own code, make sure to hint each nesting arm.
151157Skipping any one will result in the jet code not being run.
152158
153159Note that you do not need to provide C implementations for everything
154−you hint. In this above example we hint aaa, bbb, and ccc - even if
160+you hint. In this above example we hint aaa, bbb, and ccc -- even if
155161our intent is only to jet ccc.
156162
157163### Edit the C Source code (overview)
158164
159−Having hinted our hoon, we now need to write the matching C code. If
160−we don't, there isn't a problem - hinting code merely tells the
161−interpretter to look for a jet, but if a jet is not found, the hoon
165+Having hinted our Hoon, we now need to write the matching C code. If
166+we don't, there isn't a problem -- hinting code merely tells the
167+interpreter to look for a jet, but if a jet is not found, the Hoon
162168still runs just fine.
163169
164170There are two distinct tasks to be done in C:
@@ -166,33 +172,28 @@ There are two distinct tasks to be done in C:
166172+ write the jet
167173+ register the jet
168174
169−For each jet you will write one u3we() function and one u3qe() function.
175+For each jet you will write one `u3we()` function and one `u3qe()` function.
170176
171177### Edit the C Source code to add registration
172178
173−* edit the header file `include/jets/w.h` to have a declaration for each of your u3we() functions. Every u3we() function looks the same, e.g.
174−
175−```
176−u3_noun u3we_xxx(u3_noun);
177−```
178−
179−* edit the header file `~/tlon/urbit/include/jets/q.h` to have a declaration for your u3qe() function. u3qe() functions can differ from each other, taking distinct numbers of u3_nouns and/or u3_atoms, e.g
180−
181−```
182− u3_noun u3qe_yyy(u3_atom, u3_atom);
183− u3_noun u3qe_zzz(u3_noun, u3_noun, u3_atom, u3_atom);
184−```
179+- edit the header file `include/jets/w.h` to have a declaration for each of your `u3we()` functions. Every `u3we()` function looks the same, e.g.
185180
186−* create a new .c file to hold your jets (both the u3we_() and u3qe_() functions go in the same file). For example, ~/tlon/urbit/jets/e/secp.c
187−(The choice of subdirectory under 'jets' (a through g) is XXX )
188−The new file should have three things:
189−+ \#include "all.h"
190−+ the new u3we() function
191−+ the new u3qe() function
181+ ```
182+ u3_noun u3we_xxx(u3_noun);
183+ ```
184+- edit the header file `~/tlon/urbit/include/jets/q.h` to have a declaration for your `u3qe()` function. `u3qe()` functions can differ from each other, taking distinct numbers of `u3_nouns` and/or `u3_atoms`, e.g.
192185
193−* edit ~/tlon/urbit/jets/tree.c to register jet
186+ ```
187+ u3_noun u3qe_yyy(u3_atom, u3_atom);
188+ u3_noun u3qe_zzz(u3_noun, u3_noun, u3_atom, u3_atom);
189+ ```
190+- create a new .c file to hold your jets (both the `u3we_()` and `u3qe_()` functions go in the same file). For example, `~/tlon/urbit/jets/e/secp.c`. The new file should have three things:
191+ + \#include "all.h"
192+ + the new `u3we()` function
193+ + the new `u3qe()` function
194+- edit ~/tlon/urbit/jets/tree.c to register jet
194195
195−In the hoon code we hinted some leaf node functions (`ccc` in our example) and then hinted each parent node up to the root `aaa`).
196+In the Hoon code we hinted some leaf node functions (`ccc` in our example) and then hinted each parent node up to the root `aaa`).
196197
197198We need to replicate this structure in C. Here's example C code to jet our above example Hoon:
198199
@@ -204,21 +205,21 @@ We need to replicate this structure in C. Here's example C code to jet our abov
204205 {}
205206 };
206207
207− // 2: that implements a jet for hoon arm 'ccc'
208+ // 2: that implements a jet for Hoon arm 'ccc'
208209 static u3j_core _143_hex_hobo_bbb_d[] =
209210 {
210211 { "ccc", _143_hex_hobo_ccc_d },
211212 {}
212213 };
213214
214− // 3: ... that is inside a hoon arm 'bbb'
215+ // 3: ... that is inside a Hoon arm 'bbb'
215216 static u3j_core _143_hex_hobo_hobo_d[] =
216217 {
217218 { "bbb", 0, _143_hex_hobo_bbb_d },
218219 {}
219220 };
220221
221− // 4: ... that is inside a hoon arm 'aaa'
222+ // 4: ... that is inside a Hoon arm 'aaa'
222223 static u3j_core _143_hex_d[] =
223224 { { "down", 0, _143_hex_down_d },
224225 { "lore", _143_hex_lore_a },
@@ -233,37 +234,36 @@ We need to replicate this structure in C. Here's example C code to jet our abov
233234
234235```
235236
236−There are 4 things steps here. Let's look at each in turn.
237+There are 4 steps here. Let's look at each in turn.
237238
238−Section 1 names the C function that we want to invoke: 'u3we_ccc()'.
239+Section 1 names the C function that we want to invoke: `u3we_ccc()`.
239240The precise manner in which it does this is by putting entries in an
240−array of 'u3j_harm's. The first one specifies the jet; the second one
241+array of `u3j_harm`s. The first one specifies the jet; the second one
241242is empty and serves as a termination to the array, similar to how a C
242243string is null terminated with a zero. The jet registration supplies
243−two fields {".2", u3we_secp}, but this does not initialize all of the
244−fields of u3j_harm. Other fields can be specified.
244+two fields `{".2", u3we_secp}`, but this does not initialize all of the
245+fields of `u3j_harm`. Other fields can be specified.
245246
246247The first field, with value ".2" in this example, is "arm 2".
247248
248249[ N.B. ".2" labels the axis of the arm in the core. With a %fast hint
249−(~/), we're hinting a gate, so the relevant arm formula is always just
250+(`~/`), we're hinting a gate, so the relevant arm formula is always just
250251the entire battery at +2. I assume the jet dashboard is flexible
251252enough to hint arms at different axes, but I've never seen it done. ]
252253
253−The second field, with value u3we_secp in this example, is a function
254+The second field, with value `u3we_secp` in this example, is a function
254255pointer (to the C implementation of the jet).
255256
256257The third field (absent here) is a flag to turn on verification of C
257−jet vs hoon at run time. It can take value c3n (which means verify at run time) or c3y
258+jet vs Hoon at run time. It can take value `c3n` (which means verify at run time) or `c3y`
258259(which means don't verify). If not present, it is set to don't verify.
259260
260−[N.B. The use of the flags seems inverted. Why is c3y ("yes") used to
261+[N.B. The use of the flags seems inverted. Why is `c3y` ("yes") used to
261262turn OFF verification? A: because the flag is actually "is the jet
262263already known to be perfect?" ]
263264
264265There are additional flags; see ~/tlon/urbit/include/noun/jets.h
265266
266−
267267Section 2 associated the previous jet registration with the name
268268"ccc". Note that this is the symbol used in the Hoon hint! Note also
269269that we again have a "null terminated" (metaphorically) list, ending with `{}`.
@@ -273,22 +273,24 @@ Section 3 references structure built in step 2 and slots it under
273273hinting in Hoon).
274274
275275The line in section 2
276+
276277```
277278 { "ccc", _143_hex_hobo_ccc_a },
278279```
279280
280281looks very similar to the line in section 3
282+
281283```
282284 { "bbb", 0, _143_hex_hobo_bbb_d },
283285```
284286
285287But note that the line in section 2 fill in the first 2 fields in the
286288struct, and the line in section 3 fills in the first three fields.
287−Section 2 is registering an array of u3j_harm, i.e. is registering an actual C
289+Section 2 is registering an array of `u3j_harm`, i.e. is registering an actual C
288290jet.
289291
290−Section 3 is specifying 0 for the array of u3j_harm and is instead
291−specifying an array of u3j_core, i.e. it is registering nesting of
292+Section 3 is specifying 0 for the array of `u3j_harm` and is instead
293+specifying an array of `u3j_core`, i.e. it is registering nesting of
292294another core which is not a leaf node.
293295
294296Section 4 is much like section 3, but it's the root of this particular
@@ -298,23 +300,23 @@ jet-registration tree may have multiple children.
298300Using this example you should be able to register jets whether your
299301nesting is 2 layers deep, 3 (like this example), or more. You should
300302also be able to register multiple jets at the same nesting level (e.g.
301−a function u3we_ddd() which is a sibling of u3we_ccc() inside data structure _143_hex_hobo_reco_d[] ).
303+a function `u3we_ddd()` which is a sibling of `u3we_ccc()` inside data structure `_143_hex_hobo_reco_d[]` ).
302304
303−### Edit the C source code to add the u3we_() function
305+### Edit the C source code to add the `u3we_()` function
304306
305307There are two C functions per jet, because separation of concerns is a good thing.
306308
307−The first C function - named u3we_something() - unpacks arguments from
309+The first C function -- named `u3we_something()` -- unpacks arguments from
308310the Hoon code and gets them ready.
309311
310−The second C function - named u3qe_something() - takes those arguments
311−and actually performs the operations that parallel the hoon code being
312+The second C function -- named `u3qe_something()` -- takes those arguments
313+and actually performs the operations that parallel the Hoon code being
312314jetted.
313315
314−Let's write the u3we_() function.
316+Let's write the `u3we_()` function.
315317
316−Your function is going to accept one argument, of type u3_noun. This
317−is the same type as a hoon noun ('*').
318+Your function is going to accept one argument, of type `u3_noun`. This
319+is the same type as a Hoon noun (`*`).
318320
319321This one argument is the payload.
320322
@@ -325,12 +327,12 @@ of "global variables and available methods", if analogies to other
325327programming languages were allowed!) and on the left branch the
326328sample (the arguments to this particular function call).
327329
328−Your u3we_() function does one thing: unpack the sample from 'cor',
329−sanity check them, and pass them in to the u3qe_() function.
330+Your `u3we_()` function does one thing: unpack the sample from 'cor',
331+sanity check them, and pass them in to the `u3qe_()` function.
330332
331333To unpack the sample
332334
333−We use the function u3r_mean() to do this, thusly:
335+We use the function `u3r_mean()` to do this, thusly:
334336
335337```
336338 u3_noun arg_a, arg_b, arg_c ... ;
@@ -343,12 +345,12 @@ We use the function u3r_mean() to do this, thusly:
343345 0)
344346```
345347
346−If we want to to assign the data located at axis 3 of cor to arg_a, we'd set axis_a = 3.
348+If we want to to assign the data located at axis 3 of cor to `arg_a`, we'd set `axis_a = 3`.
347349
348−u3r_mean() takes varargs, so we can pass in as many axis /
350+`u3r_mean()` takes varargs, so we can pass in as many axis /
349351return-argument pairs as we wish, terminated with a 0.
350352
351−When pulling arguments out of a hoon remember that Nock and Hoon store
353+When pulling arguments out of a Hoon remember that Nock and Hoon store
352354lists as skinny right-descending trees (because a linked list is a
353355degenerate case of a tree).
354356
@@ -372,13 +374,13 @@ Note that there are #defines to help you specify the axises you want.
372374They are in include/noun/xtract.h
373375
374376If the sample has one item, that one item it is located at the axis
375−specified by the #define u3x_sam_1.
377+specified by the #define `u3x_sam_1`.
376378
377379If the sample has 2 items, they are located at the axis specified by
378−the #defines u3x_sam_2 and u3x_sam_3.
380+the #defines `u3x_sam_2` and `u3x_sam_3`.
379381
380382If the sample has 3 items, they are located at the axis specified by
381−the #defines u3x_sam_2, u3x_sam_6, and u3x_sam_7.
383+the #defines `u3x_sam_2`, `u3x_sam_6`, and `u3x_sam_7`.
382384
383385etc.
384386
@@ -388,6 +390,7 @@ N.B. in our fprintf()s we're using both \n and \r to achieve line feed
388390(move cursor down one line) and carriage return (move it to the left),
389391because Urbit uses ncurses to control the screen and it changes the
390392default behavior you may be used to (where \n accomplishes both).
393+
391394```
392395 c3_o ret;
393396 u3_noun sample;
@@ -412,14 +415,17 @@ default behavior you may be used to (where \n accomplishes both).
412415 u3m_p("15: ", sample);
413416```
414417
415−If the hoon that you're jetting looks like this
418+If the Hoon that you're jetting looks like this
419+
416420```
417421 ++ make-k
418422 ~/ %make-k
419423 =, mimes:html
420424 |= [aaa=@ bbb=@ ccc=@]
421425```
426+
422427In the C code you'd fetch them out of the payload with
428+
423429```
424430 u3r_mean(cor,
425431 u3x_sam_2, & arg_aaa,
@@ -428,18 +434,22 @@ In the C code you'd fetch them out of the payload with
428434 ...
429435 0)
430436```
437+
431438If you're confident, go ahead and write code. If you want to inspect
432439your arguments to see what's going on, you can pretty print the
433440sample.
434441
435442You could - IN THEORY - inspect / pretty-print the noun by calling
443+
436444```
437445 u3m_p("description", cor); :: DO NOT DO THIS !!!
438446```
447+
439448...but you don't want to do this, because, recall, cor contains the
440449entire context - the whole enchilada.
441450
442451Do instead, perhaps,
452+
443453```
444454 c3_o ret;
445455 u3_noun sample;
@@ -447,19 +457,25 @@ Do instead, perhaps,
447457 ret = u3r_mean(sample, u3x_sam_1, &sample, 0);
448458 fprintf(stderr, "ret = %i\n\r", ret); // we want ret = 0 = yes
449459 u3m_p("sample", sample); // pretty print the entire sample
460+
450461```
451462
452463After our C function pulls out the arguments it needs to type check them.
453464
454−If arg_a is supposed to be a atom, trust but verify:
465+If `arg_a` is supposed to be a atom, trust but verify:
466+
455467```
456468 u3ud(arg_a); // checks for atomicity; alias for u3a_is_atom()
457469```
470+
458471If it's supposed to be a cell:
472+
459473```
460474 u3du(arg_a); // checks for cell-ness
461475```
476+
462477There are other tests you might need to use
478+
463479```
464480 u3a_is_cat()
465481 u3a_is_dog()
@@ -467,59 +483,71 @@ There are other tests you might need to use
467483 u3a_is_pug()
468484 u3a_is_pom()
469485```
486+
470487All of these rests return Hoon loobeans (yes/no vs true / false), so
471−check return values vs c3n / c3y. If any of these u3_mean(), u3ud()
488+check return values vs `c3n` / `c3y`. If any of these `u3_mean()`, `u3ud()`
472489etc return u3n you have an error and should return
490+
473491```
474492 return u3m_bail(c3__exit);
475493```
494+
476495otherwise pass the arguments into your "inner" jet function and return the results of that.
477496
478−### Edit the C source code to add the u3qe_() function
497+### Edit the C source code to add the `u3qe_()` function
479498
480−The u3qe_() function is the "real" jet - the C code that replaces the hoon.
499+The `u3qe_()` function is the "real" jet -- the C code that replaces the Hoon.
481500
482501First, you may need to massage your inputs a bit to get them into types that you can use.
483502
484−You have received a bunch of u3_nouns or u3_atoms, but you presumably want to do
485−things in a native C / non-Hoon manner: computing w raw integers, etc.
503+You have received a bunch of `u3_nouns` or `u3_atoms`, but you presumably want to do things in a native C / non-Hoon manner: computing w raw integers, etc.
486504
487−A u3_noun will want to be further diassembled into atoms. XXX
505+A `u3_noun` will want to be further diassembled into atoms.
488506
489−A u3_atom represents a simple number, but the implementation may or
507+A `u3_atom` represents a simple number, but the implementation may or
490508may not be simple. If the value held in the atom is 31 bits or less,
491509it's stored directly in the atom. If the value is 32 bits the atom
492−holds a pointer into the loom where the actual value is stored. ( see https://urbit.org/docs/vere/nouns/ )
510+holds a pointer into the loom where the actual value is stored. ( see [https://urbit.org/docs/vere/nouns/](../nouns) )
493511
494−You don't want to get bogged down in the details of this - you just
512+You don't want to get bogged down in the details of this -- you just
495513want to get data out of your atoms.
496514
497515If you know that the data fits in 32 bits or less, you can use
516+
498517```
499518 u3r_word(c3_w a_w, u3_atom b);
500519```
501520
502521If it is longer than 32 bits, use
522+
503523```
504524 u3r_words(c3_w a_w, c3_w b_w, c3_w* c_w, u3_atom d);
505525```
506526
507527or
528+
508529```
509530 u3r_bytes(c3_w a_w, c3_w b_w, c3_y* c_y, u3_atom d)
510531```
511532
512−(N.B. You may want to use u3r_bytes regardless, as
533+If you need to get the size
534+
535+```
536+ u3r_met(3, a);
537+```
513538
514539The actual meat of the function is up to you. What is it supposed to do?
515540
516541Now we move on to return semantics.
517542
518543First, you can transfer raw values into nouns using
544+
519545```
520546 u3_noun u3i_words(c3_w a_w, const c3_w* b_w)
521547```
548+
522549and you can build cells out of nouns using
550+
523551```
524552 u3nc(); // pair
525553 u3nt(); // triple
@@ -528,7 +556,8 @@ and you can build cells out of nouns using
528556```
529557There are two facets here: (i) data format, (ii) memory allocation.
530558
531−Regarding data format, if the hoon is expected to return a single atom (e.g. if the hoon looks like this
559+Regarding data format, if the Hoon is expected to return a single atom (e.g. if the Hoon looks like this:)
560+
532561```
533562 ++ make-k
534563 ~/ %make-k
@@ -536,11 +565,15 @@ Regarding data format, if the hoon is expected to return a single atom (e.g. if
536565 ^- @ :: <---- return value is a single value of type '@' (atom)
537566 ...
538567```
568+
539569then your C code - at least when you're stubbing it out - can do something like
570+
540571```
541572 return(123);
542573```
574+
543575Or, if you want to create an atom more formally, you can build it like this
576+
544577```
545578 // this variable is on the stack and will disappear
546579 unsigned char nonce32[32];
@@ -552,7 +585,9 @@ Or, if you want to create an atom more formally, you can build it like this
552585 // this returns the 32 bit handle to the atom
553586 return(nonce);
554587```
555−If, on the other hand, your hoon looks like
588+
589+If, on the other hand, your Hoon looks like
590+
556591```
557592 ++ ecdsa-raw-sign :: generate signature
558593 ~/ %ecdsa-raw-sign
@@ -560,34 +595,37 @@ If, on the other hand, your hoon looks like
560595 ^- [v=@ r=@ s=@]
561596 ...
562597```
598+
563599ending your C code with
600+
564601```
565602 return(123);
566603```
604+
567605is wrong and will result in a dojo error because you are returning a single atom, instead of a list of three atoms.
568606
569607Instead do one of these:
608+
570609```
571610 return(u3nc(a, b)); // for two atoms
572611 return(u3nt(a, b, c)); // for three atoms
573612 return(u3nq(a, b, c, d)); // for four atoms
574613```
614+
575615If you need to return a longer list, you can compose your own. Look
576616at the definitions of these three functions and you will see that they
577−are just recursive calls to the cell constructor u3i_cell() e.g.
617+are just recursive calls to the cell constructor `u3i_cell()` e.g.
618+
578619```
579620 u3i_cell(a, u3i_cell(b, u3i_cell(c, d));
580621```
581622
582−XXX more here about memory model, allocation, ownership
583−
584−
623+Understanding the memory model, allocation, freeing, and ownership ('transfer' vs 'retain' semantics) is important. Some info is available at [https://www.urbit.org/docs/vere/nouns/](../nouns).
585624
586625## Compile the C code
587626
588627You've edited C code; now you need to compile it to build a new urbit executable!
589628
590−
591629+ cd ~/tlon/urbit
592630+ rm -rf build
593631+ configure: choose one of
@@ -595,73 +633,69 @@ You've edited C code; now you need to compile it to build a new urbit executable
595633 + meson configure -Dbuildtype=debugoptimized build
596634 + meson configure -Dbuildtype=debug build
597635
598−Note that debugoptimized builds run slower than release builds, and debug builds run slower yet. Booting a debug builkd of urbit may take several minutes. [ N.B. compiler flags -O2 vs -O3 ]
636+ Note that debugoptimized builds run slower than release builds, and debug builds run slower yet. Booting a debug builkd of urbit may take several minutes. [ N.B. compiler flags -O2 vs -O3 ]
599637+ scripts/build
600638
601639## Compile the Hoon code into a pill
602640
603641You've compiled the Hoon code. Now you need to compile it.
604642
605−Wait, compile? Isn't Hoon that one types at the dojo prompt interpretted, or compiled on the fly?
643+Wait, compile? Isn't Hoon that one types at the dojo prompt interpreted, or compiled on the fly?
606644
607645Yes. But.
608646
609647When the urbit executable runs the first thing it does is load the
610−complete arvo operating system. That step is much faster if it can
611−load a "jam"-ed "pill", where all of the hoon has already been parsed
648+complete Arvo operating system. That step is much faster if it can
649+load a "jam"-ed "pill", where all of the Hoon has already been parsed
612650from text file into Hoon abstract syntax tree, and then compiled from
613−the hoon into the Nock equivalent.
651+the Hoon into the Nock equivalent.
614652
615653Note that this means that if you edit hoon.hoon, zuse.hoon, arvo.hoon,
616−vane/ames.hoon, etc. and then restart the urbit executable **YOU ARE
617−NOT RUNNING YOUR NEW CODE**.
654+vane/ames.hoon, etc. and then restart the urbit executable *YOU ARE
655+NOT RUNNING YOUR NEW CODE*.
618656
619657The only way to run the new code is to follow the following process:
620658
621−+ start up urbit, tell it to be a fake zod (act as a galaxy and disconnect from the rest of the network) and have it know where your edited arvo files are (although not execute them, as discussed above):
659++ start up urbit, tell it to be a fake zod (act as a galaxy and disconnect from the rest of the network) and have it know where your edited Arvo files are (although not execute them, as discussed above):
622660 + rm -rf ~/zod
623− + rm -rf ~/tlon/mypill.pill
624− + ~/tlon/urbit/build/urbit -FI zod -A ~/bus/tlon/arvo/ -c zod
625−
626−This should take < 90 seconds.
627−
628−+ If you accidentally exit urbit you can restart it XXX
629−+ inside your urbit, from the dojo command line, load the hoon files and compile them into a pill file:
661+ + rm -rf ~/tlon/mypill.pill
662+ + ~/tlon/urbit/build/urbit -FI zod -A ~/bus/tlon/arvo/ -c zod
663+ + This should take < 90 seconds.
664+ + If you accidentally exit urbit you can restart it
665++ inside your urbit, from the dojo command line, load the Hoon files and compile them into a pill file:
630666 + .pill +solid
631−
632−This should take < 90 seconds.
633−
634−+ examine the output. Expect to see something like this
635− ```
636− %solid-start
637− %solid-loaded
638− %solid-parsed
639− %solid-compiled
640− %solid-arvo
641− [%solid-kernel 0x6aa7.627e]
642− %arvo-assembly
643− [%solid-veer p=%$ q=/zuse]
644− [%tang /~zod/home/~2018.7.25..20.47.51..0027/sys/zuse ~mondyr-rovmes]
645− ```
646− + if, on the contrary, you see anything like this:
647− ```
648− syntax error
649− {3,356 7}
650− /~zod/home/~2018.7.25..20.47.51..0027/sys/zuse
651− ```
652− you have an error. In this case the error is on line 3,356, character 7 of file ~/tlon/arvo/sys/zuse.hoon.
653−
654−
655− + the urbit executable will not reload the .hoon files as you edit them. Neither `|reset` nor `.pill +solid` will make edits visible. Instead do this:
656− + in dojo: `|mount /=base=`
657− + in dojo: `|autoload %.y`
658− + at the command line : `ln -s ~/tlon/arvo/sys/zuse.hoon ~/zod/base/sys/zuse.hoon ` (make changes to both arguments of the ln command if you're editing, say, base/sys/vane/ford.hoon)
659−
660−This does three things: it makes urbit's file system mount your own, it makes urbit scan its own filesystem for changes and load them automatically, and it keeps your zuse.hoon
661−
662−Make a change to the hoon file. In dojo you should see `<<sync>>`. If you do not, one of the above steps was done incorrectly. If you do see this, it will be followed by any compile errors.
663−
664−+ Edit the hoon and try again. Keep iterating until the hoon compiles.
667+ + This should take < 90 seconds.
668+ + examine the output. Expect to see something like this
669+
670+ ```
671+ %solid-start
672+ %solid-loaded
673+ %solid-parsed
674+ %solid-compiled
675+ %solid-arvo
676+ [%solid-kernel 0x6aa7.627e]
677+ %arvo-assembly
678+ [%solid-veer p=%$ q=/zuse]
679+ [%tang /~zod/home/~2018.7.25..20.47.51..0027/sys/zuse ~mondyr-rovmes]
680+ ```
681+ + if, on the contrary, you see anything like this:
682+
683+ ```
684+ syntax error
685+ {3,356 7}
686+ /~zod/home/~2018.7.25..20.47.51..0027/sys/zuse
687+ ```
688+
689+ you have an error. In this case the error is on line 3,356, character 7 of file ~/tlon/arvo/sys/zuse.hoon.
690+ + the urbit executable will not reload the .hoon files as you edit them. Neither `|reset` nor `.pill +solid` will make edits visible. Instead do this:
691+ + in dojo: `|mount /=base=`
692+ + in dojo: `|autoload %.y`
693+ + at the command line : `ln -s ~/tlon/arvo/sys/zuse.hoon ~/zod/base/sys/zuse.hoon ` (make changes to both arguments of the ln command if you're editing, say, base/sys/vane/ford.hoon)
694+
695+ This does three things: it makes urbit's file system mount your own, it makes urbit scan its own filesystem for changes and load them automatically, and it keeps your zuse.hoon
696+
697+ Make a change to the Hoon file. In dojo you should see `<<sync>>`. If you do not, one of the above steps was done incorrectly. If you do see this, it will be followed by any compile errors.
698+ + Edit the Hoon and try again. Keep iterating until the Hoon compiles.
665699+ exit urbit with control-D
666700+ save the pill file
667701 + cp ~/zod/.urb/put.pill ~/tlon/mypill.pill
@@ -670,10 +704,10 @@ Make a change to the hoon file. In dojo you should see `<<sync>>`. If you do n
670704
671705Here's some things to note about the pill (and -A):
672706
673−An urbit has to boot into the Arvo kernel -- a nock core with a
707+An urbit has to boot into the Arvo kernel -- a Nock core with a
674708particular interface. It'd be possible to make some ad-hoc procedure
675709to initialize Arvo, but it would be a pretty drastic layering
676−violation and couple urbit to all sorts of internal implementation
710+violation and couple Urbit to all sorts of internal implementation
677711details of Arvo and Hoon. In contrast, the pill is basically a
678712serialized, declarative set of steps to initialize Arvo.
679713
@@ -682,9 +716,9 @@ basically a snapshot of a pristine Arvo kernel. In the future (see
682716+metal or +brass), the pill will contain something like:
683717
684718+ a boot formula
685−+ the hoon compiler as nock
686−+ the hoon compiler as source
687−+ arvo as source
719++ the Hoon compiler as nock
720++ the Hoon compiler as source
721++ Arvo as source
688722+ the vanes as source
689723+ userspace as source (ie, an initial %clay sync)
690724
@@ -698,60 +732,42 @@ Hopefully this helps to demystify these startup procedures.
698732
699733]
700734
701−
702735## Run the compiled C / compiled Hoon pill
703736
704737+ type `cd ~`
705738+ type `rm -rf zod`
706−+ type `~/tlon/urbit/build/urbit -FI zod -A ~/tlon/arvo/ -B ~/tlon/mypill.pill -c zod`.
707−
708−N.B. booting should not take more than about 90 seconds. If it
709−goes longer than that you might have created a 'poison pill', which
710−hangs things. Try booting without the -B flag, and/or reverting
711−your hoon changes, generating a new pill based on that, and
712−launching urbit with the known-clean pill. If these steps and boot
713−in < 90 seconds, but a boot with a pill created from your own hoon
714−does not, you have a hoon bug of some sort.
715−
716−Hoon bugs that disable booting can be as simple as the wrong number
717−of spaces. Many, but not all of them, will result in compile
718−errors during the `.pill +solid` step. If your booting takes > 90
719−seconds, abort it, and look at your hoon. Do a git diff, and
720−remove half the edits. Run through the entire process again. If
721−booting from the pill still hangs, remove half of what remains. Do
722−a binary search to find the precise error.
739++ type `~/tlon/urbit/build/urbit -FI zod -A ~/tlon/arvo/ -B ~/tlon/mypill.pill -c zod`
740+
741+ N.B. booting should not take more than about 90 seconds. If it goes longer than that you might have created a 'poison pill', which hangs things. Try booting without the -B flag, and/or reverting your Hoon changes, generating a new pill based on that, and launching urbit with the known-clean pill. If these steps and boot in < 90 seconds, but a boot with a pill created from your own Hoon does not, you have a Hoon bug of some sort.
723742
743+ Hoon bugs that disable booting can be as simple as the wrong number of spaces. Many, but not all of them, will result in compile errors during the `.pill +solid` step. If your booting takes > 90 seconds, abort it, and look at your Hoon. Do a git diff, and remove half the edits. Run through the entire process again. If booting from the pill still hangs, remove half of what remains. Do a binary search to find the precise error.
724744+ inside dojo: `|reset`
725745+ You now have created a galaxy fakezod, on its own detached network, running your own strange variant of the OS.
726−+ inside dojo: `(make-k:secp256k1:secp:crypto `@uvI`12 33)` # or whatever command runs the hoon you're jetting
746++ inside dojo: `` (make-k:secp256k1:secp:crypto `@uvI`12 33) `` # or whatever command runs the Hoon you're jetting
727747+ do your development work
728748+ If you happen to exit, you can restart with `urbit -FI zod zod`
729749
730750To expand:
731−* F means "fake"
732−* I means "run as galaxy zod"
733−* the final argument is the unix directory holding the files for the galaxy
751+- F means "fake"
752+- I means "run as galaxy zod"
753+- the final argument is the unix directory holding the files for the galaxy
734754
735755## Run the jetted code and compare to the non jetted code
736756
737757You are now running your jetted code in a fake zod.
738758
739−It would be convenient to fire up a second urbit in a terminal next to your fake zod, this one using non-jetted hoon.
759+It would be convenient to fire up a second urbit in a terminal next to your fake zod, this one using non-jetted Hoon.
740760
741761Then you can run identical commands in each, in parallel, and confirm that they do the same thing.
742762
743763+ edit ~/tlon/urbit/jets/e/secp.c (or whatever) to include `fprintf(stderr, "*** u3we_sign 2\n");` (or similar) in your jetted functions. This will let us verify that the jets exist and are running.
744764+ `cd ~/tlon/ubit ; scripts/build `
745−
746765+ `cp ~/tlon/arvo ~/tlon/arvo_nojet`
747−
748−+ edit ~/tlon/arvo_nojet/sys/zuse_nojetting.hoon to remove jetting
749−
750−+ Because we can not run two instances of the same fake galaxy on the same machine (their ports would conflict), we need to pick a new galaxy name. Galaxy names are not arbitrary. You may not name your galaxy "mygalaxy", "withjet", "withoutjet", or anything like that. Galaxy names are restricted to the range 0-255, converted into pronounceable syllables. 'Zod' is just the pronunciation of '0' ( to see this, in a dojo, cast ~zod to an untyped atom thusly: `@`~zod). Let's pick 1 as our new galaxy id. Use dojo to convert this into a urbit name: `@p`1 yields ~nec.
751−
766++ edit `~/tlon/arvo_nojet/sys/zuse_nojetting.hoon` to remove jetting
767++ Because we can not run two instances of the same fake galaxy on the same machine (their ports would conflict), we need to pick a new galaxy name. Galaxy names are not arbitrary. You may not name your galaxy "mygalaxy", "withjet", "withoutjet", or anything like that. Galaxy names are restricted to the range 0-255, converted into pronounceable syllables. `zod` is just the pronunciation of '0' ( to see this, in a dojo, cast `~zod` to an untyped atom thusly: `` `@`~zod ``). Let's pick 1 as our new galaxy id. Use dojo to convert this into a urbit name: `` `@p`1 `` yields `~nec`.
752768+ Open a new terminal. In that terminal: `cd ~ ; rm -rf nec ; ~/tlon/urbit/build/urbit -FI nec -A ~/tlon/arvo_nojetting/ -c nec`
753769+ This should take < 90 seconds.
754−+ inside your urbit, from the dojo command line, load the hoon files and compile them into a pill file: `.pill +solid`
770++ inside your urbit, from the dojo command line, load the Hoon files and compile them into a pill file: `.pill +solid`
755771+ This should take < 90 seconds.
756772+ exit urbit with control-D
757773+ save the pill file