Merge branch 'master' of https://github.com/urbit/urbit into karpi

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,

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 \

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 `~`.