From de28b2c0a4fb5457e3d2e39f5e6abd0a38fc57a5 Mon Sep 17 00:00:00 2001
From: John Franklin <jfranklin9000@gmail.com>
Date: Sun, 18 Oct 2015 15:33:48 -0500
Subject: [PATCH 1/2] 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 <jfranklin9000@gmail.com>
Date: Mon, 19 Oct 2015 03:33:25 -0500
Subject: [PATCH 2/2] 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 \