<ulclass="crumbs"><li><ahref="../webs.html">★</a></li><li><ahref="index.html">inter 1</a></li><li><ahref="index.html#P">Preliminaries</a></li><li><b>Pipelines and Stages</b></li></ul><pclass="purpose">Sequences of named code-generation stages are called pipelines.</p>
<ulclass="toc"><li><ahref="#SP1">§1. Stages and descriptions</a></li><li><ahref="#SP3">§3. Pipelines run by Inform</a></li><li><ahref="#SP4">§4. Stage descriptions</a></li><li><ahref="#SP5">§5. Reading and generating</a></li><li><ahref="#SP6">§6. The code-generation stages</a></li></ul><hrclass="tocbar">
<pclass="inwebparagraph"><aid="SP1"></a><b>§1. Stages and descriptions. </b>A processing stage is a step in code generation which acts on a repository
of inter in memory. Some stages change, add to or edit down that code, while
others leave it untouched but output a file based on it.
</p>
<pclass="inwebparagraph">Each stage can see an entire repository of inter code at a time, and is
not restricted to working through it in sequence.
</p>
<pclass="inwebparagraph">Stages are named, which are written without spaces, and conventionally use
hyphens: for example, <codeclass="display"><spanclass="extract">resolve-conditional-compilation</span></code>. Where a filename has
to be supplied, it appears after a colon. Thus <codeclass="display"><spanclass="extract">generate-inter:my.intert</span></code>
is a valid stage description.
</p>
<pclass="inwebparagraph">A "pipeline" is a list of stage descriptions. If the pipeline is spelled
out textually on the command line, then commas are used to divide the stages:
<pclass="inwebparagraph">creates the variable <codeclass="display"><spanclass="extract">*X</span></code> with the textual contents <codeclass="display"><spanclass="extract">ex/why</span></code> before running
the given pipeline. Inside the pipeline, a line such as:
<pclass="inwebparagraph">After variable substitution like this, filenames inside the pipeline
description are interpreted as follows:
</p>
<pclass="inwebparagraph"></p>
<ulclass="items"><li>(a) If a filename contains a slash character, it is considered a literal
filename.
</li><li>(b) If not, it is considered to be a leafname inside the "domain" directory.
By default this is the current working directory, but using <codeclass="display"><spanclass="extract">-domain</span></code> at
the Inter command line changes that.
</li></ul>
<pclass="inwebparagraph">The special variable <codeclass="display"><spanclass="extract">*log</span></code>, which always exists, means the debugging log.
A command to write a text file to <codeclass="display"><spanclass="extract">*log</span></code> is interpreted instead to mean
"spool the output you would otherwise write to the debugging log instead".
<pclass="inwebparagraph">Template filenames are a little different: those are searched for inside
a path of possible directories. By default there's no such path, but using
<codeclass="display"><spanclass="extract">-template T</span></code> at the Inter command line gives a path of just one directory.
</p>
<pclass="inwebparagraph"><aid="SP3"></a><b>§3. Pipelines run by Inform. </b>As the above implies, Inter pipelines normally begin with a clean slate:
no repositories, no variables.
</p>
<pclass="inwebparagraph">When a pipeline is being run by the main Inform 7 compiler, however,
<codeclass="display"><spanclass="extract">X.materials/I6T</span></code> directory, then in the user's <codeclass="display"><spanclass="extract">I6T</span></code> directory, and failing
that in Inform's built-in one.
</p>
<pclass="inwebparagraph">The pipeline is itself looked for in the same way. If you have a project
called <codeclass="display"><spanclass="extract">Strange.inform</span></code>, then Inform first looks for
<pclass="inwebparagraph">If it can't find this file, it next looks for <codeclass="display"><spanclass="extract">default.interpipeline</span></code> in
the user's folder, and then in Inform's built-in one. If you're curious to
read the pipeline normally used by a shipping version of Inform, the file
can be found here in the Github repository for Inform:
<pclass="inwebparagraph"><aid="SP4"></a><b>§4. Stage descriptions. </b>There are three sorts of stage description: those involving material coming
in, denoted by a left arrow, those involving some external file being written
out, denoted by a right arrow, and those which just process what we have.
<pclass="inwebparagraph">In the first line the location is <codeclass="display"><spanclass="extract">2</span></code>. Pipeline descriptios allow us to manage
up to 10 different repositories, and these are called <codeclass="display"><spanclass="extract">0</span></code> to <codeclass="display"><spanclass="extract">9</span></code>. These are
all initially empty. Any stage which doesn't specify a repository is considered
to apply to <codeclass="display"><spanclass="extract">0</span></code>; plenty of pipelines never mention the digits <codeclass="display"><spanclass="extract">0</span></code> to <codeclass="display"><spanclass="extract">9</span></code> at
all because they do everything inside <codeclass="display"><spanclass="extract">0</span></code>.
</p>
<pclass="inwebparagraph">In the second line, there's no location given, so the location is presumed
to be <codeclass="display"><spanclass="extract">0</span></code>.
</p>
<pclass="inwebparagraph">The third line demonstrates that a location can be more specific than just
a repository: it can be a specific package in a repository. Here, it's
<codeclass="display"><spanclass="extract">/main/template</span></code> in repository <codeclass="display"><spanclass="extract">0</span></code>, but we could also write <codeclass="display"><spanclass="extract">7:/main/template</span></code>
to mean <codeclass="display"><spanclass="extract">/main/template</span></code> in <codeclass="display"><spanclass="extract">7</span></code>, for example. Not all stages allow the
location to be narrowed down to a single package (which by definition
includes all its subpackages): see below.
</p>
<pclass="inwebparagraph"><aid="SP5"></a><b>§5. Reading and generating. </b>The <codeclass="display"><spanclass="extract">read</span></code> stage reads Inter from a file into a repository in memory.
<pclass="inwebparagraph">where <codeclass="display"><spanclass="extract">REPOSITORY</span></code> is <codeclass="display"><spanclass="extract">0</span></code> to <codeclass="display"><spanclass="extract">9</span></code>, and is <codeclass="display"><spanclass="extract">0</span></code> if not supplied. Note that
this fills an entire repository: it's not meaningful to specify a
named package as the location.
</p>
<pclass="inwebparagraph">The <codeclass="display"><spanclass="extract">FILE</span></code> can contain either binary or textual Inter, and this is
<pclass="inwebparagraph">writes the repository out into the given <codeclass="display"><spanclass="extract">FILE</span></code>. There are several possible
formats: <codeclass="display"><spanclass="extract">binary</span></code> and <codeclass="display"><spanclass="extract">text</span></code> mean a binary or textual Inter file, <codeclass="display"><spanclass="extract">inventory</span></code>
means a textual summary of the contents, and <codeclass="display"><spanclass="extract">inform6</span></code> means an Inform 6
program. At present, only <codeclass="display"><spanclass="extract">inventory</span></code> can be generated on specific
<pclass="inwebparagraph"><aid="SP6"></a><b>§6. The code-generation stages. </b>The following are all experimental, and have probably not yet reached their
<pclass="inwebparagraph"><aid="SP7"></a><b>§7. </b><codeclass="display"><spanclass="extract">merge-template <- T</span></code> reads in the I6T template file <codeclass="display"><spanclass="extract">T</span></code>, converts it to
inter in a very basic way (creating many splats), and merges it with the
repository. Splats are the unhappiest of inter statements, simply including
<pclass="inwebparagraph"><aid="SP8"></a><b>§8. </b><codeclass="display"><spanclass="extract">parse-linked-matter</span></code> examines the splats produced by merging and annotates
<pclass="inwebparagraph"><aid="SP9"></a><b>§9. </b><codeclass="display"><spanclass="extract">resolve-conditional-compilation</span></code> looks for splats arising from Inform 6
conditional compilation directives such as <codeclass="display"><spanclass="extract">#ifdef</span></code>, <codeclass="display"><spanclass="extract">#ifndef</span></code>, <codeclass="display"><spanclass="extract">#endif</span></code>;
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 splats left in the repository.
<pclass="inwebparagraph"><aid="SP10"></a><b>§10. </b><codeclass="display"><spanclass="extract">assimilate</span></code> aims to convert all remaining splats in the repository into
<pclass="inwebparagraph"><aid="SP11"></a><b>§11. </b><codeclass="display"><spanclass="extract">make-identifiers-unique</span></code> looks for symbols marked with the <codeclass="display"><spanclass="extract">MAKE_NAME_UNIQUE</span></code>
flag (represented in textual form by an asterisk after its name), This flag
means that Inform wants the symbol name to be globally unique in the repository.
For example, if Inform generates the symbol name <codeclass="display"><spanclass="extract">fruit*</span></code>, it's really telling
the code generator that it eventually wants this to have a name which won't
collide with anything else.
</p>
<pclass="inwebparagraph">What <codeclass="display"><spanclass="extract">make-identifiers-unique</span></code> does is to append <codeclass="display"><spanclass="extract">_U1</span></code>, <codeclass="display"><spanclass="extract">_U2</span></code>, ... to such
names across the repository. Thus <codeclass="display"><spanclass="extract">fruit*</span></code> might become <codeclass="display"><spanclass="extract">fruit_U176</span></code>, and it
is guaranteed that no other symbol has the same name.
</p>
<pclass="inwebparagraph">This stage is needed because whereas the inter language has namespces, so
that the same name can mean different things in different parts of the
program, Inform 6 (mostly) does not. There cannot be two functions with the
same name in any I6 program, for example.
</p>
<pclass="inwebparagraph">At the end of this stage, no symbol still has the <codeclass="display"><spanclass="extract">MAKE_NAME_UNIQUE</span></code> flag.
<pclass="inwebparagraph"><aid="SP12"></a><b>§12. </b><codeclass="display"><spanclass="extract">reconcile-verbs</span></code> is a short stage looking for clashes between any verbs (in
<pclass="inwebparagraph"><aid="SP13"></a><b>§13. </b><codeclass="display"><spanclass="extract">eliminate-redundant-code</span></code> deletes all packages which Inter can prove
<pclass="inwebparagraph"><aid="SP14"></a><b>§14. </b><codeclass="display"><spanclass="extract">eliminate-redundant-labels</span></code> performs peephole optimisation on all of
<pclass="inwebparagraph"><aid="SP15"></a><b>§15. </b>The special stage <codeclass="display"><spanclass="extract">stop</span></code> halts processing of the pipeline midway. At present