ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-02 23:14:57 +03:00
Code Issues Projects Releases Wiki Activity

Extended Inter manual to cover stages

Browse source
This commit is contained in:
Graham Nelson 2019-03-19 12:11:09 +00:00
parent 661c585e16
commit 7d93f1473c
7 changed files with 488 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/inter/1-bsc.html
View file

@ -1,7 +1,7 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>P/ui</title>
<title>P/cas</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">

281
docs/inter/P-cas.html Normal file
View file

@ -0,0 +1,281 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>P/ui</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body>
<!--Weave of 'P/cas' generated by 7-->
<ul class="crumbs"><li><a href="../webs.html">&#9733;</a></li><li><a href="index.html">inter 1</a></li><li><a href="index.html#P">Preliminaries</a></li><li><b>Chains and Stages</b></li></ul><p class="purpose">Sequences of named code-generation stages are called chains.</p>
<ul class="toc"><li><a href="#SP1">&#167;1. Stages and descriptions</a></li><li><a href="#SP3">&#167;3. The code-generation stages</a></li><li><a href="#SP13">&#167;13. Diagnostic or non-working stages</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. Stages and descriptions. </b>Inter code has three representations: as a binary file, as a textual file,
and in memory &mdash; a sort of cross-referenced form of binary. For speed, the
Inform compiler generates memory inter directly, and code-generates from
that, so that the inter is normally never written out to disc. When Inter
performs a conversion, it loads (say) textual inter into memory inter, then
writes that out as binary inter.
</p>
<p class="inwebparagraph">A processing stage is a step in code generation which acts on memory inter.
Some stages change, add to or edit down that code, while others leave it
untouched but output a file based on it.
</p>
<p class="inwebparagraph">Each stage can see an entire "repository" of inter code at a time, and is
not restricted to working through in sequence. Those which read in or write
out a file also have a filename supplied to them as a parameter, but there
are otherwise no configuration options. It's not possible to tell a stage
to work on one specific function alone, for example.
</p>
<p class="inwebparagraph">Stages are named, which are written without spaces, and conventionally use
hyphens: for example, <code class="display"><span class="extract">resolve-conditional-compilation</span></code>. Where a filename has
to be supplied, it appears after a colon. Thus <code class="display"><span class="extract">generate-inter:my.intert</span></code>
is a valid stage description.
</p>
<p class="inwebparagraph">A "chain" is a comma-separated list of stage descriptions, and represents a
sort of program to follow: memory inter is passed through each stage in turn.
The special stage <code class="display"><span class="extract">stop</span></code> halts processing of the chain midway. At present
this is only useful for making experimental edits to chain descriptions
to see what just the first half does, without deleting the second half of
the description.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>There are three ways to use chains. One is from the command line of Inter:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">$ inter/Tangled/inter FILE -inter 'CHAIN'</span>
</pre>
<p class="inwebparagraph">The other is to use two experimental features of Inform. This sentence:
</p>
<blockquote>
<p>Use inter chain "STAGES".</p>
</blockquote>
<p class="inwebparagraph">replaces the chain normally used for code generation with the one supplied.
(This may very well cause the compiler not to produce viable code, of course.)
Equivalently, a replacement chain can be specified at the Inform 7 command line:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">$ inform7/Tangled/inform7 ... -inter 'CHAIN'</span>
</pre>
<p class="inwebparagraph">When using a chain within Inform, one further description syntax is allowed:
the filename <code class="display"><span class="extract">*</span></code> means "the filename Inform wants to use for the final
Inform 6 file". This tends to be used for the final stage in the chain, which
is normally <code class="display"><span class="extract">generate-i6:*</span></code>.
</p>
<p class="inwebparagraph"><a id="SP3"></a><b>&#167;3. The code-generation stages. </b>The following are all experimental, and have probably not yet reached their
final form or names. But this briefly describes the stages which currently
exist in the code generator. In the description below, the "repository" is
the reservoir of memory inter code being worked on.
</p>
<p class="inwebparagraph">Although one thinks of code generation as a process of turning inter into
Inform 6, in fact it goes both ways, because we also have to read in
the "template" of standing Inform 6 code. The early code generation stages
convert the template from Inform 6 into inter, merging it with the inter
already produced by the front end of the compiler. The later stages then
turn this merged repository into Inform 6 code. (Routines in the template,
therefore, are converted out of Inform 6 and then back into it again. This
sounds inefficient but is surprisingly fast, and enables many optimisations.)
</p>
<p class="inwebparagraph"><a id="SP4"></a><b>&#167;4. </b><code class="display"><span class="extract">link:T</span></code> reads in the I6T template file T, 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 verbatim snippets
of Inform 6 code.
</p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b><code class="display"><span class="extract">parse-linked-matter</span></code> examines the splats produced by linking and annotates
them by what they seem to want to do. For example,
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">splat &amp;"Global nitwit = 2;\n"</span>
</pre>
<p class="inwebparagraph">is recognised as an Inform 6 variable declaration, and annotated thus:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">splat GLOBAL &amp;"Global nitwit = 2;\n"</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b><code class="display"><span class="extract">resolve-conditional-compilation</span></code> looks for splats arising from Inform 6
conditional compilation directives such as <code class="display"><span class="extract">#ifdef</span></code>, <code class="display"><span class="extract">#ifndef</span></code>, <code class="display"><span class="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.
For example:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">constant MAGIC K_number = 16339</span>
<span class="plain">splat IFTRUE &amp;"#iftrue MAGIC == 16339;\n"</span>
<span class="plain">constant WIZARD K_number = 5</span>
<span class="plain">splat IFNOT &amp;"#ifnot;\n"</span>
<span class="plain">constant MUGGLE K_number = 0</span>
<span class="plain">splat ENDIF &amp;"#endif;\n"</span>
</pre>
<p class="inwebparagraph">is resolved to:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">constant MAGIC K_number = 16339</span>
<span class="plain">constant WIZARD K_number = 5</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP7"></a><b>&#167;7. </b><code class="display"><span class="extract">assimilate</span></code> aims to convert all remaining splats in the repository into
higher-level inter statements. For example,
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">splat STUB &amp;"#Stub Peach 0;\n"</span>
<span class="plain">splat ATTRIBUTE &amp;"Attribute marmorial;\n"</span>
</pre>
<p class="inwebparagraph">becomes:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">constant Peach K_unchecked_function = Peach_B __assimilated=1</span>
<span class="plain">property marmorial K_truth_state __assimilated=1 __attribute=1 __either_or=1</span>
</pre>
<p class="inwebparagraph">At the end of this stage, there should be no splats left in the repository,
and the linking process is complete.
</p>
<p class="inwebparagraph"><a id="SP8"></a><b>&#167;8. </b><code class="display"><span class="extract">make-identifiers-unique</span></code> looks for symbols marked with the <code class="display"><span class="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 <code class="display"><span class="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>
<p class="inwebparagraph">What <code class="display"><span class="extract">make-identifiers-unique</span></code> does is to append <code class="display"><span class="extract">_U1</span></code>, <code class="display"><span class="extract">_U2</span></code>, ... to such
names across the repository. Thus <code class="display"><span class="extract">fruit*</span></code> might become <code class="display"><span class="extract">fruit_U176</span></code>, and it
is guaranteed that no other symbol has the same name.
</p>
<p class="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>
<p class="inwebparagraph">At the end of this stage, no symbol still has the <code class="display"><span class="extract">MAKE_NAME_UNIQUE</span></code> flag.
</p>
<p class="inwebparagraph"><a id="SP9"></a><b>&#167;9. </b><code class="display"><span class="extract">reconcile-verbs</span></code> is a short stage looking for clashes between any verbs (in
the parser interactive fiction sense) which have been assimilated from the
template, and verbs which have been defined in the main source text. For
example, suppose the source creates the command verb "abstract": this would
collide with the command meta-verb "abstract", intended for debugging, which
appears in the template. What this stage does is to detect such problems,
and if it finds one, to prefix the template verb with <code class="display"><span class="extract">!</span></code>. Thus we would end
up with two command verbs: <code class="display"><span class="extract">abstract</span></code>, with its source text meaning, and
<code class="display"><span class="extract">!abstract</span></code>, with its template meaning.
</p>
<p class="inwebparagraph">At the end of this stage, all parser verbs have distinct textual forms.
</p>
<p class="inwebparagraph"><a id="SP10"></a><b>&#167;10. </b><code class="display"><span class="extract">generate-inter:F</span></code> writes out the repository as a textual inter file <code class="display"><span class="extract">F</span></code>.
(By default, Inform doesn't do this: the inter ordinarily stays in memory
throughout.)
</p>
<p class="inwebparagraph">This stage leaves the repository unchanged.
</p>
<p class="inwebparagraph"><a id="SP11"></a><b>&#167;11. </b><code class="display"><span class="extract">generate-inter-binary:F</span></code> writes out the repository as a binary inter
file <code class="display"><span class="extract">F</span></code>. (By default, Inform doesn't do this: the inter ordinarily stays in
memory throughout.)
</p>
<p class="inwebparagraph">This stage leaves the repository unchanged.
</p>
<p class="inwebparagraph"><a id="SP12"></a><b>&#167;12. </b><code class="display"><span class="extract">generate-i6:F</span></code> translates the repository to an Inform 6 program. This is
normally the final stage in the Inform code generation chain.
</p>
<p class="inwebparagraph">This stage leaves the repository unchanged.
</p>
<p class="inwebparagraph"><a id="SP13"></a><b>&#167;13. Diagnostic or non-working stages. </b></p>
<p class="inwebparagraph"><a id="SP14"></a><b>&#167;14. </b><code class="display"><span class="extract">show-dependencies:F</span></code> and <code class="display"><span class="extract">log-dependencies</span></code> output a dependency graph of
the symbols in the current repository, one to a file, the other to the
debugging log. A dependency means that one can't be compiled without the
other: for example, if a function has a local variable of a given kind, then
the function depends on that kind.
</p>
<p class="inwebparagraph"><code class="display"><span class="extract">eliminate-redundant-code</span></code> is a stage which removes all material from
the repository which the main routine is not dependent on. This can result
in many template routines being kicked out, and substantially reduces
story file sizes. The stage mostly works, but needs more refinement before
we could safely enable it by default with Inform.
</p>
<p class="inwebparagraph"><a id="SP15"></a><b>&#167;15. </b><code class="display"><span class="extract">summarise:F</span></code> is a very slow diagnostic stage showing the breakdown of the
current repository into packages, writing the output to file <code class="display"><span class="extract">F</span></code>. (Slow in
this sense means that it roughly triples compilation time.)
</p>
<p class="inwebparagraph"><a id="SP16"></a><b>&#167;16. </b><code class="display"><span class="extract">export:F</span></code> and <code class="display"><span class="extract">import:F</span></code> were part of an experiment to do with caching the
inter generated by the Standard Rules. This eventually worked, but was put on
ice while a better and more systematic solution was found.
</p>
<hr class="tocbar">
<ul class="toc"><li><a href="P-ui.html">Back to 'Using Inter'</a></li><li><i>(This section ends Preliminaries.)</i></li></ul><hr class="tocbar">
<!--End of weave-->
</body>
</html>

37
docs/inter/P-ui.html
View file

@ -9,9 +9,11 @@
<body>
<!--Weave of 'P/ui' generated by 7-->
<ul class="crumbs"><li><a href="../webs.html">&#9733;</a></li><li><a href="index.html">inter 1</a></li><li><a href="index.html#P">Preliminaries</a></li><li><b>Using Inter</b></li></ul><p class="purpose">A brief user guide.</p>
<ul class="crumbs"><li><a href="../webs.html">&#9733;</a></li><li><a href="index.html">inter 1</a></li><li><a href="index.html#P">Preliminaries</a></li><li><b>Using Inter</b></li></ul><p class="purpose">Using Inter at the command line.</p>
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. </b>The command-line executable Inter packages up the back end of the Inform 7
<ul class="toc"><li><a href="#SP1">&#167;1. What Inter does</a></li><li><a href="#SP2">&#167;2. Command-line usage</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;1. What Inter does. </b>The command-line executable Inter packages up the back end of the Inform 7
compiler into a stand-alone tool, and enables that back end to be used more
flexibly. For example, it can read or write either textual or binary inter
code, and can convert between them. It can also perform any of the numerous
@ -26,7 +28,7 @@ what Inform is doing; it also provides a test-bed for future optimisation,
or for future applications of inter code.
</p>
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. </b>If you have compiled the standard distribution of the command-line tools
<p class="inwebparagraph"><a id="SP2"></a><b>&#167;2. Command-line usage. </b>If you have compiled the standard distribution of the command-line tools
for Inform then the Inter executable will be at <code class="display"><span class="extract">inter/Tangled/inter</span></code>.
The usage is:
</p>
@ -79,7 +81,7 @@ and <code class="display"><span class="extract">-textual X</span></code> writes
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP5"></a><b>&#167;5. </b>In the third and most flexible mode, Inter runs the supplied code through
a chain of processing stages. The chain, which must contain at least
a "chain" of processing stages. The chain, which must contain at least
one stage, is a textual list of comma-separated stage names. For example,
</p>
@ -97,10 +99,10 @@ one stage, is a textual list of comma-separated stage names. For example,
<pre class="display">
<span class="plain">$ inter/Tangled/inter my.intert -binary -inter 'STAGES'</span>
<span class="plain">$ inter/Tangled/inter my.intert -inter 'CHAIN'</span>
</pre>
<p class="inwebparagraph">where <code class="display"><span class="extract">STAGES</span></code> is the chain description.
<p class="inwebparagraph">where <code class="display"><span class="extract">CHAIN</span></code> is the chain description.
</p>
<p class="inwebparagraph">In practice, this will only be useful if you can access the result, so it's
@ -121,29 +123,8 @@ and <code class="display"><span class="extract">-template T</span></code> tells
the file system location <code class="display"><span class="extract">T</span></code>. (Some code-generation stages import these.)
</p>
<p class="inwebparagraph"><a id="SP6"></a><b>&#167;6. </b>Inform itself currently has an undocumented feature to enable similar
experimentation. The "use" sentence:
</p>
<blockquote>
<p>Use inter chain "STAGES".</p>
</blockquote>
<p class="inwebparagraph">works in exactly the same way, so for example:
</p>
<blockquote>
<p>Use inter chain "link:Output.i6t,parse-linked-matter,resolve-conditional-compilation,assimilate,make-identifiers-unique,reconcile-verbs,generate-inter:haha.txt,generate-i6:*".</p>
</blockquote>
<p class="inwebparagraph">The asterisk there substitutes for "whatever filename Inform wants to give the
final I6 file".
</p>
<hr class="tocbar">
<ul class="toc"><li><i>(This section begins Preliminaries.)</i></li><li><i>(This section ends Preliminaries.)</i></li></ul><hr class="tocbar">
<ul class="toc"><li><i>(This section begins Preliminaries.)</i></li><li><a href="P-cas.html">Continue with 'Chains and Stages'</a></li></ul><hr class="tocbar">
<!--End of weave-->
</body>
</html>

6
docs/inter/index.html
View file

@ -17,7 +17,11 @@
<ul class="sectionlist">
<li>
<p><a href="P-ui.html"><spon class="sectiontitle">Using Inter</span></a> -
<span class="purpose">A brief user guide.</span></p>
<span class="purpose">Using Inter at the command line.</span></p>
</li>
<li>
<p><a href="P-cas.html"><spon class="sectiontitle">Chains and Stages</span></a> -
<span class="purpose">Sequences of named code-generation stages are called chains.</span></p>
</li>
</ul>
</li>

1
inter/Contents.w
View file

@ -12,6 +12,7 @@ Import: codegen
Preliminaries
Using Inter
Chains and Stages
Chapter 1: Everything
Basics

183
inter/Preliminaries/Chains and Stages.w Normal file
View file

@ -0,0 +1,183 @@
Chains and Stages.
Sequences of named code-generation stages are called chains.
@h Stages and descriptions.
Inter code has three representations: as a binary file, as a textual file,
and in memory -- a sort of cross-referenced form of binary. For speed, the
Inform compiler generates memory inter directly, and code-generates from
that, so that the inter is normally never written out to disc. When Inter
performs a conversion, it loads (say) textual inter into memory inter, then
writes that out as binary inter.
A processing stage is a step in code generation which acts on memory inter.
Some stages change, add to or edit down that code, while others leave it
untouched but output a file based on it.
Each stage can see an entire "repository" of inter code at a time, and is
not restricted to working through in sequence. Those which read in or write
out a file also have a filename supplied to them as a parameter, but there
are otherwise no configuration options. It's not possible to tell a stage
to work on one specific function alone, for example.
Stages are named, which are written without spaces, and conventionally use
hyphens: for example, |resolve-conditional-compilation|. Where a filename has
to be supplied, it appears after a colon. Thus |generate-inter:my.intert|
is a valid stage description.
A "chain" is a comma-separated list of stage descriptions, and represents a
sort of program to follow: memory inter is passed through each stage in turn.
The special stage |stop| halts processing of the chain midway. At present
this is only useful for making experimental edits to chain descriptions
to see what just the first half does, without deleting the second half of
the description.
@ There are three ways to use chains. One is from the command line of Inter:
|$ inter/Tangled/inter FILE -inter 'CHAIN'|
The other is to use two experimental features of Inform. This sentence:
>> Use inter chain "STAGES".
replaces the chain normally used for code generation with the one supplied.
(This may very well cause the compiler not to produce viable code, of course.)
Equivalently, a replacement chain can be specified at the Inform 7 command line:
|$ inform7/Tangled/inform7 ... -inter 'CHAIN'|
When using a chain within Inform, one further description syntax is allowed:
the filename |*| means "the filename Inform wants to use for the final
Inform 6 file". This tends to be used for the final stage in the chain, which
is normally |generate-i6:*|.
@h The code-generation stages.
The following are all experimental, and have probably not yet reached their
final form or names. But this briefly describes the stages which currently
exist in the code generator. In the description below, the "repository" is
the reservoir of memory inter code being worked on.
Although one thinks of code generation as a process of turning inter into
Inform 6, in fact it goes both ways, because we also have to read in
the "template" of standing Inform 6 code. The early code generation stages
convert the template from Inform 6 into inter, merging it with the inter
already produced by the front end of the compiler. The later stages then
turn this merged repository into Inform 6 code. (Routines in the template,
therefore, are converted out of Inform 6 and then back into it again. This
sounds inefficient but is surprisingly fast, and enables many optimisations.)
@ |link:T| reads in the I6T template file T, 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 verbatim snippets
of Inform 6 code.
@ |parse-linked-matter| examines the splats produced by linking and annotates
them by what they seem to want to do. For example,
|splat &"Global nitwit = 2;\n"|
is recognised as an Inform 6 variable declaration, and annotated thus:
|splat GLOBAL &"Global nitwit = 2;\n"|
@ |resolve-conditional-compilation| looks for splats arising from Inform 6
conditional compilation directives such as |#ifdef|, |#ifndef|, |#endif|;
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.
For example:
|constant MAGIC K_number = 16339|
|splat IFTRUE &"#iftrue MAGIC == 16339;\n"|
|constant WIZARD K_number = 5|
|splat IFNOT &"#ifnot;\n"|
|constant MUGGLE K_number = 0|
|splat ENDIF &"#endif;\n"|
is resolved to:
|constant MAGIC K_number = 16339|
|constant WIZARD K_number = 5|
@ |assimilate| aims to convert all remaining splats in the repository into
higher-level inter statements. For example,
|splat STUB &"#Stub Peach 0;\n"|
|splat ATTRIBUTE &"Attribute marmorial;\n"|
becomes:
|constant Peach K_unchecked_function = Peach_B __assimilated=1|
|property marmorial K_truth_state __assimilated=1 __attribute=1 __either_or=1|
At the end of this stage, there should be no splats left in the repository,
and the linking process is complete.
@ |make-identifiers-unique| looks for symbols marked with the |MAKE_NAME_UNIQUE|
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 |fruit*|, it's really telling
the code generator that it eventually wants this to have a name which won't
collide with anything else.
What |make-identifiers-unique| does is to append |_U1|, |_U2|, ... to such
names across the repository. Thus |fruit*| might become |fruit_U176|, and it
is guaranteed that no other symbol has the same name.
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.
At the end of this stage, no symbol still has the |MAKE_NAME_UNIQUE| flag.
@ |reconcile-verbs| is a short stage looking for clashes between any verbs (in
the parser interactive fiction sense) which have been assimilated from the
template, and verbs which have been defined in the main source text. For
example, suppose the source creates the command verb "abstract": this would
collide with the command meta-verb "abstract", intended for debugging, which
appears in the template. What this stage does is to detect such problems,
and if it finds one, to prefix the template verb with |!|. Thus we would end
up with two command verbs: |abstract|, with its source text meaning, and
|!abstract|, with its template meaning.
At the end of this stage, all parser verbs have distinct textual forms.
@ |generate-inter:F| writes out the repository as a textual inter file |F|.
(By default, Inform doesn't do this: the inter ordinarily stays in memory
throughout.)
This stage leaves the repository unchanged.
@ |generate-inter-binary:F| writes out the repository as a binary inter
file |F|. (By default, Inform doesn't do this: the inter ordinarily stays in
memory throughout.)
This stage leaves the repository unchanged.
@ |generate-i6:F| translates the repository to an Inform 6 program. This is
normally the final stage in the Inform code generation chain.
This stage leaves the repository unchanged.
@h Diagnostic or non-working stages.
@ |show-dependencies:F| and |log-dependencies| output a dependency graph of
the symbols in the current repository, one to a file, the other to the
debugging log. A dependency means that one can't be compiled without the
other: for example, if a function has a local variable of a given kind, then
the function depends on that kind.
|eliminate-redundant-code| is a stage which removes all material from
the repository which the main routine is not dependent on. This can result
in many template routines being kicked out, and substantially reduces
story file sizes. The stage mostly works, but needs more refinement before
we could safely enable it by default with Inform.
@ |summarise:F| is a very slow diagnostic stage showing the breakdown of the
current repository into packages, writing the output to file |F|. (Slow in
this sense means that it roughly triples compilation time.)
@ |export:F| and |import:F| were part of an experiment to do with caching the
inter generated by the Standard Rules. This eventually worked, but was put on
ice while a better and more systematic solution was found.

26
inter/Preliminaries/Using Inter.w
View file

@ -1,8 +1,9 @@
Using Inter.
A brief user guide.
Using Inter at the command line.
@ The command-line executable Inter packages up the back end of the Inform 7
@h What Inter does.
The command-line executable Inter packages up the back end of the Inform 7
compiler into a stand-alone tool, and enables that back end to be used more
flexibly. For example, it can read or write either textual or binary inter
code, and can convert between them. It can also perform any of the numerous
@ -15,7 +16,8 @@ it, and write it out as text again. This gives us a very helpful window into
what Inform is doing; it also provides a test-bed for future optimisation,
or for future applications of inter code.
@ If you have compiled the standard distribution of the command-line tools
@h Command-line usage.
If you have compiled the standard distribution of the command-line tools
for Inform then the Inter executable will be at |inter/Tangled/inter|.
The usage is:
@ -45,16 +47,16 @@ converts |my.intert| (a textual inter file) to its binary equivalent
|$ inter/Tangled/inter my.interb -textual my.intert|
@ In the third and most flexible mode, Inter runs the supplied code through
a chain of processing stages. The chain, which must contain at least
a "chain" of processing stages. The chain, which must contain at least
one stage, is a textual list of comma-separated stage names. For example,
|resolve-conditional-compilation,assimilate,make-identifiers-unique|
is a valid three-stage chain. The command to do this is then:
|$ inter/Tangled/inter my.intert -binary -inter 'STAGES'|
|$ inter/Tangled/inter my.intert -inter 'CHAIN'|
where |STAGES| is the chain description.
where |CHAIN| is the chain description.
In practice, this will only be useful if you can access the result, so it's
normal for the final stage to output something: perhaps Inform 6 code, perhaps
@ -66,15 +68,3 @@ Two more options may be helpful to supplement this: |-domain D| sets the
directory |D| to be the default location for reading and writing inter files;
and |-template T| tells Inter that it can find the I6T template files at
the file system location |T|. (Some code-generation stages import these.)
@ Inform itself currently has an undocumented feature to enable similar
experimentation. The "use" sentence:
>> Use inter chain "STAGES".
works in exactly the same way, so for example:
>> Use inter chain "link:Output.i6t,parse-linked-matter,resolve-conditional-compilation,assimilate,make-identifiers-unique,reconcile-verbs,generate-inter:haha.txt,generate-i6:*".
The asterisk there substitutes for "whatever filename Inform wants to give the
final I6 file".