1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-01 06:24:58 +03:00
inform7/docs/compiler.html

215 lines
27 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>The Inform 7 compiler</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">
</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><span class="unlink">compiler tools</span></li>
<li><a href="other.html">other tools</a></li>
<li><a href="extensions.html">extensions and kits</a></li>
<li><a href="units.html">unit test tools</a></li>
</ul><h2>Compiler Webs</h2><ul>
<li><a href="inbuild/index.html">inbuild</a></li>
<li><a href="inform7/index.html">inform7</a></li>
<li><a href="inter/index.html">inter</a></li>
</ul><h2>Inbuild Modules</h2><ul>
<li><a href="supervisor-module/index.html">supervisor</a></li>
</ul><h2>Inform7 Modules</h2><ul>
<li><a href="core-module/index.html">core</a></li>
<li><a href="assertions-module/index.html">assertions</a></li>
<li><a href="values-module/index.html">values</a></li>
<li><a href="knowledge-module/index.html">knowledge</a></li>
<li><a href="imperative-module/index.html">imperative</a></li>
<li><a href="runtime-module/index.html">runtime</a></li>
<li><a href="if-module/index.html">if</a></li>
<li><a href="multimedia-module/index.html">multimedia</a></li>
<li><a href="index-module/index.html">index</a></li>
</ul><h2>Inter Modules</h2><ul>
<li><a href="bytecode-module/index.html">bytecode</a></li>
<li><a href="building-module/index.html">building</a></li>
<li><a href="pipeline-module/index.html">pipeline</a></li>
<li><a href="final-module/index.html">final</a></li>
</ul><h2>Services</h2><ul>
<li><a href="arch-module/index.html">arch</a></li>
<li><a href="calculus-module/index.html">calculus</a></li>
<li><a href="html-module/index.html">html</a></li>
<li><a href="inflections-module/index.html">inflections</a></li>
<li><a href="kinds-module/index.html">kinds</a></li>
<li><a href="linguistics-module/index.html">linguistics</a></li>
<li><a href="problems-module/index.html">problems</a></li>
<li><a href="syntax-module/index.html">syntax</a></li>
<li><a href="words-module/index.html">words</a></li>
<li><a href="../../inweb/docs/foundation-module/index.html">foundation</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'The Inform 7 compiler' generated by Inweb-->
<div class="breadcrumbs">
<ul class="crumbs"><li><a href="index.html">Home</a></li><li><b>The Inform 7 compiler</b></li></ul></div>
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. </b>The task of Inform to take natural-language source text, merged from the
author's main source and some "extensions"; to compile that to an intermediate
format called Inter; merge once again with pre-compiled libraries of Inter
called "kits"; and then translate the result to a program which a
more orthodox compiler can take the rest of the way. Because Inform 7 generates
code for another compiler, rather than directly making an executable itself,
it is properly speaking a "transpiler".
</p>
<p class="commentary">For two decades that second compiler was always the roughly C-like Inform 6, a
sturdy 1990s tool for generating interactive fiction "story files" which, after
processing with the <a href="inblorb/index.html" class="internal">inblorb</a> tool, can then be played in a web browser or
with an "interpreter". In 2021, limited support was added for transpiling a
general, non-IF-specific form of the language called Basic Inform to ANSI C.
This can be compiled into more general executable programs using Clang, gcc,
or other standard C compilers.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="element-syntax">main</span><span class="plain-syntax"> </span><span class="element-syntax">source</span><span class="plain-syntax"> </span><span class="element-syntax">text</span><span class="plain-syntax"> </span><span class="element-syntax">extension</span><span class="plain-syntax"> </span><span class="element-syntax">source</span><span class="plain-syntax"> </span><span class="element-syntax">texts</span>
<span class="plain-syntax"> \ /</span>
<span class="plain-syntax"> \ / </span><span class="function-syntax">INFORM7</span><span class="plain-syntax"> </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> </span><span class="element-syntax">or</span><span class="plain-syntax"> </span><span class="function-syntax">INBUILD</span>
<span class="plain-syntax"> \ /</span>
<span class="plain-syntax"> \|/ \|/</span>
<span class="plain-syntax"> </span><span class="element-syntax">syntax</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span>
<span class="plain-syntax"> |</span>
<span class="plain-syntax"> </span><span class="element-syntax">kit</span><span class="plain-syntax"> </span><span class="element-syntax">sources</span><span class="plain-syntax"> |</span>
<span class="plain-syntax"> (</span><span class="element-syntax">in</span><span class="plain-syntax"> </span><span class="element-syntax">Inform</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="element-syntax">code</span><span class="plain-syntax">) | </span><span class="function-syntax">INFORM7</span><span class="plain-syntax"> </span><span class="element-syntax">Stages</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax">-4</span>
<span class="plain-syntax"> </span><span class="function-syntax">INTER</span><span class="plain-syntax"> | |</span>
<span class="plain-syntax"> \|/ \|/</span>
<span class="plain-syntax"> </span><span class="element-syntax">kits</span><span class="plain-syntax"> </span><span class="element-syntax">as</span><span class="plain-syntax"> </span><span class="element-syntax">Inter</span><span class="plain-syntax"> </span><span class="element-syntax">binaries</span><span class="plain-syntax"> </span><span class="element-syntax">inter</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span>
<span class="plain-syntax"> \ / </span><span class="function-syntax">INFORM7</span><span class="plain-syntax"> </span><span class="element-syntax">Stages</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax">-6 </span><span class="element-syntax">or</span><span class="plain-syntax"> </span><span class="function-syntax">INTER</span>
<span class="plain-syntax"> \|/ \|/</span>
<span class="plain-syntax"> </span><span class="element-syntax">single</span><span class="plain-syntax"> </span><span class="element-syntax">linked</span><span class="plain-syntax"> </span><span class="element-syntax">inter</span><span class="plain-syntax"> </span><span class="element-syntax">tree</span>
<span class="plain-syntax"> / | \</span>
<span class="plain-syntax"> / | \ </span><span class="function-syntax">INFORM7</span><span class="plain-syntax"> </span><span class="element-syntax">Stages</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax">-6 </span><span class="element-syntax">or</span><span class="plain-syntax"> </span><span class="function-syntax">INTER</span>
<span class="plain-syntax"> \|/ \|/ \|/</span>
<span class="plain-syntax"> </span><span class="element-syntax">Inform</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span><span class="plain-syntax"> </span><span class="element-syntax">code</span><span class="plain-syntax"> </span><span class="element-syntax">C</span><span class="plain-syntax"> </span><span class="element-syntax">code</span><span class="plain-syntax"> </span><span class="element-syntax">Index</span><span class="plain-syntax"> </span><span class="element-syntax">mini</span><span class="plain-syntax">-</span><span class="element-syntax">website</span>
<span class="plain-syntax"> | |</span>
<span class="plain-syntax"> </span><span class="function-syntax">INFORM6</span><span class="plain-syntax"> | | </span><span class="function-syntax">CLANG</span><span class="plain-syntax">/</span><span class="function-syntax">GCC</span>
<span class="plain-syntax"> \|/ \|/</span>
<span class="plain-syntax"> </span><span class="element-syntax">story</span><span class="plain-syntax"> </span><span class="element-syntax">file</span><span class="plain-syntax"> </span><span class="element-syntax">executable</span>
<span class="plain-syntax"> |</span>
<span class="plain-syntax"> </span><span class="function-syntax">INBLORB</span><span class="plain-syntax"> |</span>
<span class="plain-syntax"> \|/</span>
<span class="plain-syntax"> </span><span class="element-syntax">playable</span><span class="plain-syntax"> </span><span class="element-syntax">website</span>
</pre>
<p class="commentary">Inform offers three compiler tools: <a href="inbuild/index.html" class="internal">inbuild</a>, <a href="inform7/index.html" class="internal">inform7</a> and <a href="inter/index.html" class="internal">inter</a>,
though really they are three points of access to the same code base. <a href="inbuild/index.html" class="internal">inbuild</a>
contains Stage 1 as a stand-alone tool, <a href="inter/index.html" class="internal">inter</a> contains Stages 5 and 6 as
a stand-alone tool, but <a href="inform7/index.html" class="internal">inform7</a> is the entire compiler (Stages 1 to 6) in one.
See <a href="inbuild/M-ui.html" class="internal">Manual (in inbuild)</a>, <a href="inform7/M-cu.html" class="internal">Manual (in inform7)</a>, <a href="inter/M-ui.html" class="internal">Manual (in inter)</a> and
<a href="inbuild/M-rc.html" class="internal">Reference Card (in inbuild)</a>, <a href="inform7/M-rc.html" class="internal">Reference Card (in inform7)</a>, <a href="inter/M-rc.html" class="internal">Reference Card (in inter)</a>.
</p>
<p class="commentary">Each tool has its own CLI (or "command-line interface") but is otherwise
divided up into "modules", many shared between two or even all three tools.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="function-syntax">INBUILD</span><span class="plain-syntax"> </span><span class="function-syntax">INFORM7</span><span class="plain-syntax"> </span><span class="function-syntax">INTER</span>
<span class="plain-syntax"> +-------------+ +-------------+ +-------------+</span>
<span class="plain-syntax"> | </span><a href="inbuild/index.html" class="internal">inbuild</a><span class="plain-syntax"> | | </span><a href="inform7/index.html" class="internal">inform7</a><span class="plain-syntax"> | | </span><a href="inter/index.html" class="internal">inter</a><span class="plain-syntax"> |</span>
<span class="plain-syntax"> | (</span><span class="element-syntax">cli</span><span class="plain-syntax">) | | (</span><span class="element-syntax">cli</span><span class="plain-syntax">) | | (</span><span class="element-syntax">cli</span><span class="plain-syntax">) |</span>
<span class="plain-syntax"> +-------------+ +-------------+ +-------------+</span>
<span class="plain-syntax"> . . . . . .</span>
<span class="plain-syntax">+---------------------------+ . . . .</span>
<span class="plain-syntax">| </span><a href="supervisor-module/index.html" class="internal">supervisor</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . . . } </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
<span class="plain-syntax">+------------------------+ +------------------+ . .</span>
<span class="plain-syntax"> . . | </span><a href="core-module/index.html" class="internal">core</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . } </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span>
<span class="plain-syntax"> . . | ------------------- | . .</span>
<span class="plain-syntax"> . . | </span><a href="assertions-module/index.html" class="internal">assertions</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . }</span>
<span class="plain-syntax"> . . | </span><a href="values-module/index.html" class="internal">values</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . } </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span>
<span class="plain-syntax"> . . | </span><a href="knowledge-module/index.html" class="internal">knowledge</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . }</span>
<span class="plain-syntax"> . . | </span><a href="if-module/index.html" class="internal">if</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax">* | . . } * </span><span class="element-syntax">not</span><span class="plain-syntax"> </span><span class="element-syntax">used</span><span class="plain-syntax"> </span><span class="element-syntax">in</span>
<span class="plain-syntax"> . . | </span><a href="multimedia-module/index.html" class="internal">multimedia</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax">* | . . } </span><span class="element-syntax">Basic</span><span class="plain-syntax"> </span><span class="element-syntax">Inform</span>
<span class="plain-syntax"> . . | ------------------- | . .</span>
<span class="plain-syntax"> . . | </span><a href="imperative-module/index.html" class="internal">imperative</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . } </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span>
<span class="plain-syntax"> . . | </span><a href="runtime-module/index.html" class="internal">runtime</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | . . }</span>
<span class="plain-syntax"> . . +------------------+ +------------------------+</span>
<span class="plain-syntax"> . . . . | </span><a href="bytecode-module/index.html" class="internal">bytecode</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | }</span>
<span class="plain-syntax"> . . . . | </span><a href="building-module/index.html" class="internal">building</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | } </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span>
<span class="plain-syntax"> . . . . | </span><a href="pipeline-module/index.html" class="internal">pipeline</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | }</span>
<span class="plain-syntax"> . . . . | </span><a href="final-module/index.html" class="internal">final</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | }</span>
<span class="plain-syntax"> . . . . | ------------------------- |</span>
<span class="plain-syntax"> . . . . | </span><a href="index-module/index.html" class="internal">index</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> | } </span><span class="element-syntax">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">6</span>
<span class="plain-syntax"> . . . . +---------------------------+</span>
<span class="plain-syntax"> . . . . . .</span>
<span class="plain-syntax">+-----------------------------------------------------------------------+</span>
<span class="plain-syntax">| </span><span class="function-syntax">SERVICES</span><span class="plain-syntax"> </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="linguistics-module/index.html" class="internal">linguistics</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="calculus-module/index.html" class="internal">calculus</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="kinds-module/index.html" class="internal">kinds</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="lexicon-module/index.html" class="internal">lexicon</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="inflections-module/index.html" class="internal">inflections</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="problems-module/index.html" class="internal">problems</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="syntax-module/index.html" class="internal">syntax</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="words-module/index.html" class="internal">words</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="arch-module/index.html" class="internal">arch</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">| </span><span class="element-syntax">shared</span><span class="plain-syntax"> </span><a href="html-module/index.html" class="internal">html</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> |</span>
<span class="plain-syntax">+-----------------------------------------------------------------------+</span>
<span class="plain-syntax"> . . . . . .</span>
<span class="plain-syntax">+-----------------------------------------------------------------------+</span>
<span class="plain-syntax">| </span><span class="function-syntax">FOUNDATION</span><span class="plain-syntax"> </span><a href="../../inweb/docs/foundation-module/index.html" class="internal">foundation</a><span class="plain-syntax">-</span><span class="element-syntax">module</span><span class="plain-syntax"> (</span><span class="element-syntax">in</span><span class="plain-syntax"> </span><span class="element-syntax">inweb</span><span class="plain-syntax"> </span><span class="element-syntax">repository</span><span class="plain-syntax">) |</span>
<span class="plain-syntax">| (</span><span class="element-syntax">Posix</span><span class="plain-syntax"> </span><span class="element-syntax">or</span><span class="plain-syntax"> </span><span class="element-syntax">Windows</span><span class="plain-syntax">-</span><span class="element-syntax">related</span><span class="plain-syntax"> </span><span class="element-syntax">functions</span><span class="plain-syntax">) |</span>
<span class="plain-syntax">| (</span><span class="element-syntax">standard</span><span class="plain-syntax"> </span><span class="element-syntax">C</span><span class="plain-syntax"> </span><span class="element-syntax">library</span><span class="plain-syntax">) |</span>
<span class="plain-syntax">+-----------------------------------------------------------------------+</span>
</pre>
<p class="commentary">The Inform compiler runs in six stages. It is not literally true that each
completes before the next begins, but compilation broadly flows diagonally
downwards and rightwards in the diagram:
</p>
<ul class="items"><li>&#9679; Stage 1. The build manager <a href="supervisor-module/index.html" class="internal">supervisor</a> decides what must be compiled.
</li><li>&#9679; Stage 2. <a href="core-module/index.html" class="internal">core</a> organises compilation of a single Inform project,
doing little except to co-ordinate the other modules.
</li><li>&#9679; Stage 3. <a href="assertions-module/index.html" class="internal">assertions</a>, <a href="values-module/index.html" class="internal">values</a> and <a href="knowledge-module/index.html" class="internal">knowledge</a> assemble a world model
and a set of rules and phrases to operate it. <a href="if-module/index.html" class="internal">if</a> and <a href="multimedia-module/index.html" class="internal">multimedia</a> provide
"plugins" with additional features, adapting the language for interactive fiction.
</li><li>&#9679; Stage 4. <a href="imperative-module/index.html" class="internal">imperative</a> and <a href="runtime-module/index.html" class="internal">runtime</a> turn the constructs from Stage 3
into an intermediate bytecode format called Inter.
</li><li>&#9679; Stage 5. <a href="bytecode-module/index.html" class="internal">bytecode</a>, <a href="building-module/index.html" class="internal">building</a>, <a href="pipeline-module/index.html" class="internal">pipeline</a> and <a href="final-module/index.html" class="internal">final</a> manage,
create, link/optimise and translate this Inter code, respectively.
</li><li>&#9679; Stage 6. <a href="index-module/index.html" class="internal">index</a> generates the human-readable Index pages, which are like
a small website about the project, from Inter code.
</li></ul>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>All three tools each use a "services" library, made up of a variety of modules
providing services useful for natural language-based programs. At one time this
was going to be called "Second Foundation" or possibly "Foundation and Empire",
because there is also <a href="../../inweb/docs/foundation-module/index.html" class="internal">foundation</a> underneath, a library of utility functions
provided by <a href="../../inweb/docs/index.html" class="internal">inweb</a>.
</p>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>That's a lot: for code-spelunkers, this is a veritable limestone hillside.
Where to begin? Here are some suggested entrances:
</p>
<ul class="items"><li>(a) See <a href="supervisor-module/P-wtmd.html" class="internal">What This Module Does (in supervisor)</a> for an overview of the
build-management process.
</li><li>(b) Or take that on trust, and see <a href="core-module/P-wtmd.html" class="internal">What This Module Does (in core)</a> for
an overview of how Inform 7 basically works.
</li><li>(c) If you're more interested in the low-level representation of Inter code,
and how to generate from it, see <a href="bytecode-module/P-wtmd.html" class="internal">What This Module Does (in bytecode)</a>.
</li></ul>
<!--End of weave-->
</main>
</body>
</html>