mirror of
https://github.com/ganelson/inform.git
synced 2024-07-01 06:24:58 +03:00
567 lines
39 KiB
HTML
567 lines
39 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Pipelines and Stages</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/ConsoleText-Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../index.html">home</a></li>
|
|
</ul><h2>Compiler</h2><ul>
|
|
<li><a href="../structure.html">structure</a></li>
|
|
<li><a href="../inbuildn.html">inbuild</a></li>
|
|
<li><a href="../inform7n.html">inform7</a></li>
|
|
<li><a href="../intern.html">inter</a></li>
|
|
<li><a href="../services.html">services</a></li>
|
|
<li><a href="../secrets.html">secrets</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorbn.html">inblorb</a></li>
|
|
<li><a href="../indocn.html">indoc</a></li>
|
|
<li><a href="../inform6.html">inform6</a></li>
|
|
<li><a href="../inpolicyn.html">inpolicy</a></li>
|
|
<li><a href="../inrtpsn.html">inrtps</a></li>
|
|
</ul><h2>Resources</h2><ul>
|
|
<li><a href="../extensions.html">extensions</a></li>
|
|
<li><a href="../kits.html">kits</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inweb/index.html">inweb</a></li>
|
|
<li><a href="../../../intest/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'Pipelines and Stages' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inter</a></li><li><a href="index.html#M">Manual</a></li><li><b>Pipelines and Stages</b></li></ul></div>
|
|
<p class="purpose">Sequences of named code-generation stages are called pipelines.</p>
|
|
|
|
<ul class="toc"><li><a href="M-pas.html#SP1">§1. Variables and filenames</a></li><li><a href="M-pas.html#SP4">§4. Pipelines run by Inform</a></li><li><a href="M-pas.html#SP5">§5. Syntax of pipeline descriptions</a></li><li><a href="M-pas.html#SP7">§7. Dictionary of stages</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. Variables and filenames. </b>For an introduction to pipelines, first read the section <a href="M-ui.html" class="internal">Using Inter</a>.
|
|
</p>
|
|
|
|
<p class="commentary">In that section, two variables <span class="extract"><span class="extract-syntax">*in</span></span> and <span class="extract"><span class="extract-syntax">*out</span></span> appeared, but no others.
|
|
Those were automatically set as needed: <span class="extract"><span class="extract-syntax">*in</span></span> was the file specified first
|
|
in the command, while <span class="extract"><span class="extract-syntax">*out</span></span> was the value of the <span class="extract"><span class="extract-syntax">-o</span></span> output file switch.
|
|
</p>
|
|
|
|
<p class="commentary">In fact, though, any number of variables can be set at the command line.
|
|
<span class="extract"><span class="extract-syntax">-variable '*magicword=zooge'</span></span>, for example, creates the variable <span class="extract"><span class="extract-syntax">*magicword</span></span>
|
|
and sets its initial value to "zooge".
|
|
</p>
|
|
|
|
<p class="commentary">Of course, this has no practical effect unless the pipeline we are running
|
|
makes use of such a variable. But we might imagine running:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inter/Tangled/inter</span><span class="ConsoleText-plain-syntax"> my.intert</span><span class="ConsoleText-identifier-syntax"> -pipeline-file</span><span class="ConsoleText-plain-syntax"> mypl.interpipeline</span><span class="ConsoleText-identifier-syntax"> -variable</span><span class="ConsoleText-plain-syntax"> '*textual=v1.intert'</span><span class="ConsoleText-identifier-syntax"> -variable</span><span class="ConsoleText-plain-syntax"> '*binary=v2.interb'</span>
|
|
</pre>
|
|
<p class="commentary">where <span class="extract"><span class="ConsoleText-extract-syntax">mypl.interpipeline</span></span> reads:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">read <- *in</span>
|
|
<span class="plain-syntax">generate text -> *textual</span>
|
|
<span class="plain-syntax">generate binary -> *binary</span>
|
|
</pre>
|
|
<p class="commentary">This will then write out the same Inter program in two different formats, to
|
|
two different files.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. </b>Variables hold only text, and generally represent filenames. Variable names
|
|
begin with a star <span class="extract"><span class="extract-syntax">*</span></span>. When a pipeline runs, the value of a variable is
|
|
substituted for its name. For example,
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inter/Tangled/inter</span><span class="ConsoleText-identifier-syntax"> -variable</span><span class="ConsoleText-plain-syntax"> '*X=ex/why'</span><span class="ConsoleText-identifier-syntax"> -pipeline-file</span><span class="ConsoleText-plain-syntax"> mypl.interpipeline</span>
|
|
</pre>
|
|
<p class="commentary">creates the variable <span class="extract"><span class="ConsoleText-extract-syntax">*X</span></span> with the textual contents <span class="extract"><span class="ConsoleText-extract-syntax">ex/why</span></span> before running
|
|
the given pipeline. Inside the pipeline, a line such as:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> generate inform6 </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*X</span>
|
|
</pre>
|
|
<p class="commentary">would then be read as:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> generate inform6 </span><span class="reserved-syntax">-></span><span class="plain-syntax"> ex/why</span>
|
|
</pre>
|
|
<p class="commentary">After variable substitution like this, filenames inside the pipeline
|
|
description are interpreted as follows:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) If a filename contains a slash character, it is considered a literal
|
|
filename.
|
|
</li><li>(b) If the filename is just <span class="extract"><span class="extract-syntax">-</span></span>, it is considered to mean the console, that
|
|
is, what in Unix is usually called <span class="extract"><span class="extract-syntax">stdout</span></span>. In other words, output is printed
|
|
rather than saved.
|
|
</li><li>(c) If not, it is considered to be a leafname inside the "domain" directory.
|
|
By default this is the current working directory, but using <span class="extract"><span class="extract-syntax">-domain</span></span> at
|
|
the Inter command line changes that.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>The special variable <span class="extract"><span class="extract-syntax">*log</span></span>, which always exists, means the debugging log.
|
|
A command to write a text file to <span class="extract"><span class="extract-syntax">*log</span></span> is interpreted instead to mean
|
|
"spool the output you would otherwise write to the debugging log instead".
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> generate inventory </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*log</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. Pipelines run by Inform. </b>To Inbuild and Inform, pipelines are resources in their own right, rather
|
|
like extensions or kits. So, for example, the standard distribution includes
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> inform7/Internal/Pipelines/compile.interpipeline</span>
|
|
</pre>
|
|
<p class="commentary">which is the one used for standard compilation runs. A project's Materials
|
|
folder is free to provide a replacement:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Strange.materials/Pipelines/compile.interpipeline</span>
|
|
</pre>
|
|
<p class="commentary">...and then this will be used instead when compiling <span class="extract"><span class="extract-syntax">Strange.inform</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">1. This sentence in Inform source text:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Use inter pipeline "NAME".</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">replaces the pipeline normally used for code generation with the one supplied.
|
|
(That may very well cause the compiler not to produce viable code, of course.)
|
|
The default Inter pipeline is called <span class="extract"><span class="extract-syntax">compile</span></span>, and comes built-in. Named
|
|
pipelines are stored alongside named extensions and other resources used by
|
|
Inform; so for example you could write:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Use inter pipeline "mypipeline".</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">And then store the actual pipeline file as:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Example Work.materials/Pipelines/mypipeline.interpipeline</span>
|
|
</pre>
|
|
<p class="commentary">2. You don't need the Use... sentence, though, if you're willing to choose
|
|
on the command line instead:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inform7/Tangled/inform7</span><span class="ConsoleText-plain-syntax"> ...</span><span class="ConsoleText-identifier-syntax"> -pipeline</span><span class="ConsoleText-plain-syntax"> NAME</span>
|
|
</pre>
|
|
<p class="commentary">Or, if you want to name a file explicitly, not have it looked for by name:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inform7/Tangled/inform7</span><span class="ConsoleText-plain-syntax"> ...</span><span class="ConsoleText-identifier-syntax"> -pipeline-file</span><span class="ConsoleText-plain-syntax"> FILE</span>
|
|
</pre>
|
|
<p class="commentary">3. Finally, you can also give Inform 7 an explicit pipeline in textual form:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-element-syntax">$</span><span class="ConsoleText-plain-syntax"> </span><span class="ConsoleText-function-syntax">inform7/Tangled/inform7</span><span class="ConsoleText-plain-syntax"> ...</span><span class="ConsoleText-identifier-syntax"> -pipeline-text</span><span class="ConsoleText-plain-syntax"> 'PIPELINE'</span>
|
|
</pre>
|
|
<p class="commentary">Note that Inbuild and Inform 7 respond to all three of <span class="extract"><span class="ConsoleText-extract-syntax">-pipeline</span></span>,
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">-pipeline-file</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">-pipeline-text</span></span>, whereas Inter responds only to the
|
|
last two. (It can't find pipelines by name because it doesn't contain the
|
|
supervisor module for sorting out resources.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. 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 <span class="extract"><span class="ConsoleText-extract-syntax">!</span></span>, which are considered comments.
|
|
</p>
|
|
|
|
<p class="commentary">A step description is often as simple as being the name of a stage, but
|
|
sometimes that name is accompanied by parameters.
|
|
</p>
|
|
|
|
<p class="commentary">The difference between a step and a stage is illustrated by this example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="comment-syntax">This is a comment</span>
|
|
|
|
<span class="plain-syntax"> read </span><span class="reserved-syntax"><-</span><span class="plain-syntax"> </span><span class="identifier-syntax">*in</span>
|
|
|
|
<span class="plain-syntax"> generate text </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*tout</span>
|
|
<span class="plain-syntax"> generate binary </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*bout</span>
|
|
</pre>
|
|
<p class="commentary">Here there are three steps. The first uses the <span class="extract"><span class="extract-syntax">read</span></span> stage; the second and
|
|
third use the <span class="extract"><span class="extract-syntax">generate</span></span> stage, but with different parameters.
|
|
</p>
|
|
|
|
<p class="commentary">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.
|
|
These take the following forms:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> STAGENAME [TREE] </span><span class="reserved-syntax"><-</span><span class="plain-syntax"> SOURCE</span>
|
|
<span class="plain-syntax"> STAGENAME [TREE] [FORMAT] </span><span class="reserved-syntax">-></span><span class="plain-syntax"> DESTINATION</span>
|
|
<span class="plain-syntax"> STAGENAME [TREE]</span>
|
|
</pre>
|
|
<p class="commentary">The <span class="extract"><span class="extract-syntax">STAGENAME</span></span> never contains white space; hyphens are used instead. So, for
|
|
example, <span class="extract"><span class="extract-syntax">eliminate-redundant-labels</span></span> is a valid <span class="extract"><span class="extract-syntax">STAGENAME</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">The <span class="extract"><span class="extract-syntax">[TREE]</span></span> is optional. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> read </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="reserved-syntax"><-</span><span class="plain-syntax"> </span><span class="identifier-syntax">*in</span>
|
|
<span class="plain-syntax"> generate </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*out</span>
|
|
</pre>
|
|
<p class="commentary">Pipeline descriptions allow us to manage up to 10 different Inter trees, and
|
|
these are called <span class="extract"><span class="extract-syntax">0</span></span> to <span class="extract"><span class="extract-syntax">9</span></span>. These are all initially empty. Any stage which
|
|
doesn't specify a tree is considered to apply to <span class="extract"><span class="extract-syntax">0</span></span>; so pipelines often never
|
|
mention the digits <span class="extract"><span class="extract-syntax">0</span></span> to <span class="extract"><span class="extract-syntax">9</span></span> at all because they always work inside <span class="extract"><span class="extract-syntax">0</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Another optional feature, not currently made use of by any stages, is that
|
|
the description can specify an exact package in a tree, giving its name in URL
|
|
form. Thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> hypothetical-stage /main/whatever</span>
|
|
<span class="plain-syntax"> hypothetical-stage </span><span class="constant-syntax">6</span><span class="plain-syntax">:/main/whatever</span>
|
|
</pre>
|
|
<p class="commentary">The stages currently built in to <a href="index.html" class="internal">inter</a> do not work on individual packages,
|
|
but they did at one time in the past, and the infrastructure for it remains
|
|
in case useful in future.
|
|
</p>
|
|
|
|
<p class="commentary">SOURCE and DESTINATION specify, usually, files to read or write, but they are
|
|
often in fact given as variables, whose names start with an asterisk <span class="extract"><span class="extract-syntax">*</span></span>.
|
|
Variables have to be set in advance, either at the command line (see above)
|
|
or by the tool calling for the pipeline to be run, e.g., the <a href="../supervisor-module/index.html" class="internal">supervisor</a>
|
|
module inside Inform 7.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>Pipelines can also include each other. For example, the step:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> run pipeline assimilate</span>
|
|
</pre>
|
|
<p class="commentary">causes the whole <span class="extract"><span class="extract-syntax">assimilate</span></span> pipeline to be run at that point. Indeed, Inform 7's
|
|
main pipeline <span class="extract"><span class="extract-syntax">compile</span></span> uses this to break its task into subtasks:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">read </span><span class="reserved-syntax"><-</span><span class="plain-syntax"> </span><span class="identifier-syntax">*in</span>
|
|
|
|
<span class="plain-syntax">run pipeline assimilate</span>
|
|
<span class="plain-syntax">run pipeline link</span>
|
|
<span class="plain-syntax">run pipeline optimise</span>
|
|
|
|
<span class="comment-syntax">The following does nothing if the variable *tout does not exist and it</span>
|
|
<span class="comment-syntax">will exist only when debugging:</span>
|
|
<span class="plain-syntax">optionally-generate text </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*tout</span>
|
|
|
|
<span class="plain-syntax">generate </span><span class="reserved-syntax">-></span><span class="plain-syntax"> </span><span class="identifier-syntax">*out</span>
|
|
<span class="plain-syntax">index</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. Dictionary of stages. </b>The following gives a brief guide to the available stages, in alphabetical
|
|
order. See also <a href="../pipeline-module/P-wtmd6.html" class="internal">What This Module Does (in pipeline)</a> for how (some of) these
|
|
stages are used when building kits or projects.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b><span class="extract"><span class="extract-syntax">compile-splats</span></span>.
|
|
A "splat" node holds a single Inform 6-written statement or directive, and
|
|
thus represents not-yet-compiled material. This stage converts all remaining
|
|
splat nodes to Inter code. Note that <span class="extract"><span class="extract-syntax">resolve-conditional-compilation</span></span> must
|
|
already have run for this to handle <span class="extract"><span class="extract-syntax">#ifdef</span></span> and the like properly.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/3-css.html" class="internal">Compile Splats Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b><span class="extract"><span class="extract-syntax">detect-indirect-calls</span></span>.
|
|
Handles an edge case in linking where a function call in one compilation unit,
|
|
e.g., <span class="extract"><span class="extract-syntax">X(1)</span></span>, turned out more complicated because <span class="extract"><span class="extract-syntax">X</span></span>, defined in another
|
|
compilation unit, was a variable holding the address of a function, and not
|
|
as expected the name of a specific function.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/4-dics.html" class="internal">Detect Indirect Calls Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. </b><span class="extract"><span class="extract-syntax">eliminate-redundant-labels</span></span>.
|
|
Performs peephole optimisation on functions to remove all labels which are
|
|
declared but can never be jumped to. At the end of this stage, all labels
|
|
inside functions are targets of some branch, either by <span class="extract"><span class="extract-syntax">inv !jump</span></span> or in
|
|
assembly language.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/6-erls.html" class="internal">Eliminate Redundant Labels Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. </b><span class="extract"><span class="extract-syntax">eliminate-redundant-matter</span></span>.
|
|
Works through the dependency graph of the Inter tree to find packages which
|
|
are never needed (such as functions never called), and remove them, thus
|
|
making the final executable smaller.
|
|
</p>
|
|
|
|
<p class="commentary">Note that this is experimental, does not yet properly work, and is not used
|
|
in the built-in <span class="extract"><span class="extract-syntax">compile</span></span> pipeline.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/6-erms.html" class="internal">Eliminate Redundant Matter Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>§12. </b><span class="extract"><span class="extract-syntax">eliminate-redundant-operations</span></span>.
|
|
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 <span class="extract"><span class="extract-syntax">x + 0</span></span> rather than just evaluating <span class="extract"><span class="extract-syntax">x</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/6-eros.html" class="internal">Eliminate Redundant Operations Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>§13. </b><span class="extract"><span class="extract-syntax">generate [FORMAT] -> [DESTINATION]</span></span>.
|
|
Produces "final code" in some format, writing it to an external file specified
|
|
as the destination. If not given, the format will be the one chosen by the
|
|
<a href="../supervisor-module/index.html" class="internal">supervisor</a> module.
|
|
</p>
|
|
|
|
<p class="commentary">Note that the special destination <span class="extract"><span class="extract-syntax">*log</span></span> writes to the debugging log rather
|
|
than to some other external file.
|
|
</p>
|
|
|
|
<p class="commentary">The current list of valid formats is: <span class="extract"><span class="extract-syntax">inform6</span></span>, <span class="extract"><span class="extract-syntax">c</span></span>, <span class="extract"><span class="extract-syntax">binary</span></span>, <span class="extract"><span class="extract-syntax">text</span></span>, <span class="extract"><span class="extract-syntax">inventory</span></span>.
|
|
Of these <span class="extract"><span class="extract-syntax">binary</span></span> and <span class="extract"><span class="extract-syntax">text</span></span> are faithful, direct representations of Inter trees;
|
|
<span class="extract"><span class="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
|
|
make executable programs.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../final-module/2-cg.html" class="internal">Code Generation (in final)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>§14. </b><span class="extract"><span class="extract-syntax">index</span></span>.
|
|
This is functional only when run as part of the compilation pipeline used on
|
|
code generated by Inform 7; it will (silently) do nothing if used in any other
|
|
pipeline. Depending on command-line settings, it also updates extension documentation
|
|
and generates an EPS form of the map of an IF project.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../index-module/1-is.html" class="internal">Index Stage (in index)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>§15. </b><span class="extract"><span class="extract-syntax">load-binary-kits</span></span>.
|
|
Kits are libraries of Inter code which support the operation of Inform programs
|
|
at runtime. When "built" (using <a href="index.html" class="internal">inter</a> with the <span class="extract"><span class="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>
|
|
|
|
<p class="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
|
|
<a href="../supervisor-module/index.html" class="internal">supervisor</a> module, but it can also be done via the command line.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/4-lbks.html" class="internal">Load Binary Kits Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>§16. </b><span class="extract"><span class="extract-syntax">load-kit-source <- [SOURCE]</span></span>.
|
|
Reads a file of Inform 6-syntax source code and adds the resulting material to
|
|
the Inter tree in the form of a series of "splat" nodes, one for each statement
|
|
or directive. Those won't be much use as they stand, but see <span class="extract"><span class="extract-syntax">compile-splats</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/3-ps.html" class="internal">Parsing Stages (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>§17. </b><span class="extract"><span class="extract-syntax">make-identifiers-unique</span></span>.
|
|
Ensures that symbols marked as needing to be unique will be translated, during
|
|
any use of <span class="extract"><span class="extract-syntax">generate</span></span>, to identifiers which are all different from each other
|
|
across the entire tree. (In effect, this stage is needed because Inter has
|
|
private namespaces within packages, whereas the languages we are transpiling to —
|
|
to some extent C, but certainly Inform 6 — have a single global namespace,
|
|
where collisions of identifiers would be very unfortunate.)
|
|
</p>
|
|
|
|
<p class="commentary">At the end of this stage, no symbol still has the <span class="extract"><span class="extract-syntax">MAKE_NAME_UNIQUE_ISYMF</span></span> flag.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/4-mius.html" class="internal">Make Identifiers Unique Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>§18. </b><span class="extract"><span class="extract-syntax">make-synoptic-module</span></span>.
|
|
The synoptic module is a top-level section of material in the Inter tree which
|
|
contains functions and arrays which index or otherwise gather up material
|
|
ranging across all other modules. For example, each module originally presents
|
|
itself with its own pieces of literal text, but the synoptic module then
|
|
collates all of those together, sorted and de-duplicated.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/5-msms.html" class="internal">Make Synoptic Module Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>§19. </b><span class="extract"><span class="extract-syntax">move <- LOCATION</span></span>.
|
|
This moves a branch of one Inter tree to a position in another one, reconciling
|
|
the necessary symbol dependencies. For example, <span class="extract"><span class="extract-syntax">move 1 <- 3:/main/my_fn</span></span>
|
|
moves the package <span class="extract"><span class="extract-syntax">/main/my_fn</span></span> in tree 3 to the same position in tree 1.
|
|
Note that this is a move, not a copy, and is as fast an operation as we can
|
|
make it.
|
|
</p>
|
|
|
|
<p class="commentary">This stage is not used in the regular Inform pipelines, but exists to assist
|
|
testing of the so-called "transmigration" process, which powers <span class="extract"><span class="extract-syntax">load-binary-kits</span></span>
|
|
(see above).
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/2-rmss.html" class="internal">Read, Move, Stop Stages (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>§20. </b><span class="extract"><span class="extract-syntax">new</span></span>.
|
|
A completely empty Inter tree is not very useful. <span class="extract"><span class="extract-syntax">new</span></span> adds the very basic
|
|
definitions needed, and gives it a <span class="extract"><span class="extract-syntax">/main</span></span> package.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/2-ns.html" class="internal">New Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>§21. </b><span class="extract"><span class="extract-syntax">optionally-generate [FORMAT] -> DESTINATION</span></span>.
|
|
This is identical to <span class="extract"><span class="extract-syntax">generate</span></span> except that if the DESTINATION is given as
|
|
a variable which does not exist then no error is produced, and nothing is done.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../final-module/2-cg.html" class="internal">Code Generation (in final)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP22" class="paragraph-anchor"></a><b>§22. </b><span class="extract"><span class="extract-syntax">parse-insertions</span></span>.
|
|
This looks for <span class="extract"><span class="extract-syntax">INSERT_IST</span></span> nodes in the tree, a small number of which may have
|
|
been created by the <a href="../inform7/index.html" class="internal">inform7</a> compiler in response to uses of <span class="extract"><span class="extract-syntax">Include (- ... -)</span></span>.
|
|
These can hold arbitrarily long runs of Inform 6-syntax source code, and what
|
|
<span class="extract"><span class="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 <span class="extract"><span class="extract-syntax">compile-splats</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">When this completes, no <span class="extract"><span class="extract-syntax">INSERT_IST</span></span> nodes remain in the tree.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/3-ps.html" class="internal">Parsing Stages (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP23" class="paragraph-anchor"></a><b>§23. </b><span class="extract"><span class="extract-syntax">read <- SOURCE</span></span>.
|
|
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>
|
|
|
|
<p class="commentary">The special source <span class="extract"><span class="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 <a href="../supervisor-module/index.html" class="internal">supervisor</a> when managing an Inform
|
|
compilation, because <a href="../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>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/2-rmss.html" class="internal">Read, Move, Stop Stages (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP24" class="paragraph-anchor"></a><b>§24. </b><span class="extract"><span class="extract-syntax">reconcile-verbs</span></span>.
|
|
Looks for clashes between any verbs (i.e., command parser imperatives like
|
|
PURLOIN or LOOK) which are created in different compilation units. For example,
|
|
if the main source text creates a verb called ABSTRACT, which clashes with the
|
|
completely different command ABSTRACT defined in <span class="extract"><span class="extract-syntax">CommandParserKit</span></span> for debugging
|
|
purposes, then how is the player to differentiate these? The <span class="extract"><span class="extract-syntax">reconcile-verbs</span></span>
|
|
stage inserts <span class="extract"><span class="extract-syntax">!</span></span> characters in the kit definitions where such clashes occur;
|
|
thus ABSTRACT would be the source-text-defined command, and !ABSTRACT the
|
|
kit-defined one.
|
|
</p>
|
|
|
|
<p class="commentary">At the end of this stage, all command parser verbs have distinct textual forms.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/4-rvs.html" class="internal">Reconcile Verbs Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP25" class="paragraph-anchor"></a><b>§25. </b><span class="extract"><span class="extract-syntax">resolve-conditional-compilation</span></span>.
|
|
Looks for splats arising from Inform 6-syntax conditional compilation directives
|
|
such as <span class="extract"><span class="extract-syntax">#ifdef</span></span>, <span class="extract"><span class="extract-syntax">#ifndef</span></span>, <span class="extract"><span class="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
|
|
splats left in the tree. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int32</span><span class="plain-syntax">) MAGIC = </span><span class="constant-syntax">12345</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">splat</span><span class="plain-syntax"> IFTRUE &</span><span class="string-syntax">"#iftrue MAGIC == 12345;\n"</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int32</span><span class="plain-syntax">) WIZARD = </span><span class="constant-syntax">5</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">splat</span><span class="plain-syntax"> IFNOT &</span><span class="string-syntax">"#ifnot;\n"</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int32</span><span class="plain-syntax">) MUGGLE = </span><span class="constant-syntax">0</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">splat</span><span class="plain-syntax"> ENDIF &</span><span class="string-syntax">"#endif;\n"</span>
|
|
</pre>
|
|
<p class="commentary">is resolved to:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int32</span><span class="plain-syntax">) MAGIC = </span><span class="constant-syntax">12345</span>
|
|
<span class="plain-syntax"> </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int32</span><span class="plain-syntax">) WIZARD = </span><span class="constant-syntax">5</span>
|
|
</pre>
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/3-rccs.html" class="internal">Resolve Conditional Compilation Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP26" class="paragraph-anchor"></a><b>§26. </b><span class="extract"><span class="extract-syntax">shorten-wiring</span></span>.
|
|
Wiring is the process by which symbols in one package can refer to definitions
|
|
in another one; we say S is wired to T if S in one package refers to the meaning
|
|
defined by T is another one. The linking process can result in extended chains
|
|
of wiring, with A wired to B which is wired to C which... and so on; the
|
|
<span class="extract"><span class="extract-syntax">shorten-wiring</span></span> stage cuts out those intermediate links so that if a symbol
|
|
S is wired to T then T is not wired to anything else.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/4-sws.html" class="internal">Shorten Wiring Stage (in pipeline)</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP27" class="paragraph-anchor"></a><b>§27. </b><span class="extract"><span class="extract-syntax">stop</span></span>.
|
|
The special stage <span class="extract"><span class="extract-syntax">stop</span></span> halts processing of the pipeline midway. At present
|
|
this is only useful for making experimental edits to pipeline descriptions
|
|
to see what just the first half does, without deleting the second half of
|
|
the description.
|
|
</p>
|
|
|
|
<p class="commentary">For the implementation, see <a href="../pipeline-module/2-rmss.html" class="internal">Read, Move, Stop Stages (in pipeline)</a>.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-io.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresssection"><a href="M-ti.html">ti</a></li><li class="progresssection"><a href="M-dpiti.html">dpiti</a></li><li class="progresssection"><a href="M-cpiti.html">cpiti</a></li><li class="progresssection"><a href="M-ip.html">ip</a></li><li class="progresssection"><a href="M-ia.html">ia</a></li><li class="progresssection"><a href="M-io.html">io</a></li><li class="progresscurrent">pas</li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-rc.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|