print comments in the hex dump at the offsets labels point to

Force-Push: yes
Change-Id: I1a0ea06380095da3e7702cab278c08bd21b292ca

1 files changed, 79 insertions, 5 deletions

diff --git a/transform.e b/transform.e
index 042f1d9..279ca72 100644
--- a/transform.e
+++ b/transform.e
@@ -2750,6 +2750,12 @@ allocate-transformation-state s" transformation-state" variable
   ~ : functionality needed for the log-load routine to run, then invoke the
   ~ : log-load routine to copy a more complete set of functionality into
   ~ : memory.
+  ~ :
+  ~ :   The log-load routine is super important, but also extremely verbose,
+  ~ : which necessarily makes it hard to read. If you're skimming this file
+  ~ : for the first time to get a sense of what it contains, you might want
+  ~ : to search for the words "label transform" to get to the stuff that makes
+  ~ : better introductory reading.
   ~ : blank-line
 
   main-input-buffer dup push-input-buffer
@@ -3373,17 +3379,17 @@ allocate-transformation-state s" transformation-state" variable
 ~ keyword from the dictionary entry header. All three of these save pointer to
 ~ their respective strings in a push-subitem-string metadata entry.
 ~
+~   Admit it, you thought writing out "metadata entry" so many times instead
+~ of just "entry" was silly because there was no other kind of entry in
+~ consideration, right up until you got to "dictionary entry". If so, hey
+~ look, neat, right? ;)
+~
 ~   The -data variant treats the value as opaque, and creates an
 ~ -entry-type-saved-data metadata entry. Unlike the others, these entries do
 ~ not affect the subitem entry stack; they're consumed and removed from the
 ~ entry array before entry execution even starts, by the matching data-*
 ~ command.
 ~
-~   Admit it, you thought writing out "metadata entry" so many times instead
-~ of just "entry" was silly because there was no other kind of entry in
-~ consideration, right up until you got to "dictionary entry". If so, hey
-~ look, neat, right? ;)
-~
 ~   Anyway, notice that when the various provide-* commands execute, all
 ~ they're doing is capturing values and creating metadata entries. Like all
 ~ metadata entries, these are attached to the latest output point as of the
@@ -4747,6 +4753,59 @@ allocate-transformation-state s" transformation-state" variable
     3unroll 1+ swap 1- swap 3roll
   } while drop ;
 
+~   This has complex logic, so we do it as a trace rather than with magic
+~ comments.
+~
+~ (new label value, label entry pointer --)
+: hex-set-label-trace
+  ~   If the value is zero, don't bother making an entry. There's a bunch of
+  ~ unused labels set to zero and even if they were used, showing them at the
+  ~ start of the file would not provide useful information.
+  over 0 = { drop drop exit } if
+
+  ~   Similarly, if the label has its non-offset bit set, we don't need an
+  ~ entry for that, either
+  ~
+  ~   It's worth noting that this bit is set by the code being compiled,
+  ~ potentially after it has already called label-set, and therefore after
+  ~ this trace. This introduces an ordering dependency, though it's unlikely
+  ~ to come up in practice because the bit is kept across label-loop passes
+  ~ and as long as there are any forward references there will always be at
+  ~ least two passes.
+  dup is-label-non-offset { drop drop exit } if
+
+  ~   Recall that label values are offsets within the output file. This is not
+  ~ otherwise a requirement, compiled code can use their values for anything
+  ~ it wants, but the label transform treats them as offsets and so does the
+  ~ ELF code.
+  ~
+  ~   We want to create metadata entries associated with that offset; recall
+  ~ also that entries' data starts are host addresses which must be within
+  ~ the label-loop buffer. So...
+  over
+  transformation-state transformation-state-output-metadata @
+  hex-output-metadata-label-loop-buffer-start @ +
+  0
+  ~ (new label value, label entry pointer, entry data start,
+  ~  entry data length)
+
+  2dup hex-output-metadata-entry-type-push-subitem-hex64 7 roll
+  add-hex-output-metadata-entry
+  ~ (label entry pointer, entry data start, entry data length)
+
+  2dup hex-output-metadata-entry-type-push-subitem-string
+  6 roll entry-to-name
+
+  swap-transform-variables here @ swap-transform-variables dup 3unroll
+  ~ (copy, original, copy)
+  over stringlen 1+ memcopy
+  swap-transform-variables allocate-string swap-transform-variables
+  add-hex-output-metadata-entry
+
+  hex-output-metadata-entry-type-line-comment
+  s" label # at offset # is here."
+  add-hex-output-metadata-entry ;
+
 ~ (data start, data length --)
 : hex-pack-trace
   ~   We keep a running tally of the next address in the output, for the
@@ -5017,6 +5076,21 @@ allocate-transformation-state s" transformation-state" variable
     exit
   } if
 
+  dup s" set-label" stringcmp 0 = {
+    create dropstring
+    s" docol" find entry-to-execution-token execute ,
+    make-hidden
+
+    ~ (new label value, label entry pointer --)
+    s" 2dup" find entry-to-execution-token ,
+    ' hex-set-label-trace entry-to-execution-token ,
+    ~ Fall through to the inner implementation.
+
+    ' ] entry-to-execution-token execute
+    exit
+  } if
+
+
   dup s" packstring" stringcmp 0 = {
     create dropstring
     s" docol" find entry-to-execution-token execute ,