4221 - more docs about build process

5 files changed, 60 insertions, 0 deletions

diff --git a/Readme.md b/Readme.md
index bbb714e0..1197feb5 100644
--- a/Readme.md
+++ b/Readme.md
@@ -402,6 +402,12 @@ c) Try running the tests:
 d) Check out [the programming environment](https://github.com/akkartik/mu/tree/master/edit#readme),
 the largest app built so far in Mu.
 
+e) Look at the `build` scripts. Mu's compilation process is itself designed to
+support staged learning. Each of the scripts (`build0`, `build1`, `build2`,
+etc.) is self-contained and can compile the project by itself. Successive
+versions add new features and configurability -- and complexity -- to the
+compilation process.
+
 **Credits**
 
 Mu builds on many ideas that have come before, especially:
diff --git a/build0 b/build0
index 20344bdf..efcbfcd3 100644
--- a/build0
+++ b/build0
@@ -5,14 +5,22 @@ set -v
 set -e  # stop immediately on error
 
 cd tangle
+  # auto-generate various lists (ending in '_list' by convention) {
+  # list of types
   {
     grep -h "^struct .* {" [0-9]*.cc  |sed 's/\(struct *[^ ]*\).*/\1;/'
     grep -h "^typedef " [0-9]*.cc
   }  > type_list
+  # list of function declarations, so I can define them in any order
   grep -h "^[^ #].*) {" [0-9]*.cc  |sed 's/ {.*/;/'  > function_list
+  # list of code files to compile
   ls [0-9]*.cc  |grep -v "\.test\.cc$"  |sed 's/.*/#include "&"/'  > file_list
+  # list of test files to compile
   ls [0-9]*.test.cc  |sed 's/.*/#include "&"/'  > test_file_list
+  # list of tests to run
   grep -h "^[[:space:]]*void test_" [0-9]*.cc  |sed 's/^\s*void \(.*\)() {$/\1,/'  > test_list
+  # }
+  # Now that we have all the _lists, compile 'tangle'
   g++ -g -O3 boot.cc -o tangle
 cd ..
 
@@ -23,7 +31,12 @@ cd termbox
 cd ..
 
 ./tangle/tangle [0-9]*.cc > mu.cc
+# auto-generate function declarations, so I can define them in any order
+# functions start out unindented, have all args on the same line, and end in ') {'
+#
+#                                      \/ ignore methods
 grep -h "^[^[:space:]#].*) {$" mu.cc  |grep -v ":.*("  |sed 's/ {.*/;/'  > function_list
+# auto-generate list of tests to run
 grep -h "^\s*void test_" mu.cc  |sed 's/^\s*void \(.*\)() {.*/\1,/'  > test_list
 g++ -g -O3 mu.cc termbox/libtermbox.a -o mu_bin
 
diff --git a/build1 b/build1
index 3aeb52ee..56336f8c 100644
--- a/build1
+++ b/build1
@@ -23,14 +23,22 @@ export CFLAGS="$CFLAGS -Wall -Wextra -ftrapv -fno-strict-aliasing"
 $CXX $CFLAGS enumerate/enumerate.cc -o enumerate/enumerate
 
 cd tangle
+  # auto-generate various lists (ending in '_list' by convention) {
+  # list of types
   {
     grep -h "^struct .* {" [0-9]*.cc  |sed 's/\(struct *[^ ]*\).*/\1;/'
     grep -h "^typedef " [0-9]*.cc
   }  > type_list
+  # list of function declarations, so I can define them in any order
   grep -h "^[^ #].*) {" [0-9]*.cc  |sed 's/ {.*/;/'  > function_list
+  # list of code files to compile
   ls [0-9]*.cc  |grep -v "\.test\.cc$"  |sed 's/.*/#include "&"/'  > file_list
+  # list of test files to compile
   ls [0-9]*.test.cc  |sed 's/.*/#include "&"/'  > test_file_list
+  # list of tests to run
   grep -h "^[[:space:]]*void test_" [0-9]*.cc  |sed 's/^\s*void \(.*\)() {$/\1,/'  > test_list
+  # }
+  # Now that we have all the _lists, compile 'tangle'
   $CXX $CFLAGS boot.cc -o tangle
 cd ..
 
@@ -42,7 +50,12 @@ cd ..
 
 LAYERS=$(./enumerate/enumerate --until $UNTIL_LAYER  |grep '\.cc$')
 ./tangle/tangle $LAYERS  > mu.cc
+# auto-generate function declarations, so I can define them in any order
+# functions start out unindented, have all args on the same line, and end in ') {'
+#
+#                                      \/ ignore methods
 grep -h "^[^[:space:]#].*) {$" mu.cc  |grep -v ":.*("  |sed 's/ {.*/;/'  > function_list
+# auto-generate list of tests to run
 grep -h "^\s*void test_" mu.cc  |sed 's/^\s*void \(.*\)() {.*/\1,/'  > test_list
 $CXX $CFLAGS mu.cc termbox/libtermbox.a -o mu_bin
 
diff --git a/build2 b/build2
index 881f2702..beb536df 100755
--- a/build2
+++ b/build2
@@ -86,14 +86,22 @@ older_than enumerate/enumerate enumerate/enumerate.cc && {
 
 older_than tangle/tangle tangle/*.cc && {
   noisy_cd tangle
+    # auto-generate various lists (ending in '_list' by convention) {
+    # list of types
     {
       grep -h "^struct .* {" [0-9]*.cc  |sed 's/\(struct *[^ ]*\).*/\1;/'
       grep -h "^typedef " [0-9]*.cc
     }  |update type_list
+    # list of function declarations, so I can define them in any order
     grep -h "^[^ #].*) {" [0-9]*.cc  |sed 's/ {.*/;/'  |update function_list
+    # list of code files to compile
     ls [0-9]*.cc  |grep -v "\.test\.cc$"  |sed 's/.*/#include "&"/'  |update file_list
+    # list of test files to compile
     ls [0-9]*.test.cc  |sed 's/.*/#include "&"/'  |update test_file_list
+    # list of tests to run
     grep -h "^[[:space:]]*void test_" [0-9]*.cc  |sed 's/^\s*void \(.*\)() {$/\1,/'  |update test_list
+    # }
+    # Now that we have all the _lists, compile 'tangle'
     $CXX $CFLAGS boot.cc -o tangle
   noisy_cd ..  # no effect; just to show us returning to the parent directory
 }
@@ -110,7 +118,12 @@ older_than cleave/cleave cleave/cleave.cc && {
 }
 
 mkdir -p .build
+# auto-generate function declarations, so I can define them in any order
+# functions start out unindented, have all args on the same line, and end in ') {'
+#
+#                                      \/ ignore methods
 grep -h "^[^[:space:]#].*) {$" mu.cc  |grep -v ":.*("  |sed 's/ {.*/;/'  |update .build/function_list
+# auto-generate list of tests to run
 grep -h "^\s*void test_" mu.cc  |sed 's/^\s*void \(.*\)() {.*/\1,/'  |update .build/test_list
 mkdir -p .build/termbox
 update_cp termbox/termbox.h .build/termbox
@@ -118,6 +131,7 @@ update_cp termbox/termbox.h .build/termbox
 older_than mu_bin mu.cc *_list cleave/cleave termbox/* && {
   ./cleave/cleave mu.cc .build
   noisy_cd .build
+    # create the list of global variable declarations from the corresponding definitions
     grep ';' global_definitions_list  |sed 's/[=(].*/;/'  |sed 's/^[^\/# ]/extern &/'  |sed 's/^extern extern /extern /'  |update global_declarations_list
     for f in mu_*.cc
     do
diff --git a/build3 b/build3
index 9c125c57..f73a5175 100755
--- a/build3
+++ b/build3
@@ -111,14 +111,22 @@ older_than enumerate/enumerate enumerate/enumerate.cc && {
 
 older_than tangle/tangle tangle/*.cc && {
   noisy_cd tangle
+    # auto-generate various lists (ending in '_list' by convention) {
+    # list of types
     {
       grep -h "^struct .* {" [0-9]*.cc  |sed 's/\(struct *[^ ]*\).*/\1;/'
       grep -h "^typedef " [0-9]*.cc
     }  |update type_list
+    # list of function declarations, so I can define them in any order
     grep -h "^[^ #].*) {" [0-9]*.cc  |sed 's/ {.*/;/'  |update function_list
+    # list of code files to compile
     ls [0-9]*.cc  |grep -v "\.test\.cc$"  |sed 's/.*/#include "&"/'  |update file_list
+    # list of test files to compile
     ls [0-9]*.test.cc  |sed 's/.*/#include "&"/'  |update test_file_list
+    # list of tests to run
     grep -h "^[[:space:]]*void test_" [0-9]*.cc  |sed 's/^\s*void \(.*\)() {$/\1,/'  |update test_list
+    # }
+    # Now that we have all the _lists, compile 'tangle'
     $CXX $CFLAGS boot.cc -o tangle
   noisy_cd ..  # no effect; just to show us returning to the parent directory
 }
@@ -135,7 +143,12 @@ older_than cleave/cleave cleave/cleave.cc && {
 }
 
 mkdir -p .build
+# auto-generate function declarations, so I can define them in any order
+# functions start out unindented, have all args on the same line, and end in ') {'
+#
+#                                      \/ ignore methods
 grep -h "^[^[:space:]#].*) {$" mu.cc  |grep -v ":.*("  |sed 's/ {.*/;/'  |update .build/function_list
+# auto-generate list of tests to run
 grep -h "^\s*void test_" mu.cc  |sed 's/^\s*void \(.*\)() {.*/\1,/'  |update .build/test_list
 mkdir -p .build/termbox
 update_cp termbox/termbox.h .build/termbox
@@ -143,6 +156,7 @@ update_cp termbox/termbox.h .build/termbox
 older_than mu_bin mu.cc *_list cleave/cleave termbox/* && {
   ./cleave/cleave mu.cc .build
   noisy_cd .build
+    # create the list of global variable declarations from the corresponding definitions
     grep ';' global_definitions_list  |sed 's/[=(].*/;/'  |sed 's/^[^\/# ]/extern &/'  |sed 's/^extern extern /extern /'  |update global_declarations_list
     for f in mu_*.cc
     do