From 37bc3b8d101b54247b05b4053d70cf99af4695ec Mon Sep 17 00:00:00 2001
From: crc <crc@noemail.net>
Date: Thu, 7 Feb 2019 02:08:47 +0000
Subject: [PATCH] add some commentary on building & using retro-compiler

FossilOrigin-Name: a98c6167c4d942aed18c9938210f7102ff7dcb178b22df80ed61fbe145d8a519
---
 BUILDING.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/BUILDING.md b/BUILDING.md
index cd0fd05..11d0c3f 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -77,6 +77,43 @@ To build:
 
     make bin/retro-barebones
 
+## retro-compiler
+
+This is a turnkey compiler. It can compile a new executable
+bundling a Retro VM and image.
+
+Requirements:
+
+- BSD or Linux
+- objcopy in $PATH
+
+To build:
+
+    make bin/retro-compiler
+
+Example use:
+
+1. Given a source file like "Hello.forth":
+
+    ~~~
+    :hello 'hello_world! s:put nl ;
+    ~~~
+
+2. Use:
+
+    ./bin/retro-compiler Hello.forth hello
+
+The first argument is the source file, the second is the
+word to run on startup.
+
+3. Run the generated `a.out`
+
+Limits:
+
+This only supports the core words ('all' interface) and the
+file i/o words. Support for other I/O extensions will be
+added in the future.
+
 ## RETRO12.html
 
 There is a JavaScript and HTML based interface. To