mirror of
https://github.com/ganelson/inform.git
synced 2024-07-16 22:14:23 +03:00
594 lines
43 KiB
HTML
594 lines
43 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>A Guide to Kits</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">
|
|
<script src="http://code.jquery.com/jquery-1.12.4.min.js"
|
|
integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
|
|
|
|
<script src="../docs-assets/Bigfoot.js"></script>
|
|
<link href="../docs-assets/Bigfoot.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 'A Guide to Kits' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inbuild</a></li><li><a href="index.html#M">Manual</a></li><li><b>A Guide to Kits</b></li></ul></div>
|
|
<p class="purpose">Provisional documentation on how to make and build new kits.</p>
|
|
|
|
<ul class="toc"><li><a href="M-agtk.html#SP1">§1. Historical note</a></li><li><a href="M-agtk.html#SP2">§2. Exactly how kit dependencies are worked out</a></li><li><a href="M-agtk.html#SP12">§12. Full specification of the kit metadata file</a></li><li><a href="M-agtk.html#SP24">§24. Future directions</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. Historical note. </b>Inform 7 projects have always needed an underpinning of low-level code, in the
|
|
same way that all C programs can use standard library functions like <span class="extract"><span class="extract-syntax">printf</span></span>.
|
|
In builds from 2016 and earlier, this standard low-level code was provided as
|
|
a set of "template files" with filenames like <span class="extract"><span class="extract-syntax">Mathematics.i6t</span></span>, all written
|
|
in Inform 6. During compilation, an I7 source text would be compiled down to
|
|
one wodge of I6 code, then standing I6 code from files like <span class="extract"><span class="extract-syntax">Mathematics.i6t</span></span>
|
|
would be spliced in, and the result would, of course, be an I6 program.
|
|
</p>
|
|
|
|
<p class="commentary">With the arrival of Inter and the possibility of compiling to, say, C instead
|
|
of I6 code, this all conceptually changed. Instead of an undifferentiated mass of
|
|
template files, that standing material was grouped together into multiple "kits".
|
|
(The material formerly in "Mathematics.i6t" now lives on inside BasicInformKit.)
|
|
</p>
|
|
|
|
<p class="commentary">Moreover, that material is still written in Inform 6 syntax, or very nearly so.
|
|
What happens to it is completely different — it is compiled first to Inter, and
|
|
then to whatever we like, which may or may not be Inform 6 code — but in
|
|
practice it is not hard to convert template files to become new kits. The
|
|
notes in this section are provisional documentation on how to make and use
|
|
non-standard kits, that is, kits not supplied with the standard Inform apps.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. Exactly how kit dependencies are worked out. </b>Inbuild is in charge of deciding which kits a project will use, just as it also
|
|
decides which extensions. For an English-language work of interactive
|
|
fiction being made with the Inform apps, the kits will always be:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">BasicInformKit + EnglishLanguageKit + WorldModelKit + CommandParserKit</span>
|
|
</pre>
|
|
<p class="commentary">However, if the "Basic Inform" checkbox is ticked on the Settings panel for
|
|
the project, the kits will instead be:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">BasicInformKit + EnglishLanguageKit + BasicInformExtrasKit</span>
|
|
</pre>
|
|
<p class="commentary">And these are also the defaults when Inform projects are compiled from the command
|
|
line, with the optional <span class="extract"><span class="extract-syntax">-basic</span></span> switch forcing us into the second case. As a
|
|
first step, then, let us see why these are the defaults.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>BasicInformKit is absolutely obligatory. No Inform project can ever compile
|
|
without it: it contains essential functions such as <span class="extract"><span class="extract-syntax">BlkValueCreate</span></span> or <span class="extract"><span class="extract-syntax">IntegerDivide</span></span>.
|
|
Inbuild therefore makes every Inform project have BasicInformKit as a dependency.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild also makes each project dependent on the language kit for whatever language
|
|
bundle it is using. The name of the necessary kit can be specified in the language
|
|
bundle's <span class="extract"><span class="extract-syntax">about.txt</span></span> file — see <a href="../supervisor-module/5-ls.html" class="internal">Language Services (in supervisor)</a> — or, if the
|
|
<span class="extract"><span class="extract-syntax">about.txt</span></span> doesn't specify one, it's made by adding <span class="extract"><span class="extract-syntax">LanguageKit</span></span> to the language's
|
|
name. So if the French language bundle is used, then the default configurations
|
|
become:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">BasicInformKit + FrenchLanguageKit + WorldModelKit + CommandParserKit</span>
|
|
<span class="plain-syntax">BasicInformKit + FrenchLanguageKit + BasicInformExtrasKit</span>
|
|
</pre>
|
|
<p class="commentary">Next, Inbuild adds a dependency on any kit which is named at the command line
|
|
using the <span class="extract"><span class="extract-syntax">-kit</span></span> switch. Note that this exists as a command-line switch for
|
|
both <span class="extract"><span class="extract-syntax">inbuild</span></span> and <span class="extract"><span class="extract-syntax">inform7</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Finally, Inbuild adds an automatic dependency on CommandParserKit if neither
|
|
the <span class="extract"><span class="extract-syntax">-kit</span></span> nor <span class="extract"><span class="extract-syntax">-basic</span></span> switches have been used. The practical effect of that
|
|
rule is that Inform by default assumes it is making an interactive fiction
|
|
of some kind, unless explicitly told not to — by using <span class="extract"><span class="extract-syntax">-basic</span></span> or <span class="extract"><span class="extract-syntax">-kit</span></span>,
|
|
or by checking the "Basic Inform" checkbox in the apps.<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup>
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:1"><p class="inwebfootnote"><sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> Checking this box equates to <span class="extract"><span class="extract-syntax">-basic</span></span>, which in turn is equivalent
|
|
to specifying <span class="extract"><span class="extract-syntax">-kit BasicInformKit</span></span>.
|
|
<a href="#fnref:1" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>Kits have the ability to specify that other kits are automatically added to
|
|
the project in an ITTT, "if-this-then-that", way. As we shall see, every kit
|
|
contains a file called <span class="extract"><span class="extract-syntax">kit_metadata.txt</span></span> describing its needs. The metadata
|
|
for CommandParserKit includes:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">dependency: if CommandParserKit then WorldModelKit</span>
|
|
</pre>
|
|
<p class="commentary">This means that any project depending on CommandParserKit automatically depends
|
|
on WorldModelKit too. BasicInformKit uses this facility as well, but in a
|
|
negative way. Its own metadata file says:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">dependency: if not WorldModelKit then BasicInformExtrasKit</span>
|
|
</pre>
|
|
<p class="commentary">It follows that if WorldModelKit is not present, then BasicInformExtrasKit is
|
|
automatically added instead.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>Kits can also use their metadata to specify that associated extensions should
|
|
automatically be loaded into the project.<sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup> For example, the <span class="extract"><span class="extract-syntax">kit_metadata.txt</span></span>
|
|
for BasicInformKit includes the lines:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">extension: Basic Inform by Graham Nelson</span>
|
|
<span class="plain-syntax">extension: English Language by Graham Nelson</span>
|
|
</pre>
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:2"><p class="inwebfootnote"><sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup> This in fact is the mechanism by which Inform decides which extensions
|
|
should be implicitly included in a project. Other extensions are included only
|
|
because of explicit "Include..." sentences in the source text.
|
|
<a href="#fnref:2" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>As an example, suppose we have a minimal Inform story called "French Laundry",
|
|
whose source text reads just "The French Laundry is a room." Running Inbuild
|
|
with the <span class="extract"><span class="extract-syntax">-build-needs</span></span> option shows what is needed to build this project:
|
|
</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">inbuild/Tangled/inbuild</span><span class="ConsoleText-identifier-syntax"> -project</span><span class="ConsoleText-plain-syntax"> 'French Laundry.inform'</span><span class="ConsoleText-identifier-syntax"> -build-needs</span>
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: French Laundry.inform</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BasicInformKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Inform by Graham Nelson v1</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: English Language by Graham Nelson v1</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: CommandParserKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Standard Rules by Graham Nelson v6</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: WorldModelKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Standard Rules by Graham Nelson v6</span>
|
|
<span class="ConsoleText-plain-syntax"> language: English</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: EnglishLanguageKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: English Language by Graham Nelson v1</span>
|
|
</pre>
|
|
<p class="commentary">The effect of some of the rules above can be seen here. EnglishLanguageKit is
|
|
included because of the use of the English language. WorldModelKit is included
|
|
only because CommandParserKit is there. And the kits between them call for
|
|
three extensions to be auto-included: Basic Inform, English Language and the
|
|
Standard Rules.
|
|
</p>
|
|
|
|
<p class="commentary">As this shows, the same kit or extension may be needed for multiple reasons.
|
|
But it is only included once, of course.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b>At the command line, either for Inbuild or Inform7, the <span class="extract"><span class="ConsoleText-extract-syntax">-kit</span></span> switch
|
|
can specify alternative kit(s) to use. Note that if any use is made of <span class="extract"><span class="ConsoleText-extract-syntax">-kit</span></span>
|
|
then CommandParserKit and (in consequence) WorldModelKit are no longer auto-included.
|
|
For example, if <span class="extract"><span class="ConsoleText-extract-syntax">-kit BalloonKit</span></span> is specified, then we will end up with:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">BasicInformKit + EnglishLanguageKit + BalloonKit + BasicInformExtrasKit</span>
|
|
</pre>
|
|
<p class="commentary">But if <span class="extract"><span class="extract-syntax">-kit CommandParserKit -kit BalloonKit</span></span> is specified, then:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">BasicInformKit + EnglishLanguageKit + WorldModelKit + CommandParserKit + BalloonKit</span>
|
|
</pre>
|
|
<p class="commentary">It may seem that if Inform is being used inside the apps, then there is no way to
|
|
specify non-standard kits. Since the user isn't using the command line, how can
|
|
the user specify a <span class="extract"><span class="extract-syntax">-kit</span></span>? However, a feature of Inform new in 2022 gets around
|
|
this. Additional command-line switches for <span class="extract"><span class="extract-syntax">inbuild</span></span> or for <span class="extract"><span class="extract-syntax">inform7</span></span> can be
|
|
placed in the Materials directory for an Inform project, in files called
|
|
<span class="extract"><span class="extract-syntax">inbuild-setting.txt</span></span> and <span class="extract"><span class="extract-syntax">inform7-settings.txt</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">For example, suppose we set both<sup id="fnref:3"><a href="#fn:3" rel="footnote">3</a></sup> of these files to be:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">-kit CommandParserKit</span>
|
|
<span class="plain-syntax">-kit BalloonKit</span>
|
|
</pre>
|
|
<p class="commentary">And put the following into place:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">Exotic.inform</span>
|
|
<span class="plain-syntax">Exotic.materials</span>
|
|
<span class="plain-syntax"> inbuild-settings.txt</span>
|
|
<span class="plain-syntax"> inform7-settings.txt</span>
|
|
<span class="plain-syntax"> Inter</span>
|
|
<span class="plain-syntax"> BalloonKit</span>
|
|
<span class="plain-syntax"> ...</span>
|
|
<span class="plain-syntax"> ...</span>
|
|
</pre>
|
|
<p class="commentary">BalloonKit has to be a properly set up kit — see below; but if so, then when
|
|
we next look at the build requirements for the project, we see:
|
|
</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">inbuild/Tangled/inbuild</span><span class="ConsoleText-identifier-syntax"> -project</span><span class="ConsoleText-plain-syntax"> 'French Laundry.inform'</span><span class="ConsoleText-identifier-syntax"> -build-needs</span>
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: French Laundry.inform</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BasicInformKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Inform by Graham Nelson v1</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: English Language by Graham Nelson v1</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: CommandParserKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Standard Rules by Graham Nelson v6</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: WorldModelKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Standard Rules by Graham Nelson v6</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BalloonKit</span>
|
|
<span class="ConsoleText-plain-syntax"> language: English</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: EnglishLanguageKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: English Language by Graham Nelson v1</span>
|
|
</pre>
|
|
<p class="commentary">So now BalloonKit is indeed a dependency.
|
|
</p>
|
|
|
|
<p class="commentary">See <a href="M-ui.html" class="internal">Manual (in inbuild)</a> for the full story on where the compiler expects to
|
|
find kits, but basically, they're managed much the way extensions are.
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:3"><p class="inwebfootnote"><sup id="fnref:3"><a href="#fn:3" rel="footnote">3</a></sup> Both, so that whether the executable looking at the project is inbuild or
|
|
inform7, it will use the same set of kits. You want this.
|
|
<a href="#fnref:3" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>So, then, what actually is a kit? It is stored as a directory whose name is
|
|
the name of the kit: in the case of our example, that will be <span class="extract"><span class="ConsoleText-extract-syntax">BalloonKit</span></span>.
|
|
This directory contains:
|
|
</p>
|
|
|
|
<ul class="items"><li>● Source code. In fact, a kit is also an Inweb literate program, though it
|
|
is always a deliberately simple one. (Being Inweb-compatible is very convenient,
|
|
since it means it can be woven into website form. See <a href="../BasicInformKit/index.html" class="internal">BasicInformKit</a> for
|
|
an example of the result.) It is simple because it provides only a <span class="extract"><span class="ConsoleText-extract-syntax">Contents.w</span></span>
|
|
page and a <span class="extract"><span class="ConsoleText-extract-syntax">Sections</span></span> subdirectory — it has no manual, chapters, figures,
|
|
sounds or other paraphernalia.
|
|
</li><li>● A file called <span class="extract"><span class="ConsoleText-extract-syntax">kit_metadata.txt</span></span> describing the kit, its version and its
|
|
dependencies.
|
|
</li><li>● Compiled binary Inter files — but only once the kit has been built. These
|
|
always have filenames in the shape <span class="extract"><span class="ConsoleText-extract-syntax">arch-A.interb</span></span>, where <span class="extract"><span class="ConsoleText-extract-syntax">A</span></span> is an architecture;
|
|
in that way, a kit can contain binary Inter to suit several different architectures.
|
|
For example, <span class="extract"><span class="ConsoleText-extract-syntax">arch-16d.interb</span></span> or <span class="extract"><span class="ConsoleText-extract-syntax">arch-32.interb</span></span>.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b>The source code is written in Inform 6 syntax.<sup id="fnref:4"><a href="#fn:4" rel="footnote">4</a></sup> This means that to create or
|
|
edit kits, you need to be able to write Inform 6 code, but it's a very simple
|
|
language to learn if all you're doing is writing functions, variables and arrays.
|
|
</p>
|
|
|
|
<p class="commentary">For <span class="extract"><span class="ConsoleText-extract-syntax">BalloonKit</span></span>, the contents page <span class="extract"><span class="ConsoleText-extract-syntax">BalloonKit/Contents.w</span></span> will be:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">Title: BalloonKit</span>
|
|
<span class="plain-syntax">Author: Joseph-Michel Montgolfier</span>
|
|
<span class="plain-syntax">Purpose: Inter-level support for inflating rubber-lined pockets of air.</span>
|
|
|
|
<span class="plain-syntax">Sections</span>
|
|
<span class="plain-syntax"> Inflation</span>
|
|
</pre>
|
|
<p class="commentary">So there will be just one section, <span class="extract"><span class="extract-syntax">BalloonKit/Sections/Inflation.w</span></span>, which
|
|
will read:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Inflation.</span>
|
|
|
|
<span class="plain-syntax"> Vital Inter-level support for those balloons.</span>
|
|
|
|
<span class="plain-syntax"> @h Inflation function.</span>
|
|
|
|
<span class="plain-syntax"> =</span>
|
|
<span class="plain-syntax"> Constant MAX_SAFE_INFLATION_PUFFS 5;</span>
|
|
|
|
<span class="plain-syntax"> [ InflateBalloon N i;</span>
|
|
<span class="plain-syntax"> if (N > MAX_SAFE_INFLATION_PUFFS) N = MAX_SAFE_INFLATION_PUFFS;</span>
|
|
<span class="plain-syntax"> for (i=0: i<N: i++) {</span>
|
|
<span class="plain-syntax"> print "Huff... ";</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> print "It's inflated!^";</span>
|
|
<span class="plain-syntax"> ];</span>
|
|
</pre>
|
|
<p class="commentary">Note the very simple Inweb-style markup here. We do not use any of the fancier
|
|
features of literate programming (definitions, paragraph macros, and so on),
|
|
because the kit assimilator can only perform very simple tangling, and is not
|
|
nearly as strong as the full Inweb tangler.<sup id="fnref:5"><a href="#fn:5" rel="footnote">5</a></sup>
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:4"><p class="inwebfootnote"><sup id="fnref:4"><a href="#fn:4" rel="footnote">4</a></sup> It would have been conceivable to write such code directly as textual Inter,
|
|
but the experience would have been painful. Even in its textual form, Inter is not
|
|
very legible, and it is highly verbose.
|
|
<a href="#fnref:4" title="return to text"> ↩</a></p></li><li class="footnote" id="fn:5"><p class="inwebfootnote"><sup id="fnref:5"><a href="#fn:5" rel="footnote">5</a></sup> At some point it may be developed out a little, but there's no great need.
|
|
<a href="#fnref:5" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. </b>The metadata file at <span class="extract"><span class="extract-syntax">BalloonKit/kit_metadata.txt</span></span> is going to be simple:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">extension: Party Balloons by Joseph-Michel Montgolfier</span>
|
|
</pre>
|
|
<p class="commentary">In fact we don't really need this line at all (a kit does not need to have any
|
|
associated extensions), but it makes for a more interesting demonstration. We
|
|
can see an effect at once:
|
|
</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">inbuild/Tangled/inbuild</span><span class="ConsoleText-identifier-syntax"> -project</span><span class="ConsoleText-plain-syntax"> 'French Laundry.inform'</span><span class="ConsoleText-identifier-syntax"> -build-needs</span>
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: French Laundry.inform</span>
|
|
<span class="ConsoleText-plain-syntax"> ...</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BalloonKit</span>
|
|
<span class="ConsoleText-plain-syntax"> missing extension: Party Balloons by Joseph-Michel Montgolfier, any version will do</span>
|
|
<span class="ConsoleText-plain-syntax"> ...</span>
|
|
</pre>
|
|
<p class="commentary">This will, in fact, now fail to build, because Inform needs an extension which
|
|
it has not got. So suppose we provide one:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">Version</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="identifier-syntax">of</span><span class="plain-syntax"> </span><span class="identifier-syntax">Party</span><span class="plain-syntax"> </span><span class="identifier-syntax">Balloons</span><span class="plain-syntax"> </span><span class="identifier-syntax">by</span><span class="plain-syntax"> </span><span class="identifier-syntax">Joseph</span><span class="plain-syntax">-</span><span class="identifier-syntax">Michel</span><span class="plain-syntax"> </span><span class="identifier-syntax">Montgolfier</span><span class="plain-syntax"> </span><span class="identifier-syntax">begins</span><span class="plain-syntax"> </span><span class="identifier-syntax">here</span><span class="plain-syntax">.</span>
|
|
|
|
<span class="identifier-syntax">To</span><span class="plain-syntax"> </span><span class="identifier-syntax">perform</span><span class="plain-syntax"> </span><span class="identifier-syntax">an</span><span class="plain-syntax"> </span><span class="identifier-syntax">inflation</span><span class="plain-syntax"> </span><span class="identifier-syntax">with</span><span class="plain-syntax"> (</span><span class="identifier-syntax">N</span><span class="plain-syntax"> - </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax">) </span><span class="identifier-syntax">puff</span><span class="plain-syntax">/</span><span class="identifier-syntax">puffs</span><span class="plain-syntax">: (- </span><span class="identifier-syntax">InflateBalloon</span><span class="plain-syntax">({</span><span class="identifier-syntax">N</span><span class="plain-syntax">}); -).</span>
|
|
|
|
<span class="identifier-syntax">Party</span><span class="plain-syntax"> </span><span class="identifier-syntax">Balloons</span><span class="plain-syntax"> </span><span class="identifier-syntax">ends</span><span class="plain-syntax"> </span><span class="identifier-syntax">here</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">and place this file at:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">French Laundry.materials/Extensions/Joseph-Michel Montgolfier/Party Balloons.i7x</span>
|
|
</pre>
|
|
<p class="commentary">To make use of this, we'll change the French Laundry source text to:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">French</span><span class="plain-syntax"> </span><span class="identifier-syntax">Laundry</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">room</span><span class="plain-syntax">. </span><span class="string-syntax">"This fancy Sonoma restaurant has, for some reason,</span>
|
|
<span class="string-syntax">become a haunt of the pioneers of aeronautics."</span>
|
|
|
|
<span class="identifier-syntax">When</span><span class="plain-syntax"> </span><span class="identifier-syntax">play</span><span class="plain-syntax"> </span><span class="identifier-syntax">begins</span><span class="plain-syntax">:</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">perform</span><span class="plain-syntax"> </span><span class="identifier-syntax">an</span><span class="plain-syntax"> </span><span class="identifier-syntax">inflation</span><span class="plain-syntax"> </span><span class="identifier-syntax">with</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> </span><span class="identifier-syntax">puffs</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">Now Inbuild is happier:
|
|
</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">inbuild/Tangled/inbuild</span><span class="ConsoleText-identifier-syntax"> -project</span><span class="ConsoleText-plain-syntax"> 'French Laundry.inform'</span><span class="ConsoleText-identifier-syntax"> -build-needs</span>
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: French Laundry.inform</span>
|
|
<span class="ConsoleText-plain-syntax"> ...</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BalloonKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Party Balloons by Joseph-Michel Montgolfier v2</span>
|
|
<span class="ConsoleText-plain-syntax"> ...</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. </b>The whole point of a kit is to be precompiled code, so we had better compile it.
|
|
There are several ways to do this. One is to tell Inbuild directly:
|
|
</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">inbuild/Tangled/inbuild</span><span class="ConsoleText-identifier-syntax"> -build</span><span class="ConsoleText-plain-syntax"> 'French Laundry.materials/Inter/BalloonKit'</span>
|
|
</pre>
|
|
<p class="commentary">This then issues a series of commands to the <a href="../inter/index.html" class="internal">inter</a> tool, which actually
|
|
performs the work, compiling the kit for each architecture in turn. (These
|
|
commands are echoed to the console, so you can see exactly what is done, and
|
|
indeed you could always build the kit by hand using <a href="../inter/index.html" class="internal">inter</a> and not Inbuild.)
|
|
</p>
|
|
|
|
<p class="commentary">In fact, though, Inbuild can also make its own mind up about when a kit needs
|
|
to be compiled. Rather than build the kit, we can build the story:
|
|
</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">inbuild/Tangled/inbuild</span><span class="ConsoleText-identifier-syntax"> -project</span><span class="ConsoleText-plain-syntax"> French\ Laundry.inform</span><span class="ConsoleText-identifier-syntax"> -build</span>
|
|
</pre>
|
|
<p class="commentary">If BalloonKit needs building first, either because it has never been compiled or
|
|
because the source code for the kit has changed since it was last compiled,
|
|
then it will be built as part of the process; and if not, not.
|
|
</p>
|
|
|
|
<p class="commentary">And this incremental building is also what happens if the "French Laundry"
|
|
project is compiled in the Inform apps, by clicking "Go" in the usual way. Any
|
|
of its kits which need rebuilding are automatically rebuilt as part of the process.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>§12. Full specification of the kit metadata file. </b>This is a UTF-8 encoded Unicode text file, consisting of a sequence of commands
|
|
in any order, one per line. No commands are compulsory. An empty file is legal.
|
|
</p>
|
|
|
|
<p class="commentary">Blank lines are ignored, as are lines whose first non-white-space character is <span class="extract"><span class="ConsoleText-extract-syntax">#</span></span>,
|
|
which are considered comments.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>§13. </b><span class="extract"><span class="ConsoleText-extract-syntax">version: V</span></span> gives the kit's version number. This follows Inbuild's usual semantic
|
|
version numbering conventions, so for example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> version: 5</span>
|
|
<span class="plain-syntax"> version: 1.5.6-alpha.12</span>
|
|
</pre>
|
|
<p class="commentary">This is the version number which Inbuild will use to resolve dependencies. If a
|
|
project needs v1.7 or better, for example, Inbuild will not allow it to use
|
|
version 1.5.6-alpha.12 of a kit.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>§14. </b><span class="extract"><span class="extract-syntax">compatibility: C</span></span> allows us to say which architectures or final targets
|
|
the kit is compatible with. By default, Inbuild assumes it will work with anything,
|
|
equivalent to <span class="extract"><span class="extract-syntax">compatibility: all</span></span>. But for example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> compatibility: for 16-bit with debugging only</span>
|
|
<span class="plain-syntax"> compatibility: not for 32-bit</span>
|
|
<span class="plain-syntax"> compatibility: for Inform6 version 8</span>
|
|
<span class="plain-syntax"> compatibility: not for C</span>
|
|
</pre>
|
|
<p class="commentary">In general, it's best to stick to architectural constraints (i.e. 16 or 32 bit,
|
|
with or without debugging support) and not to constrain the final target unless
|
|
really necessary.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>§15. </b><span class="extract"><span class="extract-syntax">defines Main: yes</span></span> or <span class="extract"><span class="extract-syntax">defines Main: no</span></span>. The default is <span class="extract"><span class="extract-syntax">no</span></span>, so use this
|
|
only to specify that the kit contains within it a definition of the <span class="extract"><span class="extract-syntax">Main</span></span>
|
|
function. But only the shipped-with-Inform kits should ever do this.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>§16. </b><span class="extract"><span class="extract-syntax">natural language: yes</span></span> or <span class="extract"><span class="extract-syntax">natural language: no</span></span>. The default is <span class="extract"><span class="extract-syntax">no</span></span>; use
|
|
this only to say that the kit is a language support kit, like EnglishLanguageKit.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>§17. </b><span class="extract"><span class="extract-syntax">insert: X</span></span>. This sneakily allows a sentence of Inform 7 source text to be
|
|
inserted into any project using the kit. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> insert: Use maximum inflation level of 20.</span>
|
|
</pre>
|
|
<p class="commentary">But in general it's better not to use this at all, and to put any such material
|
|
in an associated extension which is automatically included.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>§18. </b><span class="extract"><span class="extract-syntax">kinds: F</span></span>, where <span class="extract"><span class="extract-syntax">F</span></span> is the name of a Neptune file. Neptune is a mini-language
|
|
for setting up kinds and kind constructors inside the compiler: see
|
|
<a href="../kinds-module/4-abgtn.html" class="internal">A Brief Guide to Neptune (in kinds)</a> for much more on this. The file <span class="extract"><span class="extract-syntax">F</span></span> should
|
|
be placed as <span class="extract"><span class="extract-syntax">BalloonKit/kinds/F</span></span>. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">kinds: Protocols.neptune</span>
|
|
<span class="plain-syntax">kinds: Core.neptune</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>§19. </b><span class="extract"><span class="extract-syntax">extension: E</span></span>, where <span class="extract"><span class="extract-syntax">E</span></span> is the name of an extension. A version number
|
|
can optionally be given, too. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">extension: Party Balloons by Joseph-Michel Montgolfier</span>
|
|
<span class="plain-syntax">extension: version 2.1 of Party Balloons by Joseph-Michel Montgolfier</span>
|
|
</pre>
|
|
<p class="commentary">Inbuild will now automatically include this extension if it can find it; if
|
|
not, the build will halt. Compatibility with the version number is done by
|
|
semantic version numbering rules, so v2.1.67 would be fine, but not v2.2, v1,
|
|
v3, and so forth. Note that kits can mandate multiple extensions, not just one.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>§20. </b><span class="extract"><span class="extract-syntax">activate: F</span></span> and <span class="extract"><span class="extract-syntax">deactivate: F</span></span>. This says that if the kit is present, then
|
|
a given feature inside the compiler <span class="extract"><span class="extract-syntax">F</span></span> should be switched on or off. For
|
|
example, the metadata for CommandParserKit includes:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">activate: command</span>
|
|
</pre>
|
|
<p class="commentary">which enables command grammar to be part of the Inform language. WorldModelKit
|
|
more ambitiously says:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">activate: interactive fiction</span>
|
|
<span class="plain-syntax">activate: multimedia</span>
|
|
</pre>
|
|
<p class="commentary">It is these activation lines, in WorldModelKit and CommandParserKit, which cause
|
|
the Inform language to have IF-specific features during a compilation. Without
|
|
them, the language would just be Basic Inform.
|
|
</p>
|
|
|
|
<p class="commentary">The feature names <span class="extract"><span class="extract-syntax">F</span></span> are the names of plugins inside the compiler, and this is
|
|
not the place to document that. See the implementation at <a href="../core-module/3-pm.html" class="internal">Chapter 3: Plugins (in core)</a>.
|
|
But in general, unless you are performing wild experiments with new language
|
|
features inside the compiler, never use <span class="extract"><span class="extract-syntax">activate</span></span> or <span class="extract"><span class="extract-syntax">deactivate</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>§21. </b><span class="extract"><span class="extract-syntax">dependency: if X then Y</span></span> and <span class="extract"><span class="extract-syntax">dependency: if not X then Y</span></span>. This specifies
|
|
dependencies between kits; often <span class="extract"><span class="extract-syntax">X</span></span> or <span class="extract"><span class="extract-syntax">Y</span></span> will be the kit you are currently
|
|
defining, but not necessarily. Rules are considered for all kits currently loaded.
|
|
For example, this is part of the metadata for CommandParserKit:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">dependency: if CommandParserKit then WorldModelKit</span>
|
|
</pre>
|
|
<p class="commentary">A few points to note:
|
|
</p>
|
|
|
|
<ul class="items"><li>● Rules are considered only for kits which are loaded. There is no way to
|
|
make BalloonKit parasitically attach to all projects by giving it the rule
|
|
<span class="extract"><span class="extract-syntax">if not BalloonKit then BalloonKit</span></span>, because this rule will only be looked at
|
|
if BalloonKit has already loaded.
|
|
</li><li>● The outcome cannot be <span class="extract"><span class="extract-syntax">... then not Y</span></span>; once loaded, a kit cannot be
|
|
unloaded. So these dependency rules can only cause extra kits to be added.
|
|
</li><li>● Positive rules <span class="extract"><span class="extract-syntax">if ...</span></span> are considered first, and only then negative ones
|
|
<span class="extract"><span class="extract-syntax">if not ...</span></span>. Within each category, kits have their rules looked at in order
|
|
of their priority (see below).
|
|
</li><li>● Version number requirements cannot be specified for either <span class="extract"><span class="extract-syntax">X</span></span> or <span class="extract"><span class="extract-syntax">Y</span></span>
|
|
at present.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP22" class="paragraph-anchor"></a><b>§22. </b><span class="extract"><span class="extract-syntax">priority: N</span></span>, where <span class="extract"><span class="extract-syntax">N</span></span> is a number from 0 to 100. This is used only to
|
|
decide whose wishes get priority when Inbuild is performing if-this-then-that
|
|
decisions to sort out which kits are present in a project. The default is 10,
|
|
and for almost all kits it should stay that way. Lower-numbered kits have
|
|
"more important" wishes than higher-numbered ones.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP23" class="paragraph-anchor"></a><b>§23. </b><span class="extract"><span class="extract-syntax">index from: C</span></span> can change the structure of the Index for a project using
|
|
this kit, but in practice this should be done only by BasicInformKit or by
|
|
WorldModelKit. (There are two versions of the index, one for Basic Inform
|
|
projects, the other for interactive-fiction ones.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP24" class="paragraph-anchor"></a><b>§24. Future directions. </b>It will be noted that a kit can include an extension automatically, but not
|
|
vice versa. Indeed, at present there is no way for Inform 7 source text to ask
|
|
for a kit to be included. This limitation is intentional for now.
|
|
</p>
|
|
|
|
<p class="commentary">A likely future development is that extensions will be made more powerful
|
|
by breaking the current requirement that every extension is a single file of
|
|
I7 source text. It seems possible that in future, an extension might be a
|
|
small package which could also include, for example, an accompanying kit.
|
|
But this has yet to be worked out, and involves questions of how Inbuild,
|
|
and the apps, the Public Library, and so on, would deal with all of that.
|
|
In the mean time, it seems premature to commit to any model.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-ui.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresscurrent">agtk</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>
|
|
|