Add notes on the build process and CLI interface.

1 files changed, 38 insertions, 0 deletions

diff --git a/README.md b/README.md
index 4d5024a..14a6f09 100644
--- a/README.md
+++ b/README.md
@@ -353,3 +353,41 @@ conversion step for IR2. Afterwards, we will transform all
 a reference into the current closure. All `<lambda>` forms will be
 replaced by a `<closure>` that explicitly captures variables from the
 parent context.
+
+### Build process
+
+The idea behind the build process is to bootstrap compilation through a
+Guile compatibility layer. Because we're writing R7RS scheme, Guile can
+execute `csc` just fine. So building executes in phases.
+
+1. Use Guile to run the compiler on itself, producing a compiled
+   bytecode blob.
+2. Run the bytecode blob on the compiler again, producing a second blob
+   that would in theory be identical.
+3. Embed the compiler bytecode blob with the bytecode interpreter to
+   make a compiler executable.
+
+## CLI interface
+
+The `csc` compiler has a simple CLI interface. There are two main modes
+of operation, compile-and-run, and ahead-of-time compilation. The
+default is compile-and-run.
+
+The compiler flags are given below.
+
+- **`-I` *dir*.** Add *dir* to the list of directories to be searched
+  for libraries. A system directory will always be searched as well. A
+  library name is translated into a path by combining the elements with
+  `/`. Library files end in a `.csc` suffix, and if there is a `.cso`
+  precomipled object file in the same directory, it will be used instead
+  of the `.csc` source file. Indeed, the `.csc` source file is not
+  required at all if a precompiled object file is found.
+- **`-o` *file*.** Write a precompiled object file to *file*. If `-o` is
+  specified, `csc` will operate in ahead-of-time compilation mode and
+  will not run the program. The output file will usually end in `.cso`.
+  This option can be used to precompile libraries to speed up execution,
+  and is used by the build process to turn the compiler into a bytecode
+  blob that can be embedded with the bytecode interpreter.
+
+The `csc` compiler also takes a filename to compile and
+possibly execute.