<!--Weave of 'What This Module Does' generated by Inweb-->
<divclass="breadcrumbs">
<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../compiler.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="purpose">An overview of the building module's role and abilities.</p>
<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:
</p>
<ulclass="items"><li>(a) It helps to have some experience of reading webs: see <ahref="../../../inweb/docs/index.html"class="internal">inweb</a> for more.
</li><li>(b) The module is written in C, in fact ANSI C99, but this is disguised by the
fact that it uses some extension syntaxes provided by the <ahref="../../../inweb/docs/index.html"class="internal">inweb</a> literate
programming tool, making it a dialect of C called InC. See <ahref="../../../inweb/docs/index.html"class="internal">inweb</a> for
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>.
</li><li>(c) This module uses other modules drawn from the <ahref="../compiler.html"class="internal">compiler</a>, and also
uses a module of utility functions called <ahref="../../../inweb/docs/foundation-module/index.html"class="internal">foundation</a>.
For more, see <ahref="../../../inweb/docs/foundation-module/P-abgtf.html"class="internal">A Brief Guide to Foundation (in foundation)</a>.
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. Services for builders. </b>This module is essentially middleware. It acts as a bridge to the low-level
functions in the <ahref="../bytecode-module/index.html"class="internal">bytecode</a> module, allowing them to be used with much
greater ease and consistency.
</p>
<pclass="commentary">In particular, the functions here enforce a number of conventions about how an
Inter tree is laid out. Indiscriminate use of <ahref="../bytecode-module/index.html"class="internal">bytecode</a> functions would allow
other layouts to be made, but we want to be systematic.
</p>
<pclass="commentary">This module needs plenty of working data, and stashes that data inside the
<spanclass="extract"><spanclass="extract-syntax">inter_tree</span></span> structure it is working on: in a compoment of that structure called
a <ahref="1-bm.html#SP4"class="internal">building_site</a>. Whereas the main data ih an <spanclass="extract"><spanclass="extract-syntax">inter_tree</span></span> affects the meaning
of the tree, i.e., makes a difference as to what program the tree represents,
the contents of the <ahref="1-bm.html#SP4"class="internal">building_site</a> component are only used to make it, and
are ignored by the <ahref="../final-module/index.html"class="internal">final</a> code-generator.
</p>
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Structural conventions. </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>In particular, Inter code is fundamentally a mass of <spanclass="extract"><spanclass="extract-syntax">inter_package</span></span>s, which
<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>
