From 0b84ccf360d9efb6616483f50fe87b86a29c6db4 Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Wed, 7 Oct 2015 15:42:19 -0700 Subject: [PATCH 01/16] Remove # prompt. --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 47 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 4f735d65c..6fe37149b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -urbit +Urbit ===== Urbit is a new computing environment designed from scratch. @@ -19,21 +19,23 @@ can: All of the source code is distributed under the MIT license. -Packages --------- - -#### Ubuntu or Debian - -Third-party package files are maintained at -https://github.com/yebyen/urbit-deb. Urbit is only supported on Jessie -onward. +Install from packages +-------------------- #### OS X - Homebrew brew install --HEAD homebrew/head-only/urbit -Dependencies ------------- +#### Ubuntu or Debian + +Third-party package files are maintained at +https://github.com/yebyen/urbit-deb. + +Urbit is only supported on jessie onward (but outgoing HTTPS +requests only work on stretch). + +Install by hand +--------------- urbit depends on: @@ -101,15 +103,22 @@ Just run `make`: Run (with a network invitation) ------------------------------- -If you have a planet named `~fintud-macrep` and a ticket -`~fortyv-tombyt-tabsen-sonres`, run +Your invitation is a planet (32-bit urbit), with a name like +`~fintud-macrep`, and a ticket (sekrit code), like +`~fortyv-tombyt-tabsen-sonres`. Run bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres Your pier (all Urbit state, log and checkpoint) will be in -`./fintud-macrep`. +`./fintud-macrep`. You can move it, and it's portable. Doing +`rm -r fintud-macrep/.urb/chk` will delete the checkpoint, +meaning all your events need to be recomputed, but making the +image smaller. -To start Urbit again omit the `-w` and `-t` flags: +To quit Urbit (without destroying any data, since Urbit is a +database): ^D. + +To start ~fintud-macrep again, omit the `-w` and `-t` flags: bin/urbit fintud-macrep @@ -118,12 +127,33 @@ Run (without a network invitation) bin/urbit -c mypier -Urbit will create a comet in `mypier`. +Urbit will create a comet (128-bit urbit) in `mypier`. -To start Urbit again omit the `-c` flag: +To quit Urbit (without destroying any data, since Urbit is a +database): ^D. Note that you can kill your urbit process as +nastily as you want, + +To start your comet again, omit the `-c` flag: bin/urbit mypier +Getting started +--------------- + +Your urbit is a Web server, so the best place to read about it +is in your browser. + +Urbit prints the HTTP port it's serving when it starts up: + + http: live (insecure) on 8080 + +8080 is the default. If you're running on AWS or another cloud +service, this port may be firewalled; go to the firewall +configuration to open it. + +Learn these two control keys first: +Press ^v + Basics ------ From 26e0060cd1b22e47360958b2607bb5341f50eb98 Mon Sep 17 00:00:00 2001 From: Raymond Pasco Date: Thu, 8 Oct 2015 13:17:15 -0400 Subject: [PATCH 02/16] C89 compatible for loop --- vere/main.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/vere/main.c b/vere/main.c index f167ffc85..484141cf5 100644 --- a/vere/main.c +++ b/vere/main.c @@ -225,7 +225,8 @@ u3_ve_usage(c3_i argc, c3_c** argv) "-f Fuzz testing\n", "-k stage Start at Hoon kernel version stage\n", "-Xwtf Skip last event\n"}; - for ( c3_i i=0; i < sizeof(use_c)/sizeof(c3_c*); i++ ) { + c3_i i; + for ( i=0; i < sizeof(use_c)/sizeof(c3_c*); i++ ) { fprintf(stderr,use_c[i],argv[0]); } exit(1); From e92012984c5d1da4bff1c7c2d8a81758de13395e Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Fri, 9 Oct 2015 18:31:07 -0700 Subject: [PATCH 03/16] Doc fixes and changes to match. --- README.md | 229 +++++++++++++++++++++++++++++++++++--------------- noun/vortex.c | 9 +- vere/http.c | 2 + vere/main.c | 6 +- vere/term.c | 2 + 5 files changed, 179 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 6fe37149b..11b79e9e8 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,25 @@ -Urbit -===== +# Urbit -Urbit is a new computing environment designed from scratch. +Urbit is a clean-slate system software stack. It's patent-free +and MIT licensed. It runs its own encrypted P2P network over UDP. -At present urbit is under heavy development. It's not useful for any -external purpose. Documentation is completely inadequate. Anyone can use -the interpreter, of course, but the network is invitation-only. +At present urbit is under heavy development. It's not useful for +any external purpose. Documentation is completely inadequate. +Anyone can try the interpreter, of course, but the network is +officially invitation-only. -If you're interested in keeping in touch or following the project you -can: +If you're interested in keeping in touch or following the project +you can: -- Enter your email address at [urbit.org](http://urbit.org). -- Subscribe to the +- Give us your email address at [urbit.org](http://urbit.org). +- Check out the [urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev) mailing list. - Follow [@urbit_](https://twitter.com/urbit\_) on Twitter. -- Get in touch with us via email, +- Hit us up by email, . We're nice! -All of the source code is distributed under the MIT license. - -Install from packages --------------------- +Install a package +----------------- #### OS X - Homebrew @@ -28,18 +27,24 @@ Install from packages #### Ubuntu or Debian -Third-party package files are maintained at -https://github.com/yebyen/urbit-deb. +Third-party packages are available, at: -Urbit is only supported on jessie onward (but outgoing HTTPS -requests only work on stretch). + https://github.com/yebyen/urbit-deb + +Urbit is only supported on Jessie onward (but outgoing HTTPS +requests only work on Stretch; I wish we knew why; if you have an +idea why or just think you can help, please let us know). Install by hand --------------- +First, install all our external dependencies. Then, make. + +### Dependencies + urbit depends on: - gcc + gcc (or clang) gmp libsigsegv openssl @@ -56,9 +61,6 @@ urbit depends on: sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags automake autoconf libtool g++ ragel cmake re2c -*note: http requests are not supported on debian jessie due to an ssl -issue* - #### Fedora sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake re2c @@ -83,8 +85,7 @@ three packages, at least with Homebrew. Your mileage may vary. pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool -Build ------ +### Build instructions Clone the repo: @@ -94,53 +95,101 @@ Clone the repo: cd urbit -Just run `make`: +Run `make`: make (On FreeBSD, use `gmake` instead.) -Run (with a network invitation) -------------------------------- +The executable is `bin/urbit`. Install it somewhere, or just use +it in place. -Your invitation is a planet (32-bit urbit), with a name like -`~fintud-macrep`, and a ticket (sekrit code), like -`~fortyv-tombyt-tabsen-sonres`. Run - - bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres - -Your pier (all Urbit state, log and checkpoint) will be in -`./fintud-macrep`. You can move it, and it's portable. Doing -`rm -r fintud-macrep/.urb/chk` will delete the checkpoint, -meaning all your events need to be recomputed, but making the -image smaller. - -To quit Urbit (without destroying any data, since Urbit is a -database): ^D. - -To start ~fintud-macrep again, omit the `-w` and `-t` flags: - - bin/urbit fintud-macrep - -Run (without a network invitation) ----------------------------------- - - bin/urbit -c mypier - -Urbit will create a comet (128-bit urbit) in `mypier`. - -To quit Urbit (without destroying any data, since Urbit is a -database): ^D. Note that you can kill your urbit process as -nastily as you want, - -To start your comet again, omit the `-c` flag: - - bin/urbit mypier - -Getting started +Create your urbit --------------- -Your urbit is a Web server, so the best place to read about it +Urbit is a semi-decentralized P2P network. So you may or may not +have an invitation. + +If you have an invitation, it's a *ticket* that lets you create +a 32-bit Urbit plot, aka *planet*. If you don't have an +invitation, you have to create a 128-bit plot, aka *comet*. + +As a comet, you're not necessarily a bad person. But you could +be anyone, so you have zero reputation. You have no official +access to any Urbit services. Any connectivity you may enjoy +could be shut off at any time. And probably will be. + +If you have an invitation, it's a planet like `~fintud-macrep` +and a ticket like `~fortyv-tombyt-tabsen-sonres`. Run + + urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres + +If you don't, pick a nickname for your comet, like `mycomet`. +Urbit will randomly generate a 128-bit address, but + + urbit -c mycomet + +Either way, creating your urbit will take some time. Go get +a cup of coffee. Some of this time involves creating keys; +some of it involves downloading code over Urbit itself. + +Note that Urbit is a P2P network that runs over random UDP ports; +some firewalls may not like it. Urbit without connectivity isn't +useless, but it can't boot without the network. + +But however horribly hacked, the `urbit` process can only read +and write inside the `fintud-macrep` or `mycomet` directory, +which we call your *pier*. A pier is portable; any Urbit install +on any OS can execute the same pier. + +In the pier directory is a set of user-level mount points. Mount +points are synced Dropbox style, with Unix file changes +autocommitted to the Urbit revision control system (`%clay`) and +vice versa. You edit Urbit code with vim and emacs, or whatever. + +Also within the pier is a system directory, `.urb`, which +contains an event log (`egz.hope`), a checkpoint (`.chk`), and +I/O directories for uploads and downloads (`put` and `get`). +You can compact the pier by deleting the checkpoint, although +that means Urbit needs to re-execute its entire event history. +This will take some time. Go have a beer. + +When it's created (and before it calls `chroot()`), your urbit +creates a passcode file, with a name like `~posluc-darnup`, +in `~/.urbit`. If you want to encrypt the checkpoint and log, +delete this file; Urbit will prompt you for its contents. Please +be warned that Urbit is not at present secure in any way! + +Wait until you see a prompt, like + + ~fintud-macrep:talk> + +and then press ^D to quit. Your urbit is born. + +Execute +------- + +To restart your urbit, run with the pier name: + + urbit fintud-macrep + urbit mycomet + +Your Urbit is a database, at least in theory. You can kill the +process however you like, and it won't lose state. In theory. +In practice, this works better on OS X than Linux. Also, don't +let your filesystem run out of disk! + +Out of the box, your urbit is running two default appliances, +`:dojo` (a shell or REPL) and `:talk`. Switch between them with +`^X`. Note that all apps share an output log, but `^X` switches +the prompt. + +`^D` from any default appliance exits the urbit process. + +Learn more +---------- + +Your urbit is a web server, so the best place to read about it is in your browser. Urbit prints the HTTP port it's serving when it starts up: @@ -149,10 +198,56 @@ Urbit prints the HTTP port it's serving when it starts up: 8080 is the default. If you're running on AWS or another cloud service, this port may be firewalled; go to the firewall -configuration to open it. +configuration to open it. In a last resort, you can use our +server, doznec.urbit.org. -Learn these two control keys first: -Press ^v +Or just talk +------------ + +Use `^X` to get into `:talk`, and +From `:talk`, + + ~ + +Doing more +---------- + +To test the dojo, run +Doing more + + +From either of the core + +directory. Your pier (all Urbit state, log and checkpoint) will +be in `./fintud-macrep`. The format is portable. Doing `rm -r +fintud-macrep/.urb/chk` will delete the checkpoint, meaning all +your events need to be recomputed, but making the image smaller. + + + bin/urbit fintud-macrep + +Run (without a network invitation) +---------------------------------- + +To create a comet (128-bit urbit) in the Unix directory +`mycomet`: + + bin/urbit -c mycomet + +This will take a little while. Go smoke a bowl. + +This process can only read and write files within `mycomet`. + +To quit Urbit (without destroying any data, since Urbit is a +database): ^D. + +To start your comet again, omit the `-c` flag: + + bin/urbit mypier + + +Learn these two control keys first: ^D to quit Urbit (from either +of the two core applications), Basics ------ diff --git a/noun/vortex.c b/noun/vortex.c index 8f9960895..7b4851d01 100644 --- a/noun/vortex.c +++ b/noun/vortex.c @@ -105,7 +105,14 @@ u3v_wish(const c3_c* str_c) // It's probably not a good idea to use u3v_wish() // outside the top level... // - return _cv_nock_wish(u3i_string(str_c)); + u3_noun txt = u3i_string(str_c); + u3_noun exp = u3kdb_get(u3A->yot, u3k(txt)); + + if ( u3_none != exp ) { + u3z(txt); + return exp; + } + else return _cv_nock_wish(u3i_string(str_c)); } } diff --git a/vere/http.c b/vere/http.c index 9adcede81..64155fda4 100644 --- a/vere/http.c +++ b/vere/http.c @@ -1054,9 +1054,11 @@ _http_start(u3_http* htp_u) uL(fprintf(uH, "http: listen: %s\n", uv_strerror(ret))); } } +#if 0 uL(fprintf(uH, "http: live (%s) on %d\n", (c3y == htp_u->sec) ? "\"secure\"" : "insecure", htp_u->por_w)); +#endif break; } } diff --git a/vere/main.c b/vere/main.c index f167ffc85..c50c8ed89 100644 --- a/vere/main.c +++ b/vere/main.c @@ -344,7 +344,11 @@ main(c3_i argc, fprintf(stderr, "used -c but %s already exists\n", u3_Host.dir_c); exit(1); } - } + } + if ( 0 == getuid() ) { + chroot(u3_Host.dir_c); + u3_Host.dir_c = "/"; + } u3_ve_sysopt(); diff --git a/vere/term.c b/vere/term.c index c22c8956f..750ffc3a3 100644 --- a/vere/term.c +++ b/vere/term.c @@ -355,7 +355,9 @@ u3_term_io_talk(void) uL(fprintf(uH, "term: listen: %s\n", uv_strerror(ret_w))); } } +#if 0 uL(fprintf(uH, "term: live (but unsupported) on %d\n", tel_u->por_s)); +#endif break; } } From d73fdfae6135339a912d9b94dc45dbc62142220d Mon Sep 17 00:00:00 2001 From: John Franklin Date: Mon, 12 Oct 2015 23:32:16 -0500 Subject: [PATCH 04/16] Generalize the message if trying to use -c or -w on an existing pier. --- vere/main.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vere/main.c b/vere/main.c index 484141cf5..35017550b 100644 --- a/vere/main.c +++ b/vere/main.c @@ -342,7 +342,7 @@ main(c3_i argc, if ( c3y == u3_Host.ops_u.nuu ) { struct stat s; if ( !stat(u3_Host.dir_c, &s) ) { - fprintf(stderr, "used -c but %s already exists\n", u3_Host.dir_c); + fprintf(stderr, "tried to create, but %s already exists\n", u3_Host.dir_c); exit(1); } } From 0fdb149c599e0a5e11627066a7b0d48ebf920684 Mon Sep 17 00:00:00 2001 From: John Franklin Date: Thu, 15 Oct 2015 12:47:52 -0500 Subject: [PATCH 05/16] Fix some comments in vere.h. No changes to the compiled code. --- include/vere/vere.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/vere/vere.h b/include/vere/vere.h index 0160640a9..1326d901d 100644 --- a/include/vere/vere.h +++ b/include/vere/vere.h @@ -819,7 +819,7 @@ void u3_term_ef_bake(u3_noun fav); - /* u3_term_ef_blit(): send %blit effect to to terminal. + /* u3_term_ef_blit(): send %blit effect to terminal. */ void u3_term_ef_blit(c3_l tid_l, @@ -950,7 +950,7 @@ void u3_unix_ef_ogre(u3_noun mon); - /* u3_unix_ef_ogre(): delete mount point + /* u3_unix_ef_hill(): enumerate mount points */ void u3_unix_ef_hill(u3_noun hil); From cda9537d0e1bbbb2c637241685d05bfd39a4afc8 Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Sat, 17 Oct 2015 12:56:18 -0700 Subject: [PATCH 06/16] Iterative welder for long lists. --- jets/b/weld.c | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/jets/b/weld.c b/jets/b/weld.c index cf55fbce0..94597b15b 100644 --- a/jets/b/weld.c +++ b/jets/b/weld.c @@ -6,6 +6,61 @@ /* functions */ + static u3_noun + _u3_iterative_weld(u3_noun a, + u3_noun b) + { + c3_w i_w, len_w; + c3_w** ray_w; + + // Count `a`. + { + u3_noun c = a; + + len_w = 0; + while ( c3y == u3du(c) ) { + if ( 0xffffffff == len_w ) { + return u3m_bail(c3__fail); + } + len_w++; + c = u3t(c); + } + } + + // Allocate an array of cells. + { + ray_w = u3a_walloc(len_w * c3_wiseof(c3_w *)); + for ( i_w = 0; i_w < len_w; i_w++ ) { + ray_w[i_w] = u3a_celloc(); + } + } + + // Fill in the array. + { + for ( i_w = 0; i_w < len_w; i_w++ ) { + u3a_cell* nov_u = (void *)ray_w[i_w]; + + nov_u->hed = u3k(u3h(a)); + if ( i_w == (len_w - 1) ) { + nov_u->tel = u3k(b); + } + else { + nov_u->tel = u3a_to_pom(u3a_outa(ray_w[i_w + 1])); + } + + a = u3t(a); + } + } + + // Return the result. + { + u3_noun pro = u3a_to_pom(u3a_outa(ray_w[0])); + + u3a_wfree(ray_w); + return pro; + } + } + u3_noun u3qb_weld(u3_noun a, u3_noun b) @@ -13,12 +68,16 @@ if ( 0 == a ) { return u3k(b); } +#if 0 else if ( c3n == u3du(a) ) { return u3m_bail(c3__exit); } else { return u3nc(u3k(u3h(a)), u3qb_weld(u3t(a), b)); } +#else + return _u3_iterative_weld(a, b); +#endif } u3_noun u3wb_weld(u3_noun cor) From 3f2b00109be99742cdaf2f033a5e2f8f840cb6fd Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Sat, 17 Oct 2015 20:23:53 -0700 Subject: [PATCH 07/16] Suspicious of this fix. --- jets/b/weld.c | 59 --------------------------------------------------- 1 file changed, 59 deletions(-) diff --git a/jets/b/weld.c b/jets/b/weld.c index 94597b15b..cf55fbce0 100644 --- a/jets/b/weld.c +++ b/jets/b/weld.c @@ -6,61 +6,6 @@ /* functions */ - static u3_noun - _u3_iterative_weld(u3_noun a, - u3_noun b) - { - c3_w i_w, len_w; - c3_w** ray_w; - - // Count `a`. - { - u3_noun c = a; - - len_w = 0; - while ( c3y == u3du(c) ) { - if ( 0xffffffff == len_w ) { - return u3m_bail(c3__fail); - } - len_w++; - c = u3t(c); - } - } - - // Allocate an array of cells. - { - ray_w = u3a_walloc(len_w * c3_wiseof(c3_w *)); - for ( i_w = 0; i_w < len_w; i_w++ ) { - ray_w[i_w] = u3a_celloc(); - } - } - - // Fill in the array. - { - for ( i_w = 0; i_w < len_w; i_w++ ) { - u3a_cell* nov_u = (void *)ray_w[i_w]; - - nov_u->hed = u3k(u3h(a)); - if ( i_w == (len_w - 1) ) { - nov_u->tel = u3k(b); - } - else { - nov_u->tel = u3a_to_pom(u3a_outa(ray_w[i_w + 1])); - } - - a = u3t(a); - } - } - - // Return the result. - { - u3_noun pro = u3a_to_pom(u3a_outa(ray_w[0])); - - u3a_wfree(ray_w); - return pro; - } - } - u3_noun u3qb_weld(u3_noun a, u3_noun b) @@ -68,16 +13,12 @@ if ( 0 == a ) { return u3k(b); } -#if 0 else if ( c3n == u3du(a) ) { return u3m_bail(c3__exit); } else { return u3nc(u3k(u3h(a)), u3qb_weld(u3t(a), b)); } -#else - return _u3_iterative_weld(a, b); -#endif } u3_noun u3wb_weld(u3_noun cor) From 04d916aa59885637e4882a18307729f6087fe5d7 Mon Sep 17 00:00:00 2001 From: "C. Guy Yarvin" Date: Sat, 17 Oct 2015 20:29:59 -0700 Subject: [PATCH 08/16] Eliminate hasty chroot. --- vere/main.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/vere/main.c b/vere/main.c index 461d09590..3756c27a4 100644 --- a/vere/main.c +++ b/vere/main.c @@ -346,11 +346,12 @@ main(c3_i argc, exit(1); } } +#if 0 if ( 0 == getuid() ) { chroot(u3_Host.dir_c); u3_Host.dir_c = "/"; } - +#endif u3_ve_sysopt(); printf("~\n"); From de28b2c0a4fb5457e3d2e39f5e6abd0a38fc57a5 Mon Sep 17 00:00:00 2001 From: John Franklin Date: Sun, 18 Oct 2015 15:33:48 -0500 Subject: [PATCH 09/16] Clarifications to Spec/u3.md --- Spec/u3.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Spec/u3.md b/Spec/u3.md index ed03df0dc..09fa140b0 100644 --- a/Spec/u3.md +++ b/Spec/u3.md @@ -163,8 +163,8 @@ Regular symbols follow this pattern: u3w[a-g] jets (retain, nock core) i/j/w.h j/[a-g]/*.c Irregular symbols always start with `u3` and obey no other rules. -They're defined in `i/n/u.h`. Finally, `i/all.h` includes all -these headers (fast compilers, yay) and is all you need to +They're defined in `i/n/aliases.h`. Finally, `i/all.h` includes +all these headers (fast compilers, yay) and is all you need to program in `u3`. ### u3: noun internals @@ -175,10 +175,10 @@ If your `u3_noun` is less than `(1 << 31)`, it's a direct atom. Every unsigned integer between `0` and `0x7fffffff` inclusive is its own noun. -If bit `31` is set in a `u3_noun`, bit `30` is always set - this -bit is reserved. Bit `29` is `1` if the noun is a cell, `0` if -it's an atom. Bits `28` through `0` are a word pointer into the -loom - see below. The structures are: +If bit `31` is set in a `u3_noun` and bit `30` is `1` the noun +is an indirect cell. If bit `31` is set and bit `30` is `0` the +noun is an indirect atom. Bits `29` through `0` are a word +pointer into the loom - see below. The structures are: typedef struct { c3_w mug_w; @@ -400,9 +400,10 @@ A "south" road is the other way around: Legend: `-` is durable storage (heap); `+` is temporary storage (stack); `~` is deep storage (immutable); `$` is the allocation -frame `#` is free memory. +frame; `#` is free memory. Pointer restrictions: pointers stored in `+` can point anywhere. +Of course, pointing to `#` (free memory) would be a bug. Pointers in `-` can only point to `-` or `~`; pointers in `~` only point to `~`. From fcc8e8ada239a2d468b5b8f767fd1caf1d4da5c3 Mon Sep 17 00:00:00 2001 From: John Franklin Date: Mon, 19 Oct 2015 03:33:25 -0500 Subject: [PATCH 10/16] Add notes on debugging with gdb. --- CONTRIBUTING.md | 24 ++++++++++++++++++++++++ Makefile | 10 +++++++++- 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb9d596b3..a67b830ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -145,6 +145,30 @@ Just do the same procedure to create a new, merged pill before committing the merge. Otherwise, just make sure to use the correct `urbit.pill` for each commit. +## Debug urbit with `gdb` + +Follow the build instructions in README.md but run `make` with argument `DEBUG=yes`: + +(If you've already built urbit first run `make clean`.) + + make DEBUG=yes + +Run `gdb`, while loading `bin/urbit` and its symbol table: + + gdb bin/urbit + +Set a breakpoint on `main()` (optional): + + break main + +Run your urbit comet `mycomet`: + + run mycomet + +Continue from the breakpoint on `main()`: + + continue + ## What to work on If you are not thinking of contributing with a specific goal in mind, diff --git a/Makefile b/Makefile index 7160cb2c2..a4ed3c502 100644 --- a/Makefile +++ b/Makefile @@ -70,10 +70,18 @@ endif INCLUDE=include MDEFINES=-DU3_OS_$(OS) -DU3_OS_ENDIAN_$(ENDIAN) -D U3_LIB=\"$(LIB)\" +DEBUG=no + +ifeq ($(DEBUG),yes) +DEBUGFLAGS=-g +else +DEBUGFLAGS=-O3 +endif + # NOTFORCHECKIN - restore -O3 # -DGHETTO \ # -DHUSH -CFLAGS= $(COSFLAGS) -O3 -ffast-math \ +CFLAGS= $(COSFLAGS) $(DEBUGFLAGS) -ffast-math \ -funsigned-char \ -I/usr/local/include \ -I/opt/local/include \ From 1358a2aaf29acd96b79877fdc30afd425ef550e9 Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:40:29 -0700 Subject: [PATCH 11/16] new readme --- README.md | 245 ++++++++++++++++++++++++++---------------------------- 1 file changed, 117 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 4f735d65c..8f05c78bb 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,86 @@ -urbit +Urbit ===== -Urbit is a new computing environment designed from scratch. +Urbit is a clean-slate system software stack defined as a +deterministic computer. An encrypted P2P network, `%ames`, runs on a +functional operating system, Arvo, written in a strict, typed +functional language, Hoon, which compiles itself to a combinator +interpreter, Nock, whose spec gzips to 340 bytes. -At present urbit is under heavy development. It's not useful for any -external purpose. Documentation is completely inadequate. Anyone can use -the interpreter, of course, but the network is invitation-only. +What is this for? Most directly, Urbit is designed as a personal +cloud server for self-hosted web apps. It also uses HTTP APIs to +manage data stuck in traditional web applications. -If you're interested in keeping in touch or following the project you -can: +More broadly, Urbit's network tackles identity and security problems +which the Internet can't easily address. Programming for a +deterministic single-level store is also a different experience from +Unix programming, regardless of language. -- Enter your email address at [urbit.org](http://urbit.org). -- Subscribe to the +Getting involved +---------------- + +If you're interested in following Urbit, you can: + +- Read our documentation at [urbit.org](http://urbit.org/docs) +- Subscribe to our newsletter at [urbit.org](http://urbit.org). +- Check out the [urbit-dev](https://groups.google.com/forum/#!forum/urbit-dev) mailing list. - Follow [@urbit_](https://twitter.com/urbit\_) on Twitter. -- Get in touch with us via email, +- Hit us up by email, `urbit@urbit.org`. We're nice! -All of the source code is distributed under the MIT license. +Code of conduct +--------------- -Packages --------- +Everyone involved in the Urbit project needs to understand and +respect our code of conduct, which is: "don't be rude." -#### Ubuntu or Debian +Documentation +============= -Third-party package files are maintained at -https://github.com/yebyen/urbit-deb. Urbit is only supported on Jessie -onward. +In-progress documentation can be found at +[urbit.org/docs](http://urbit.org/docs). -#### OS X - Homebrew +These docs ship with your urbit. If you're running one locally you +can access them at + + http://localhost:8080/home/docs + +Assuming you're running on port 8080. The port is printed on startup. + +Installation guide +================== + +Urbit can be installed on most Unix systems. There is no Windows +port. Windows is a wonderful OS, we just haven't gotten to it yet. +Use a VM. + +Install as a package +-------------------- + +### OS X - Homebrew brew install --HEAD homebrew/head-only/urbit -Dependencies ------------- +### Ubuntu or Debian + +Third-party packages are available, at: + + https://github.com/yebyen/urbit-deb + +Urbit is only supported on Jessie onward (but outbound HTTPS requests +only work on Stretch; I wish we knew why; help us!) + +Hand-build from source +---------------------- + +First, install all external dependencies. Then, make. + +### Dependencies urbit depends on: - gcc + gcc (or clang) gmp libsigsegv openssl @@ -54,9 +97,6 @@ urbit depends on: sudo apt-get install libgmp3-dev libsigsegv-dev openssl libssl-dev libncurses5-dev git make exuberant-ctags automake autoconf libtool g++ ragel cmake re2c -*note: http requests are not supported on debian jessie due to an ssl -issue* - #### Fedora sudo dnf install gcc gcc-c++ git gmp-devel openssl-devel openssl ncurses-devel libsigsegv-devel ctags automake autoconf libtool ragel cmake re2c @@ -81,8 +121,7 @@ three packages, at least with Homebrew. Your mileage may vary. pkg install git gmake gmp libsigsegv openssl automake autoconf ragel cmake re2c libtool -Build ------ +### Download and make Clone the repo: @@ -92,144 +131,94 @@ Clone the repo: cd urbit -Just run `make`: +Run `make`: make (On FreeBSD, use `gmake` instead.) -Run (with a network invitation) -------------------------------- +The executable is `bin/urbit`. Install it somewhere, or just use it +where it is. -If you have a planet named `~fintud-macrep` and a ticket -`~fortyv-tombyt-tabsen-sonres`, run +Launch procedure +================ - bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres +An urbit is a persistent server on the `%ames` P2P network. You'll +create one of these servers now. To understand what you're building, +you need to know a little about the network. -Your pier (all Urbit state, log and checkpoint) will be in -`./fintud-macrep`. +Launch instructions +------------------- -To start Urbit again omit the `-w` and `-t` flags: +If you have an invitation, it's a planet like `~fintud-macrep` and a +ticket like `~fortyv-tombyt-tabsen-sonres`. Run - bin/urbit fintud-macrep + urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres -Run (without a network invitation) ----------------------------------- +(You can leave the `~` on, but it annoys some Unix shells.) - bin/urbit -c mypier +If you don't have an invitation, pick a nickname for your comet, like +`mycomet`. Urbit will randomly generate a 128-bit plot: -Urbit will create a comet in `mypier`. + urbit -c mycomet -To start Urbit again omit the `-c` flag: +Either way, creating your urbit will take some time. Some of this +time involves creating keys; some of it involves downloading code +over Urbit itself. Go get a cup of coffee. Or a beer. - bin/urbit mypier +Wait until you see a prompt, either -Basics ------- + ~fintud-macrep:talk() -`^v` will switch between the task manager and the focussed process. `^x` -will switch between processes. +or -To start a process that is not yet started, run `*proc` from the task -manager. + ~fintud-macrep:dojo> -To connect your console to a process that has already been started, run -`+proc` from the task manager. Note that the process must be one that -supports console access, such as dojo and talk. +and then press \^D to quit. -`^d` will exit the pier from the task manager. No matter how you shut -your urbit down you'll be returned to exactly the same state as when you -turned it off. +Your urbit is launched! Ladies and gentlemen, we are floating in +space. -Talk ----- +Read the docs +============= -If you're on the network, you can use its most basic application, -`talk`. +Your urbit is your personal web server. The best place to read its +docs is by pointing your browser at it. -If `talk` is not running, start it with `*talk` from the task manager. +Urbit prints the HTTP port it's serving when it starts up: -Use `^x` to switch to the `talk` prompt and then run + http: live (insecure) on 8080 - ;join ~doznec/urbit-meta +8080 is the default. If you're running on AWS or another cloud +service, this port may be firewalled; go to the firewall +configuration to open it. -to join the `urbit-meta` channel. People in there are helpful. +(*Always run any urbit HTTP server which is even semi-serious inside +a reliable, battle-proven frontline server like nginx.*) -There are three main `talk` commands: +Urbit's own official planet `~winsen-pagdel` is also bound to just +plain `urbit.org`, and hosts the public docs +[here](http://urbit.org/docs). (They are, of course, the same as +those that ship with your urbit). - ;join ~urbit-name/channel +Assuming your Urbit is on `localhost:8080`, the Urbit docs are at -`;join` subscribes your main feed to a remote channel. + http://localhost:8080/home/docs - ; +And `:talk` is: -`;` activates a previous message number, like a URL that got -clipped. + http://localhost:8080/home/pub/talk/fab - ; - -`;` sets the target for your messages, such as `;~urbit-name` -for a private message. - -Filesystem Sync ---------------- - -The Urbit filesystem, `%clay` doesn't automatically sync to unix. If -you'd like to browse the contents of your Urbit from unix you'll need to -use `|mount`. - -`|mount` creates a mirror in unix of files from `%clay` that is always -watching for changes. To sync your entire `home/` desk run: - - |mount % - -you should see a directory called `home/` get created inside your pier. -When you change files in this directory the changes will get synced into -your urbit. - -Since each mount point is always watching for changes you may also want -to unmount from time to time. - -The full syntax is as follows (from `dojo`): - - |mount [] - -The `` is optional and defaults to the last part of -the ``. - - |unmount - -or: - - |unmount - -Sysadmin --------- - -For the most part, updates to the system are automatically synced to -your urbit across the network. - -When we make updates to the interpreter you should be able to shut down -your urbit and: - - git pull origin master - make - bin/urbit pier - -where pier is the name of your pier. - -While the network is still young from time to time we reboot the entire -universe. We call this a 'continuity breach' since we're breaking the -continuity of our crypto. - -When this happens you'll need to back up your data and start a fresh -pier. Your original ticket will still work. +For the time being the login code is output to your console. First +try any text, then you'll see a printf that looks like +`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will +get you in. Contributing ------------- +============ The first step in contributing to urbit is to come and join us on `:talk`. For more detailed instructions check out -[`contributing.md`](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md),. +[`contributing.md`](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md). From d584387dd5630c5fce584f0f86ee17e776ae6cce Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:43:56 -0700 Subject: [PATCH 12/16] clarifying --- README.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8f05c78bb..2bdc2d09b 100644 --- a/README.md +++ b/README.md @@ -144,8 +144,7 @@ Launch procedure ================ An urbit is a persistent server on the `%ames` P2P network. You'll -create one of these servers now. To understand what you're building, -you need to know a little about the network. +create one of these servers now. Launch instructions ------------------- @@ -166,7 +165,7 @@ Either way, creating your urbit will take some time. Some of this time involves creating keys; some of it involves downloading code over Urbit itself. Go get a cup of coffee. Or a beer. -Wait until you see a prompt, either +Wait until you see a prompt, something like ~fintud-macrep:talk() @@ -174,8 +173,6 @@ or ~fintud-macrep:dojo> -and then press \^D to quit. - Your urbit is launched! Ladies and gentlemen, we are floating in space. @@ -205,14 +202,13 @@ Assuming your Urbit is on `localhost:8080`, the Urbit docs are at http://localhost:8080/home/docs -And `:talk` is: +and `:talk` is http://localhost:8080/home/pub/talk/fab -For the time being the login code is output to your console. First +(For the time being the login code is output to your console. First try any text, then you'll see a printf that looks like -`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will -get you in. +`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will get you in.) Contributing ============ From 5f87e74098ed47c60ac1c5473d759ed2369552cf Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:44:53 -0700 Subject: [PATCH 13/16] minor --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2bdc2d09b..81ff7348e 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,7 @@ Third-party packages are available, at: https://github.com/yebyen/urbit-deb -Urbit is only supported on Jessie onward (but outbound HTTPS requests -only work on Stretch; I wish we knew why; help us!) +Urbit is only supported on Jessie onward (but outbound HTTPS requests only work on Stretch; I wish we knew why; help us!) Hand-build from source ---------------------- @@ -190,13 +189,12 @@ Urbit prints the HTTP port it's serving when it starts up: service, this port may be firewalled; go to the firewall configuration to open it. -(*Always run any urbit HTTP server which is even semi-serious inside -a reliable, battle-proven frontline server like nginx.*) +(*Always run any urbit HTTP server which is even semi-serious inside a reliable, battle-proven frontline server like nginx.*) Urbit's own official planet `~winsen-pagdel` is also bound to just plain `urbit.org`, and hosts the public docs [here](http://urbit.org/docs). (They are, of course, the same as -those that ship with your urbit). +those that ship with your urbit.) Assuming your Urbit is on `localhost:8080`, the Urbit docs are at From f1bedbf42c6fcf446861014239af880d325a4634 Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:46:25 -0700 Subject: [PATCH 14/16] simpler --- README.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 81ff7348e..bcb3c04e4 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,8 @@ can access them at Assuming you're running on port 8080. The port is printed on startup. -Installation guide -================== +Install +======= Urbit can be installed on most Unix systems. There is no Windows port. Windows is a wonderful OS, we just haven't gotten to it yet. @@ -139,15 +139,12 @@ Run `make`: The executable is `bin/urbit`. Install it somewhere, or just use it where it is. -Launch procedure -================ +Launch +====== An urbit is a persistent server on the `%ames` P2P network. You'll create one of these servers now. -Launch instructions -------------------- - If you have an invitation, it's a planet like `~fintud-macrep` and a ticket like `~fortyv-tombyt-tabsen-sonres`. Run @@ -175,8 +172,8 @@ or Your urbit is launched! Ladies and gentlemen, we are floating in space. -Read the docs -============= +Docs +==== Your urbit is your personal web server. The best place to read its docs is by pointing your browser at it. From 6c9feb38e5a8d48e68d94e308c84026a368b03ac Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:47:43 -0700 Subject: [PATCH 15/16] ports --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bcb3c04e4..fbe7187f2 100644 --- a/README.md +++ b/README.md @@ -182,7 +182,7 @@ Urbit prints the HTTP port it's serving when it starts up: http: live (insecure) on 8080 -8080 is the default. If you're running on AWS or another cloud +8080 is the default. When it's not available we use 8081. Then 8082, and so on. If you're running on AWS or another cloud service, this port may be firewalled; go to the firewall configuration to open it. From 8f85bb6eb2a7b7e0640daaf30a51e7324c2b1278 Mon Sep 17 00:00:00 2001 From: Galen Wolfe-Pauly Date: Tue, 20 Oct 2015 11:49:40 -0700 Subject: [PATCH 16/16] simpler --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index fbe7187f2..4c16c986f 100644 --- a/README.md +++ b/README.md @@ -193,17 +193,13 @@ plain `urbit.org`, and hosts the public docs [here](http://urbit.org/docs). (They are, of course, the same as those that ship with your urbit.) -Assuming your Urbit is on `localhost:8080`, the Urbit docs are at +Assuming your Urbit is on `localhost:8080`, your copy of the docs are at http://localhost:8080/home/docs -and `:talk` is +To continue getting setup, start here: - http://localhost:8080/home/pub/talk/fab - -(For the time being the login code is output to your console. First -try any text, then you'll see a printf that looks like -`code='laslyt-mocwyd-hobmyn-rolbyl'` in your terminal. That code will get you in.) + http://localhost:8080/home/docs/user/start Contributing ============