1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-06-26 04:00:43 +03:00

Revised diagrams

This commit is contained in:
Graham Nelson 2021-08-10 11:46:51 +01:00
parent c2b1504318
commit 66ed1d0d30
3 changed files with 96 additions and 89 deletions

View file

@ -24,37 +24,56 @@ or other standard C compilers.
\|/ \|/
syntax tree
|
kit sources |
(in Inform 6 code) | INFORM7 Stages 2-4
INTER | |
\|/ \|/
kits as Inter binaries inter tree
\ / INFORM7 Stages 5-6 or INTER
\|/ \|/
single linked inter tree
kit sources |
(in Inform 6 code) | INFORM7 Stages 2 to 4
INTER | |
\|/ \|/
precompiled Inter trees Inter tree
\ /
\ / INFORM7 Stage 5 or INTER
\|/ \|/
single linked Inter tree
/ | \
/ | \ INFORM7 Stages 5-6 or INTER
I / | \ INFORM7 Stage 6 or INTER
\|/ \|/ \|/
Inform 6 code C code Index mini-website
Inform 6 code C code index mini-website
| |
INFORM6 | | CLANG/GCC
INFORM6 | | CLANG/GCC
\|/ \|/
story file executable
|
INBLORB |
INBLORB |
\|/
playable website
=
Inform offers three compiler tools: //inbuild//, //inform7// and //inter//,
though really they are three points of access to the same code base. //inbuild//
contains Stage 1 as a stand-alone tool, //inter// contains Stages 5 and 6 as
a stand-alone tool, but //inform7// is the entire compiler (Stages 1 to 6) in one.
See //inbuild: Manual//, //inform7: Manual//, //inter: Manual// and
@ The Inform 7 transpiler, then, occupies the top two-thirds of the above diagram.
Broadly speaking, it runs in six stages, and the code for each stage is made
up of one or more "modules", as follows:
(*) Stage 1. A build manager called //supervisor// gathers what must be compiled.
(*) Stage 2. //core// organises compilation of a single Inform project,
doing little except to co-ordinate the other modules.
(*) Stage 3. //assertions//, //values// and //knowledge// assemble a world model,
turning sentences first into logical propositions and then into inferred facts,
and also gather a set of rules and phrases to operate it. //if// and //multimedia//
provide "plugins" to this process with additional features, adapting the language
for interactive fiction.
(*) Stage 4. //imperative// and //runtime// turn the constructs from Stage 3
into an intermediate bytecode format called Inter.
(*) Stage 5. //bytecode//, //building// and //pipeline// manage, create, link
and optimise this Inter code.
(*) Stage 6. //final// generates final code and //index// generates human-readable
Index pages, which forn a small website about the project.
Inform 7 presents as three command-line tools, not one: //inbuild//, //inform7//
and //inter//. Really, though, they are three points of access to the same code
base. //inbuild// contains Stage 1 as a stand-alone tool, //inter// contains Stages
5 and 6 as a stand-alone tool, and //inform7// is the entire compiler (Stages 1 to 6)
in one. Each tool has its own CLI (or "command-line interface"): see
//inbuild: Manual//, //inform7: Manual//, //inter: Manual// and
//inbuild: Reference Card//, //inform7: Reference Card//, //inter: Reference Card//.
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.
The full breakdown of these three tools into modules is as follows:
= (hyperlinked text as BoxArt)
INBUILD INFORM7 INTER
+-------------+ +-------------+ +-------------+
@ -79,8 +98,8 @@ divided up into "modules", many shared between two or even all three tools.
. . . . | //bytecode//-module | }
. . . . | //building//-module | } Stage 5
. . . . | //pipeline//-module | }
. . . . | //final//-module | }
. . . . | ------------------------- |
. . . . | //final//-module | }
. . . . | //index//-module | } Stage 6
. . . . +---------------------------+
. . . . . .
@ -103,30 +122,14 @@ divided up into "modules", many shared between two or even all three tools.
| (standard C library) |
+-----------------------------------------------------------------------+
=
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:
(*) Stage 1. The build manager //supervisor// decides what must be compiled.
(*) Stage 2. //core// organises compilation of a single Inform project,
doing little except to co-ordinate the other modules.
(*) Stage 3. //assertions//, //values// and //knowledge// assemble a world model
and a set of rules and phrases to operate it. //if// and //multimedia// provide
"plugins" with additional features, adapting the language for interactive fiction.
(*) Stage 4. //imperative// and //runtime// turn the constructs from Stage 3
into an intermediate bytecode format called Inter.
(*) Stage 5. //bytecode//, //building//, //pipeline// and //final// manage,
create, link/optimise and translate this Inter code, respectively.
(*) Stage 6. //index// generates the human-readable Index pages, which are like
a small website about the project, from Inter code.
@ All three tools each use a "services" library, made up of a variety of modules
Note that all three tools 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 //foundation// underneath, a library of utility functions
provided by //inweb//.
@ That's a lot: for code-spelunkers, this is a veritable limestone hillside.
Where to begin? Here are some suggested entrances:
@ That's a lot: for code-spelunkers, this is quite the limestone hillside of
potential points of entry. Where to begin? Here are some suggested entrances:
(a) See //supervisor: What This Module Does// for an overview of the
build-management process.
(b) Or take that on trust, and see //core: What This Module Does// for

View file

@ -89,37 +89,58 @@ or other standard C compilers.
<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="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"> </span><span class="element-syntax">to</span><span class="plain-syntax"> </span><span class="constant-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">precompiled</span><span class="plain-syntax"> </span><span class="element-syntax">Inter</span><span class="plain-syntax"> </span><span class="element-syntax">trees</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">Stage</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax"> </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="element-syntax">I</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">6</span><span class="plain-syntax"> </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="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="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="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
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>The Inform 7 transpiler, then, occupies the top two-thirds of the above diagram.
Broadly speaking, it runs in six stages, and the code for each stage is made
up of one or more "modules", as follows:
</p>
<ul class="items"><li>&#9679; Stage 1. A build manager called <a href="supervisor-module/index.html" class="internal">supervisor</a> gathers 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,
turning sentences first into logical propositions and then into inferred facts,
and also gather 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" to this process 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> and <a href="pipeline-module/index.html" class="internal">pipeline</a> manage, create, link
and optimise this Inter code.
</li><li>&#9679; Stage 6. <a href="final-module/index.html" class="internal">final</a> generates final code and <a href="index-module/index.html" class="internal">index</a> generates human-readable
Index pages, which forn a small website about the project.
</li></ul>
<p class="commentary">Inform 7 presents as three command-line tools, not one: <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>. Really, though, 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, and <a href="inform7/index.html" class="internal">inform7</a> is the entire compiler (Stages 1 to 6)
in one. Each tool has its own CLI (or "command-line interface"): 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 class="commentary">The full breakdown of these three tools into modules is as follows:
</p>
<pre class="displayed-code all-displayed-code code-font">
@ -146,8 +167,8 @@ divided up into "modules", many shared between two or even all three tools.
<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="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><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>
@ -170,33 +191,15 @@ divided up into "modules", many shared between two or even all three tools.
<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
<p class="commentary">Note that all three tools 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 class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>That's a lot: for code-spelunkers, this is quite the limestone hillside of
potential points of entry. 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

View file

@ -1,10 +1,10 @@
100.0% in inform7 run
55.2% in compilation to Inter
40.2% in //Sequence::undertake_queued_tasks//
3.5% in //MajorNodes::pre_pass//
55.5% in compilation to Inter
40.4% in //Sequence::undertake_queued_tasks//
3.4% in //MajorNodes::pre_pass//
2.6% in //MajorNodes::pass_1//
1.5% in //RTPhrasebook::compile_entries//
1.4% in //ImperativeDefinitions::assess_all//
1.3% in //ImperativeDefinitions::assess_all//
1.1% in //RTKindConstructors::compile//
0.4% in //ImperativeDefinitions::compile_first_block//
0.4% in //MajorNodes::pass_2//
@ -16,12 +16,12 @@
0.1% in //RTKindConstructors::compile_permissions//
0.1% in //Task::make_built_in_kind_constructors//
0.1% in //World::stages_II_and_III//
1.8% not specifically accounted for
42.7% in running Inter pipeline
10.9% in step preparation
9.8% in inter step 7/14: consolidate-text
2.0% not specifically accounted for
42.5% in running Inter pipeline
10.7% in step preparation
9.6% in inter step 7/14: consolidate-text
8.2% in inter step 14/14: generate inform6 -> auto.inf
8.0% in inter step 2/14: link
8.1% in inter step 2/14: link
1.5% in inter step 10/14: make-identifiers-unique
0.4% in inter step 11/14: reconcile-verbs
0.2% in inter step 13/14: eliminate-redundant-operations
@ -29,6 +29,7 @@
0.2% in inter step 8/14: resolve-external-symbols
0.2% in inter step 9/14: inspect-plugs
0.1% in inter step 12/14: eliminate-redundant-labels
0.1% in inter step 3/14: merge-template <- none
0.1% in inter step 4/14: parse-linked-matter
0.1% in inter step 5/14: resolve-conditional-compilation
2.1% not specifically accounted for