Bootstrap README

2 files changed, 33 insertions, 0 deletions

diff --git a/src/README.txt b/src/README.txt
index a04d515f..05dc7c83 100644
--- a/src/README.txt
+++ b/src/README.txt
@@ -10,6 +10,7 @@ Compiler toolchain:
 - pp.bqn      General preprocessing
 - pr.bqn      Preprocess the runtime
 - cjs.bqn     Format compiler output as Javascript literals
+- bootstrap/  Simpler compilers for bootstrapping (see README there)
 
 Compilation targets:
 
diff --git a/src/bootstrap/README.txt b/src/bootstrap/README.txt
new file mode 100644
index 00000000..74034a39
--- /dev/null
+++ b/src/bootstrap/README.txt
@@ -0,0 +1,32 @@
+Bootstrapping chain for BQN. The following gets you a full compiler:
+
+- Files boot2.bqn and boot1.bqn here, and ../c.bqn
+- A compiler capable of building boot2.bqn
+- Primitive support sufficient to run all of the above
+
+Each compiler can compile the previous one, but not ones before that.
+Run verify.bqn to check that object code produced at each step matches
+the full compiler's output.
+
+The compiler boot2.bqn uses an easy-to-compile subset of BQN syntax.
+Syntax restrictions for the full chain are listed below.
+
+Full compiler, boot 0
+  No headers or namespaces (or decimals) . :;? ⇐
+  No high-rank array syntax []
+  No useless parentheses that enclose a single value
+
+Boot -1
+  No stranding ‿ or character literals '
+  No " in comment: comments can safely be parsed before strings
+  No _: token role determined by first character
+  No Nothing: · doesn't appear and 𝕨 always has a value
+  Only 𝕊𝕩𝕨 for special names
+
+Boot -2
+  Single-scope
+  No modified or list assignment
+  No 2-modifiers at all
+
+Boot -3
+  Not easier to compile, just cut down further