<ulclass="toc"><li><ahref="M-ui.html#SP1">§1. What Inter does</a></li><li><ahref="M-ui.html#SP3">§3. Verify only</a></li><li><ahref="M-ui.html#SP4">§4. Format conversion</a></li><li><ahref="M-ui.html#SP5">§5. Running a pipeline</a></li><li><ahref="M-ui.html#SP9">§9. Assimilation</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. What Inter does. </b>"Inter" is the intermediate representation of a program used in the Inform
compiler toolchain. Most compilers have one of these: for example, Microsoft
compilers mostly use "CIL" (common intermediate language), while <spanclass="extract"><spanclass="extract-syntax">gcc</span></span> uses
something called GIMPLE, and so on. See <ahref="../bytecode-module/index.html"class="internal">bytecode</a> for a longer discussion
of what motivates the design of Inter.
</p>
<pclass="commentary">The practical effect is that the back end of the Inform compiler deals only
with Inter code. This back end exists as part of the executable <ahref="../inform7/index.html"class="internal">inform7</a>,
but also as a stand-alone program called <ahref="index.html"class="internal">inter</a>, which comes with its
own command-line interface. Whereas <ahref="../inform7/index.html"class="internal">inform7</a> has a specific task to perform
and uses Inter code only as a means to an end, <ahref="index.html"class="internal">inter</a> is designed to be
as flexible as possible.
</p>
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. </b>Inter code can exist in memory, or in a human-readable text file, or in a
rapid-access binary file. The tool <ahref="index.html"class="internal">inter</a> can convert between these formats:
<pclass="commentary">The Inter tree <spanclass="extract"><spanclass="extract-syntax">T</span></span> starts out empty,<supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> and at the end it is thrown away. So any
useful pipeline will begin by loading something in (usually as step 1), and
end by producing some useful output (usually in its last step or steps).
<ulclass="footnotetexts"><liclass="footnote"id="fn:1"><pclass="inwebfootnote"><supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> Programs in Inter format are called "Inter trees".
<ahref="#fnref:1"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Verify only. </b>If you have compiled the standard distribution of the command-line tools
have the filename extension <spanclass="extract"><spanclass="ConsoleText-extract-syntax">.intert</span></span> or <spanclass="extract"><spanclass="ConsoleText-extract-syntax">.interb</span></span> respectively, but that's
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. Format conversion. </b>In the second mode, Inter not only loads (and verifies) the named file, but
then converts it to a different format and writes that out. For example,
<pclass="commentary">converts <spanclass="extract"><spanclass="ConsoleText-extract-syntax">my.intert</span></span> (a textual inter file) to its binary equivalent <spanclass="extract"><spanclass="ConsoleText-extract-syntax">my.interb</span></span>,
<pclass="commentary">Two parameters must be specified: <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-o</span></span> giving the output file, and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-format=F</span></span>
to say what format <spanclass="extract"><spanclass="ConsoleText-extract-syntax">F</span></span> this should have. Formats are in the same notation as
those used by <ahref="../inbuild/index.html"class="internal">inbuild</a>, which similarly supports <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-o</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-format</span></span>.
In fact, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-format=text</span></span> is the default.
<pclass="commentary">generates a 32-bit-word, debugging-enabled ANSI C program from the Inter tree
in <spanclass="extract"><spanclass="ConsoleText-extract-syntax">my.interb</span></span>, with no <spanclass="extract"><spanclass="ConsoleText-extract-syntax">main</span></span> function included in it.
</p>
<pclass="commentary">As a special case, if <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-o</span></span> is given just as <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-</span></span>, then the output is printed
to the console rather than to a file.
</p>
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. Running a pipeline. </b>If we specify <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-trace</span></span> as a command-line switch, Inter prints out every step
of the pipeline(s) it is following. This reveals that even the simple commands
above are, in fact, running pipelines, albeit short ones:
<pclass="commentary">As this shows, a one or two-step pipeline was running:
</p>
<ulclass="items"><li>(1) The first step used the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">read</span></span> compilation stage, which reads some Inter
code into memory. Here, it comes from the file <spanclass="extract"><spanclass="ConsoleText-extract-syntax">my.intert</span></span>.
</li><li>(2) The second step used the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">generate</span></span> stage, which writes out Inter code
in the format of one's choice — here "binary".
</li></ul>
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. </b>However, we don't have to use this default pipeline. <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-text 'PIPELINE'</span></span>
reads in a textual description of the pipeline to follow, with the steps divided
by commas. The examples above used a pipeline which in this notation would
<pclass="commentary"><spanclass="extract"><spanclass="ConsoleText-extract-syntax">*in</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">*out</span></span> are examples of "pipeline variables". <spanclass="extract"><spanclass="ConsoleText-extract-syntax">*in</span></span> is the filename
of whatever file is to be read in, and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">*out</span></span> is whatever was specified by <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-o</span></span>
at the command line, or in other words, the filename to write the output to.
</p>
<pclass="commentary">This is not quite the smallest possible pipeline. Consider:
<spanclass="ConsoleText-plain-syntax"> step 2/2: generate text -> my.intert</span>
</pre>
<pclass="commentary">Here we didn't specify any Inter file to read in, so <spanclass="extract"><spanclass="ConsoleText-extract-syntax">*in</span></span> does not appear.
Instead wevbegan the pipeline with the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">new</span></span> compilation stage, which creates
a minimal Inter program from nothing.
</p>
<pclass="commentary">Even three-step pipelines can be very useful. For example:
<spanclass="ConsoleText-plain-syntax"> step 3/3: generate text -> my.intert</span>
</pre>
<pclass="commentary">This could be used to test that the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">eliminate-redundant-labels</span></span> compilation
stage is working as it should. We can feed our choice of Inter code into it,
and examine its direct output, in isolation from the working of the rest of
the compiler (and, of course, more quickly).
</p>
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. </b>In practice, it becomes cumbersome to spell the pipeline out longhand on
the command line, so we can also put it into a text file:
<pclass="commentary">It's not allowed to specify both <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-file</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-text</span></span>.
The text file, however, specifies pipelines with one step on each line, not
using commas. So <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-text 'read <- *in, eliminate-redundant-labels, generate -> *out'</span></span>
is equivalent to <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-pipeline-file</span></span> with the file:
<pclass="commentary">For more on how to write and use pipeline files, see <ahref="M-pas.html"class="internal">Pipelines and Stages</a>.
</p>
<pclass="commentary firstcommentary"><aid="SP8"class="paragraph-anchor"></a><b>§8. </b>In general, filenames follow the usual Unix conventions: they are taken as
relative to the current working directory, unless given as absolute filenames
beginning with <spanclass="extract"><spanclass="extract-syntax">/</span></span>. But we can also set a "default directory" to take the
place of the CWD, using <spanclass="extract"><spanclass="extract-syntax">-domain</span></span>:
<pclass="commentary firstcommentary"><aid="SP9"class="paragraph-anchor"></a><b>§9. Assimilation. </b>Inform makes use of what are called "kits" of pre-compiled Inter code:
<pclass="commentary">At present there are four architectures: <spanclass="extract"><spanclass="ConsoleText-extract-syntax">16</span></span>, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">16d</span></span>, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">32</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">32d</span></span>.
Note that an architecture is not the same thing as a format: it specifies
only the word size (16 or 32 bit) and the presence, or not, of debugging data.
<pclass="commentary">looks at the kit <spanclass="extract"><spanclass="ConsoleText-extract-syntax">K</span></span>, works out which architectures need rebuilding, and
<pclass="commentary firstcommentary"><aid="SP10"class="paragraph-anchor"></a><b>§10. </b>Under the hood, assimilation is just another use of pipeline processing. If we
run one of these <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-build-kit</span></span> commands with <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-trace</span></span> switched on, we see
<pclass="commentary">This is in fact the result of running a pipeline file called <spanclass="extract"><spanclass="ConsoleText-extract-syntax">build-kit.interpipeline</span></span>
which is included in the standard Inter distribution.