1 //: Ordering transforms is a well-known hard problem when building compilers.
 2 //: In our case we also have the additional notion of layers. The ordering of
 3 //: layers can have nothing in common with the ordering of transforms when
 4 //: SubX is tangled and run. This can be confusing for readers, particularly
 5 //: if later layers start inserting transforms at arbitrary points between
 6 //: transforms introduced earlier. Over time adding transforms can get harder
 7 //: and harder, having to meet the constraints of everything that's come
 8 //: before. It's worth thinking about organization up-front so the ordering is
 9 //: easy to hold in our heads, and it's obvious where to add a new transform.
10 //: Some constraints:
11 //:
12 //:   1. Layers force us to build SubX bottom-up; since we want to be able to
13 //:   build and run SubX after stopping loading at any layer, the overall
14 //:   organization has to be to introduce primitives before we start using
15 //:   them.
16 //:
17 //:   2. Transforms usually need to be run top-down, converting high-level
18 //:   representations to low-level ones so that low-level layers can be
19 //:   oblivious to them.
20 //:
21 //:   3. When running we'd often like new representations to be checked before
22 //:   they are transformed away. The whole reason for new representations is
23 //:   often to add new kinds of automatic checking for our machine code
24 //:   programs.
25 //:
26 //: Putting these constraints together, we'll use the following broad
27 //: organization:
28 //:
29 //:   a) We'll divide up our transforms into "levels", each level consisting
30 //:   of multiple transforms, and dealing in some new set of representational
31 //:   ideas. Levels will be added in reverse order to the one their transforms
32 //:   will be run in.
33 //:
34 //:     To run all transforms:
35 //:       Load transforms for level n
36 //:       Load transforms for level n-1
37 //:       ...
38 //:       Load transforms for level 2
39 //:       Run code at level 1
40 //:
41 //:   b) *Within* a level we'll usually introduce transforms in the order
42 //:   they're run in.
pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008800 } /* Keyword.Pseudo */
.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.highlight .na { color: #336699 } /* Name.Attribute */
.highlight .nb { color: #003388 } /* Name.Builtin */
.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Cl