document how to do a full build of evoke.hex

the contents of evoke.hex aren't usable quite yet, for reasons now described in the README, but the build itself runs to completion. this is honestly a huge milestone.

Force-Push: yes!!!!!
Change-Id: Ia95d6aba7485062c0e64cdde0575058a2df2a1ef

1 files changed, 19 insertions, 13 deletions

diff --git a/README.txt b/README.txt
index 384c8f9..4471530 100644
--- a/README.txt
+++ b/README.txt
@@ -216,17 +216,23 @@ written in Evocation-assembly), if you intend to play around with this you may
 wish to know how to attempt to run it on things. The latest draft way to do
 that is:
 
-  $ (cat labels.e elf.e transform.e; echo 's" xyzzy" allocate-string dup 1048576 read-to-buffer'; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e linux-dynamic.e labels.e elf.e transform.e execution.e; echo 's" pyrzqxgl" allocate-string dup 262144 read-to-buffer '; cat core.e linux.e output.e amd64.e execution-support.e log-load.e; echo pyrzqxgl swap 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e linux-dynamic.e; echo pyrzqxgl; cat evoke.e; echo 'xyzzy s" evoke-source" variable 1024 1024 * allocate s" evoke-binary" variable 1024 1024 * allocate s" evoke-metadata" variable evoke-metadata evoke-binary dup evoke-source 5 roll hex-transform bye ' ) | ./evoke > evoke.hex
-
-  It will likely crash somewhere inside label-loop. You may find it helpful
-to modify transform.e's definition of hex-sys-write-replacement by adding
-the words "sys-write" and "exit" at the start of it, thereby turning it off
-and allowing crash dumps to print.
-
-  It's worth understanding that, although the log-load transform's output
-comes first in the executable, it conceptually depends on the label transform,
-and is unlikely to get anywhere until that's complete. For development
-purposes, it may make sense to comment out the call to output-warm-start in
-evoke.e and set a placeholder value for the warm-start label. Now running it
-will cause failure somewhere inside the log-load transform; get debugging! :)
+  $ (cat labels.e elf.e transform.e; echo 's" xyzzy" allocate-string dup 1048576 read-to-buffer'; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e linux-dynamic.e labels.e elf.e transform.e execution.e; echo 's" pyrzqxgl" allocate-string dup 262144 read-to-buffer '; cat core.e linux.e output.e amd64.e execution-support.e log-load.e; echo pyrzqxgl swap 262144 read-to-buffer; cat core.e linux.e output.e amd64.e execution-support.e log-load.e dynamic.e input.e interpret.e flow-control.e linux-dynamic.e; echo pyrzqxgl; cat evoke.e; echo 'xyzzy s" evoke-source" variable 1024 1024 2 * * allocate s" evoke-binary" variable 1024 1024 * allocate s" evoke-metadata" variable evoke-metadata evoke-binary dup evoke-source 5 roll hex-transform bye ' ) | ./evoke > evoke.hex
+
+  It should run to completion, producing output, but the output has various
+problems such as underflowing the substring-entry stack, displaying assembly
+parameters in the wrong order, having insufficient explanation of label
+references and definitions, and so on. It also takes several minutes to run,
+which Irenes believe is because of the use of linked lists rather than hash
+tables for the various dictionaries. Adding a hash table is a task to do after
+bootstrapping is complete, but the rest of that is fixable now, and should
+likely be the focus of any development efforts.
+
+  In perusing the output, it's worth understanding that, although the log-load
+transform's output comes first in the executable, it conceptually depends on
+the label transform, and is unlikely to get anywhere until that's complete.
+For development purposes, it may make sense to comment out the call to
+output-warm-start in evoke.e and set a placeholder value for the warm-start
+label.
+
+  Now get debugging! :)