<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../intern.html">Inter Modules</a></li><li><ahref="index.html">building</a></li><li><ahref="index.html#P">Preliminaries</a></li><li><b>What This Module Does</b></li></ul></div>
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Prerequisites. </b>The building module is a part of the Inform compiler toolset. It is
presented as a literate program or "web". Before diving in:
full details, but essentially: it's C without predeclarations or header files,
and where functions have names like <spanclass="extract"><spanclass="extract-syntax">Tags::add_by_name</span></span> rather than just <spanclass="extract"><spanclass="extract-syntax">add_by_name</span></span>.
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. Introduction. </b>This module is essentially middleware. It acts as a bridge to the low-level
<spanclass="extract"><spanclass="extract-syntax">inter_tree</span></span> structure it is working on: in a component of that structure called
a <ahref="1-bm.html#SP4"class="internal">building_site</a>. Whereas the main data in an <spanclass="extract"><spanclass="extract-syntax">inter_tree</span></span> affects the meaning
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Large-scale architecture. </b>An inter tree is fundamentally a set of resources stored in a nested set of
<li>● Everything else is inside a single top-level package called <spanclass="extract"><spanclass="extract-syntax">main</span></span>, which
has package type <spanclass="extract"><spanclass="extract-syntax">_plain</span></span>.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">main</span></span> contains only packages, and of only two types:
<ulclass="items"><li>● "Modules", which are packages of type <spanclass="extract"><spanclass="extract-syntax">_module</span></span>. These occur nowhere else
in the tree.
</li><li>● "Linkages", which are packages of type <spanclass="extract"><spanclass="extract-syntax">_linkage</span></span>. These occur nowhere else
in the tree.
</li></ul>
<li>●<ahref="../inform7/index.html"class="internal">inform7</a> compiles the material in each compilation unit to a module
named for that unit. That is:
<ulclass="items"><li>● The module <spanclass="extract"><spanclass="extract-syntax">source_text</span></span> contains material from the main source text.
</li><li>● Each extension included produces a module, named, for example,
<li>● Each kit produces a module, named after it. Any Inter tree produced by
<ahref="../inform7/index.html"class="internal">inform7</a> will always contain the module <spanclass="extract"><spanclass="extract-syntax">BasicInformKit</span></span>, for example.
</li><li>●<ahref="../inform7/index.html"class="internal">inform7</a> generates an additional module called <spanclass="extract"><spanclass="extract-syntax">generic</span></span>, holding
generic definitions — material which is the same regardless of what is
being compiled.
</li><li>●<ahref="../inform7/index.html"class="internal">inform7</a> generates an additional module called <spanclass="extract"><spanclass="extract-syntax">completion</span></span>, holding
resources put together from across different compilation units.<supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup>
</li><li>●<ahref="../inter/index.html"class="internal">inter</a> generates an additional module called <spanclass="extract"><spanclass="extract-syntax">synoptic</span></span>, made during
linking, which contains resources collated from or cross-referencing
everything else.
</li><li>● Modules contain only further packages, called "submodules" and with the
package type <spanclass="extract"><spanclass="extract-syntax">_submodule</span></span>. The Inform tools use a standard set of names for
such submodules: for example, in any module the resources defining its
global variables are in a submodule called <spanclass="extract"><spanclass="extract-syntax">variables</span></span>. (If it defines no
variables, the submodule will not be present.)
</li><li>● There are just two different linkages — packages with special contents
and which the linking steps of <ahref="../pipeline-module/index.html"class="internal">pipeline</a> treat differently from modules.
<ulclass="items"><li>●<spanclass="extract"><spanclass="extract-syntax">architecture</span></span> has no subpackages, and contains only constant definitions,
drawn from a fixed and limited set. These definitions depend on, and indeed
express, the target architecture: for example, <spanclass="extract"><spanclass="extract-syntax">WORDSIZE</span></span>, the number of
bytes per word, is defined here. Symbols here behave uniquely in linking:
when two trees are linked together, they will each have an <spanclass="extract"><spanclass="extract-syntax">architecture</span></span>
package, and symbols in them will simply be identified with each other.
Thus the <spanclass="extract"><spanclass="extract-syntax">WORDSIZE</span></span> defined in the main Inform 7 tree will be considered
the same symbol as the <spanclass="extract"><spanclass="extract-syntax">WORDSIZE</span></span> defined in the tree for BasicInformKit.
</li><li>●<spanclass="extract"><spanclass="extract-syntax">connectors</span></span> has no subpackages and no resources other than symbols.
It holds plugs and sockets enabling the Inter tree to be linked with other
Inter trees; during linking, these are removed when their purposes has been
served, so that after a successful link, <spanclass="extract"><spanclass="extract-syntax">connectors</span></span> will always be empty.
</li></ul>
</li></ul>
<pclass="commentary">See <ahref="1-ls.html"class="internal">Large-Scale Structure</a> for the code which builds all of the above
<ulclass="footnotetexts"><liclass="footnote"id="fn:1"><pclass="inwebfootnote"><supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> Ideally <spanclass="extract"><spanclass="extract-syntax">completion</span></span> would not exist, and everything in it would be made
as part of <spanclass="extract"><spanclass="extract-syntax">synoptic</span></span> during linking, but at present this is too difficult.
<ahref="#fnref:1"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. </b>Inter code is a nested tree of boxes, <spanclass="extract"><spanclass="extract-syntax">inter_package</span></span>s, which contain Inter
<pclass="commentary">So, for example, a <ahref="1-pck.html#SP1"class="internal">package_request</a> can represent <spanclass="extract"><spanclass="extract-syntax">/main/synoptic/kinds</span></span>
to call a <spanclass="extract"><spanclass="extract-syntax">symbol_request</span></span>. But "iname" is now a term used almost ubiquitously
across <ahref="../inform7/index.html"class="internal">inform7</a> and <ahref="../inter/index.html"class="internal">inter</a>, and it doesn't seem worth renaming it now.
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. Medium-scale blueprints. </b>The above systems make nested packages and symbols within them, but not the
<pclass="commentary">Note that we do not need to say where this code will go. <ahref="3-prd.html"class="internal">Producing Inter</a>
looks at the iname, works out what package request it should go into, incarnates
that into a real <spanclass="extract"><spanclass="extract-syntax">inter_package</span></span> if necessary, then incarnates the iname into
a real <spanclass="extract"><spanclass="extract-syntax">inter_symbol</span></span> if necessary; and finally emits a <spanclass="extract"><spanclass="extract-syntax">CONSTANT_IST</span></span> in the
relevant package, an instruction which defines the symbol.
</p>
<pclass="commentary">And similarly for emitting code inside a function body, though then it is
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. </b>But that is a laborious sort of notation for what, in a C-like language, would
be written just as <spanclass="extract"><spanclass="extract-syntax">return 1</span></span>. It would be very painful to have to implement
kits such as BasicInformKit that way. Instead, we write them in a notation which
is very close indeed<supid="fnref:2"><ahref="#fn:2"rel="footnote">2</a></sup> to Inform 6 syntax.<supid="fnref:3"><ahref="#fn:3"rel="footnote">3</a></sup>
<pclass="commentary">generates Inter code equivalent to the example above.<supid="fnref:4"><ahref="#fn:4"rel="footnote">4</a></sup> But the real power of
<ulclass="items"><li>(a) The ability to handle much larger passages of I6 notation - for example, a
function body 10K long — in an acceptably speed-efficient way; and
</li><li>(b) The ability to subsctitute values in for placeholders.
</li></ul>
<pclass="commentary">As an example of (b), an <ahref="2-is.html#SP1"class="internal">inter_schema</a> is how <ahref="../inform7/index.html"class="internal">inform7</a> compiles so-called
<pclass="commentary">Here, the text <spanclass="extract"><spanclass="extract-syntax">LIST_OF_TY_Say({-by-reference:L}, 1);</span></span> is passed through to
<ahref="2-pis.html#SP1"class="internal">ParsingSchemas::from_text</a> to make a schema. When the phrase is invoked,
<ahref="2-eis.html#SP1"class="internal">EmitInterSchemas::emit</a> is used to generate Inter code from it; and a
reference to the list passed to the invocation as the token <spanclass="extract"><spanclass="extract-syntax">L</span></span> is substituted
for the braced clause <spanclass="extract"><spanclass="extract-syntax">{-by-reference:L}</span></span>.<supid="fnref:5"><ahref="#fn:5"rel="footnote">5</a></sup> Schemas are also used as convenient
<ulclass="footnotetexts"><liclass="footnote"id="fn:2"><pclass="inwebfootnote"><supid="fnref:2"><ahref="#fn:2"rel="footnote">2</a></sup> Some antique syntaxes, such as <spanclass="extract"><spanclass="extract-syntax">for</span></span> loops broken with semicolons not colons,
are missing; so are some hardly-used directives; and the superclass <spanclass="extract"><spanclass="extract-syntax">::</span></span> operator;
and built-in compiler symbols relevant only to particular virtual machines, such
as <spanclass="extract"><spanclass="extract-syntax">#g$self</span></span>, are not there. But really, you will never notice they are gone.
<ahref="#fnref:2"title="return to text">↩</a></p></li><liclass="footnote"id="fn:3"><pclass="inwebfootnote"><supid="fnref:3"><ahref="#fn:3"rel="footnote">3</a></sup> Using Inform 6 notation was very convenient in the years 2004-17, when Inform
generated only I6 code: it became more problematic in 2018, when Inter instructions
were needed instead, and much of this module was written as a response.
<ahref="#fnref:3"title="return to text">↩</a></p></li><liclass="footnote"id="fn:4"><pclass="inwebfootnote"><supid="fnref:4"><ahref="#fn:4"rel="footnote">4</a></sup> Skipping over some of the arguments to the emission function, which basically
<ahref="#fnref:4"title="return to text">↩</a></p></li><liclass="footnote"id="fn:5"><pclass="inwebfootnote"><supid="fnref:5"><ahref="#fn:5"rel="footnote">5</a></sup> These braced placeholders are, of course, not Inform 6 notation, and
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. Small-scale masonry. </b>Finally, there are also times when we want to compile explicit code, one
Inter instruction at a time, and for this the Produce API is provided.
</p>
<pclass="commentary">This API keeps track of the current write position inside each tree (using
the <ahref="3-prd.html#SP3"class="internal">code_insertion_point</a> system), and then provides functions which call
down into <ahref="../bytecode-module/index.html"class="internal">bytecode</a> for us, making use of that write position. So, for
<pclass="commentary">Note the use of <ahref="3-prd.html#SP9"class="internal">Produce::down</a> and <ahref="3-prd.html#SP9"class="internal">Produce::up</a> to step up and down the
hierarchy: these functions are always called in matching ways.
</p>
<pclass="commentary firstcommentary"><aid="SP8"class="paragraph-anchor"></a><b>§8. </b>The <ahref="../pipeline-module/index.html"class="internal">pipeline</a> module makes heavy use of the Produce API. Surprising,
it provides still another middleware layer on top. See <ahref="../runtime-module/2-emt.html"class="internal">Emit (in runtime)</a>.
But it's really only a very thin layer, allowing the caller not to have to
pass the <spanclass="extract"><spanclass="extract-syntax">I</span></span> argument to every call (because it will always be the Inter tree
being compiled by <ahref="../inform7/index.html"class="internal">inform7</a>). Despite appearances, then, Produce makes all
of the Inter instructions generated inside either <ahref="../inter/index.html"class="internal">inter</a> or <ahref="../inform7/index.html"class="internal">inform7</a>.
