<!--Weave of 'Pipelines and Stages' generated by Inweb-->
<divclass="breadcrumbs">
<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="../compiler.html">Compiler Tools</a></li><li><ahref="index.html">inter</a></li><li><ahref="index.html#M">Manual</a></li><li><b>Pipelines and Stages</b></li></ul></div>
<pclass="purpose">Sequences of named code-generation stages are called pipelines.</p>
<ulclass="toc"><li><ahref="M-pas.html#SP1">§1. Stages and descriptions</a></li><li><ahref="M-pas.html#SP3">§3. Pipelines run by Inform</a></li><li><ahref="M-pas.html#SP4">§4. Syntax of pipeline descriptions</a></li><li><ahref="M-pas.html#SP5">§5. Dictionary of stages</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Stages and descriptions. </b>A processing stage is a step in code generation which acts on a tree
<pclass="commentary">and the file <spanclass="extract"><spanclass="ConsoleText-extract-syntax">mypl.interpipeline</span></span> would have one stage listed on each line,
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. </b>A pipeline description can make use of "variables". These hold only text,
<pclass="commentary">creates the variable <spanclass="extract"><spanclass="ConsoleText-extract-syntax">*X</span></span> with the textual contents <spanclass="extract"><spanclass="ConsoleText-extract-syntax">ex/why</span></span> before running
<pclass="commentary">The special variable <spanclass="extract"><spanclass="extract-syntax">*log</span></span>, which always exists, means the debugging log.
A command to write a text file to <spanclass="extract"><spanclass="extract-syntax">*log</span></span> is interpreted instead to mean
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Pipelines run by Inform. </b>As the above implies, Inter pipelines normally begin with a clean slate:
<pclass="commentary">In addition, the "domain" is set to the directory containing the <spanclass="extract"><spanclass="extract-syntax">*out</span></span>
<pclass="commentary">...and then this will be used instead when compiling <spanclass="extract"><spanclass="extract-syntax">Strange.inform</span></span>.
<pclass="commentary">Note that Inbuild and Inform 7 respond to all three of <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline</span></span>,
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-file</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-text</span></span>, whereas Inter responds only to the
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. Syntax of pipeline descriptions. </b>Pipelines are, roughly speaking, just lists of steps. Each step occupies
a single line: blank lines are ignored, and so are lines whose first non-white-space
character is a <spanclass="extract"><spanclass="ConsoleText-extract-syntax">!</span></span>, which are considered comments.
</p>
<pclass="commentary">A step description is often as simple as being the name of a stage, but
sometimes that name is accompanied by parameters.
</p>
<pclass="commentary">The difference between a step and a stage is illustrated by this example:
<spanclass="plain-syntax"> generate text </span><spanclass="reserved-syntax">-></span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">*tout</span>
<pclass="commentary">Here there are three steps. The first uses the <spanclass="extract"><spanclass="extract-syntax">read</span></span> stage; the second and
third use the <spanclass="extract"><spanclass="extract-syntax">generate</span></span> stage, but with different parameters.
</p>
<pclass="commentary">There are three sorts of stage description: those involving material coming
<pclass="commentary">The <spanclass="extract"><spanclass="extract-syntax">STAGENAME</span></span> never contains white space; hyphens are used instead. So, for
example, <spanclass="extract"><spanclass="extract-syntax">eliminate-redundant-labels</span></span> is a valid <spanclass="extract"><spanclass="extract-syntax">STAGENAME</span></span>.
</p>
<pclass="commentary">The <spanclass="extract"><spanclass="extract-syntax">[TREE]</span></span> is optional. For example:
<pclass="commentary">Pipeline descriptios allow us to manage up to 10 different Inter trees, and
these are called <spanclass="extract"><spanclass="extract-syntax">0</span></span> to <spanclass="extract"><spanclass="extract-syntax">9</span></span>. These are all initially empty. Any stage which
doesn't specify a tree is considered to apply to <spanclass="extract"><spanclass="extract-syntax">0</span></span>; so pipelines often never
mention the digits <spanclass="extract"><spanclass="extract-syntax">0</span></span> to <spanclass="extract"><spanclass="extract-syntax">9</span></span> at all because they always work inside <spanclass="extract"><spanclass="extract-syntax">0</span></span>.
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. Dictionary of stages. </b>The following gives a brief guide to the available stages, in alphabetical
order. See also <ahref="../pipeline-module/P-wtmd.html"class="internal">What This Module Does (in pipeline)</a> for how (some of) these
Handles an edge case in linking where a function call in one compilation unit,
e.g., <spanclass="extract"><spanclass="extract-syntax">X(1)</span></span>, turned out more complicated because <spanclass="extract"><spanclass="extract-syntax">X</span></span>, defined in another
compilation unit, was a variable holding the address of a function, and not
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/4-dics.html"class="internal">Detect Indirect Calls Stage (in pipeline)</a>.
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/6-erls.html"class="internal">Eliminate Redundant Labels Stage (in pipeline)</a>.
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/6-erms.html"class="internal">Eliminate Redundant Matter Stage (in pipeline)</a>.
Performs peephole optimisation on functions to remove arithmetic or logical
operations which can be proved to have neither a direct effect nor any
side-effect: for example, performing <spanclass="extract"><spanclass="extract-syntax">x + 0</span></span> rather than just evaluating <spanclass="extract"><spanclass="extract-syntax">x</span></span>.
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/6-eros.html"class="internal">Eliminate Redundant Operations Stage (in pipeline)</a>.
<pclass="commentary">Note that the special destination <spanclass="extract"><spanclass="extract-syntax">*log</span></span> writes to the debugging log rather
<pclass="commentary">The current list of valid formats is: <spanclass="extract"><spanclass="extract-syntax">inform6</span></span>, <spanclass="extract"><spanclass="extract-syntax">c</span></span>, <spanclass="extract"><spanclass="extract-syntax">binary</span></span>, <spanclass="extract"><spanclass="extract-syntax">text</span></span>, <spanclass="extract"><spanclass="extract-syntax">inventory</span></span>.
Of these <spanclass="extract"><spanclass="extract-syntax">binary</span></span> and <spanclass="extract"><spanclass="extract-syntax">text</span></span> are faithful, direct representations of Inter trees;
<spanclass="extract"><spanclass="extract-syntax">inventory</span></span> is a human-readable summary of the contents; but the others are
genuine conversions to code which can be run through other compilers to
Kits are libraries of Inter code which support the operation of Inform programs
at runtime. When "built" (using <ahref="index.html"class="internal">inter</a> with the <spanclass="extract"><spanclass="extract-syntax">build-kit</span></span> pipeline), a
kit provides a binary Inter file of code for each possible architecture. This
stage gathers up all needed kits, and loads them into the current tree, thus
considerably expanding it.
</p>
<pclass="commentary">Note that the list of "needed" kits has to be specified in advance of the pipeline
being run. For Inform compilations, this is handled automatically by the
<ahref="../supervisor-module/index.html"class="internal">supervisor</a> module, but it can also be done via the command line.
</p>
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/4-lbks.html"class="internal">Load Binary Kits Stage (in pipeline)</a>.
<pclass="commentary">At the end of this stage, no symbol still has the <spanclass="extract"><spanclass="extract-syntax">MAKE_NAME_UNIQUE</span></span> flag.
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/4-mius.html"class="internal">Make Identifiers Unique Stage (in pipeline)</a>.
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/2-rmwss.html"class="internal">Read, Move, Wipe, Stop Stages (in pipeline)</a>.
This looks for <spanclass="extract"><spanclass="extract-syntax">LINK_IST</span></span> nodes in the tree, a small number of which may have
been created by the <ahref="../inform7/index.html"class="internal">inform7</a> compiler in response to uses of <spanclass="extract"><spanclass="extract-syntax">Include (- ... -)</span></span>.
These can hold arbitrarily long runs of Inform 6-syntax source code, and what
<spanclass="extract"><spanclass="extract-syntax">parse-insertions</span></span> does is to break then up into splats, one for each statement
or directive. Those won't be much use as they stand, but see <spanclass="extract"><spanclass="extract-syntax">compile-splats</span></span>.
</p>
<pclass="commentary">When this completes, no <spanclass="extract"><spanclass="extract-syntax">LINK_IST</span></span> nodes remain in the tree.
</p>
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/3-ps.html"class="internal">Parsing Stages (in pipeline)</a>.
Copies the contents of the SOURCE file to be the new contents of the tree.
The file must be an Inter file, but can be in either binary or textual format.
</p>
<pclass="commentary">The special source <spanclass="extract"><spanclass="extract-syntax">*memory</span></span> can be used if we already have a tree set up in
slot 0; this is a device used by the <ahref="../supervisor-module/index.html"class="internal">supervisor</a> when managing an Inform
compilation, because <ahref="../inform7/index.html"class="internal">inform7</a> will already have made an Inter tree in
memory, and it would be inefficient to save this out to the file system and
then read it in again.
</p>
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/2-rmwss.html"class="internal">Read, Move, Wipe, Stop Stages (in pipeline)</a>.
Looks for splats arising from Inform 6-syntax conditional compilation directives
such as <spanclass="extract"><spanclass="extract-syntax">#ifdef</span></span>, <spanclass="extract"><spanclass="extract-syntax">#ifndef</span></span>, <spanclass="extract"><spanclass="extract-syntax">#endif</span></span>; it then detects whether the relevant
symbols are defined, or looks at their values, and deletes sections of code not
to be compiled. At the end of this stage, there are no conditional compilation
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/3-rccs.html"class="internal">Resolve Conditional Compilation Stage (in pipeline)</a>.
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/2-rmwss.html"class="internal">Read, Move, Wipe, Stop Stages (in pipeline)</a>.
Empties a tree slot, freeing it up to be used again.
</p>
<pclass="commentary">For the implementation, see <ahref="../pipeline-module/2-rmwss.html"class="internal">Read, Move, Wipe, Stop Stages (in pipeline)</a>.