<!--Weave of 'A Guide to Kits' generated by Inweb-->
<divclass="breadcrumbs">
<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="index.html">inbuild</a></li><li><ahref="index.html#M">Manual</a></li><li><b>A Guide to Kits</b></li></ul></div>
<pclass="purpose">Provisional documentation on how to make and build new kits.</p>
<ulclass="toc"><li><ahref="M-agtk.html#SP1">§1. Historical note</a></li><li><ahref="M-agtk.html#SP2">§2. Exactly how kit dependencies are worked out</a></li><li><ahref="M-agtk.html#SP12">§12. Full specification of the kit metadata file</a></li><li><ahref="M-agtk.html#SP24">§24. Future directions</a></li></ul><hrclass="tocbar">
<pclass="commentary firstcommentary"><aid="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 <spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="extract-syntax">Mathematics.i6t</span></span>
would be spliced in, and the result would, of course, be an I6 program.
</p>
<pclass="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>
<pclass="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>
<pclass="commentary firstcommentary"><aid="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:
<pclass="commentary">And these are also the defaults when Inform projects are compiled from the command
line, with the optional <spanclass="extract"><spanclass="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>
<pclass="commentary firstcommentary"><aid="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 <spanclass="extract"><spanclass="extract-syntax">BlkValueCreate</span></span> or <spanclass="extract"><spanclass="extract-syntax">IntegerDivide</span></span>.
Inbuild therefore makes every Inform project have BasicInformKit as a dependency.
</p>
<pclass="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 <spanclass="extract"><spanclass="extract-syntax">about.txt</span></span> file — see <ahref="../supervisor-module/5-ls.html"class="internal">Language Services (in supervisor)</a>— or, if the
<spanclass="extract"><spanclass="extract-syntax">about.txt</span></span> doesn't specify one, it's made by adding <spanclass="extract"><spanclass="extract-syntax">LanguageKit</span></span> to the language's
name. So if the French language bundle is used, then the default configurations
<pclass="commentary">Next, Inbuild adds a dependency on any kit which is named at the command line
using the <spanclass="extract"><spanclass="extract-syntax">-kit</span></span> switch. Note that this exists as a command-line switch for
both <spanclass="extract"><spanclass="extract-syntax">inbuild</span></span> and <spanclass="extract"><spanclass="extract-syntax">inform7</span></span>.
</p>
<pclass="commentary">Finally, Inbuild adds an automatic dependency on CommandParserKit if neither
the <spanclass="extract"><spanclass="extract-syntax">-kit</span></span> nor <spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="extract-syntax">-basic</span></span> or <spanclass="extract"><spanclass="extract-syntax">-kit</span></span>,
or by checking the "Basic Inform" checkbox in the apps.<supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup>
</p>
<ulclass="footnotetexts"><liclass="footnote"id="fn:1"><pclass="inwebfootnote"><supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> Checking this box equates to <spanclass="extract"><spanclass="extract-syntax">-basic</span></span>, which in turn is equivalent
to specifying <spanclass="extract"><spanclass="extract-syntax">-kit BasicInformKit</span></span>.
<ahref="#fnref:1"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="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 <spanclass="extract"><spanclass="extract-syntax">kit_metadata.txt</span></span> describing its needs. The metadata
<spanclass="plain-syntax">dependency: if not WorldModelKit then BasicInformExtrasKit</span>
</pre>
<pclass="commentary">It follows that if WorldModelKit is not present, then BasicInformExtrasKit is
automatically added instead.
</p>
<pclass="commentary firstcommentary"><aid="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.<supid="fnref:2"><ahref="#fn:2"rel="footnote">2</a></sup> For example, the <spanclass="extract"><spanclass="extract-syntax">kit_metadata.txt</span></span>
<spanclass="plain-syntax">extension: Basic Inform by Graham Nelson</span>
<spanclass="plain-syntax">extension: English Language by Graham Nelson</span>
</pre>
<ulclass="footnotetexts"><liclass="footnote"id="fn:2"><pclass="inwebfootnote"><supid="fnref:2"><ahref="#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.
<ahref="#fnref:2"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="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 <spanclass="extract"><spanclass="extract-syntax">-build-needs</span></span> option shows what is needed to build this project:
<spanclass="ConsoleText-plain-syntax"> extension: English Language by Graham Nelson v1</span>
</pre>
<pclass="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>
<pclass="commentary">As this shows, the same kit or extension may be needed for multiple reasons.
But it is only included once, of course.
</p>
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. </b>At the command line, either for Inbuild or Inform7, the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-kit</span></span> switch
can specify alternative kit(s) to use. Note that if any use is made of <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-kit</span></span>
then CommandParserKit and (in consequence) WorldModelKit are no longer auto-included.
For example, if <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-kit BalloonKit</span></span> is specified, then we will end up with:
<pclass="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 <spanclass="extract"><spanclass="extract-syntax">-kit</span></span>? However, a feature of Inform new in 2022 gets around
this. Additional command-line switches for <spanclass="extract"><spanclass="extract-syntax">inbuild</span></span> or for <spanclass="extract"><spanclass="extract-syntax">inform7</span></span> can be
placed in the Materials directory for an Inform project, in files called
<spanclass="extract"><spanclass="extract-syntax">inbuild-setting.txt</span></span> and <spanclass="extract"><spanclass="extract-syntax">inform7-settings.txt</span></span>.
</p>
<pclass="commentary">For example, suppose we set both<supid="fnref:3"><ahref="#fn:3"rel="footnote">3</a></sup> of these files to be:
<spanclass="ConsoleText-plain-syntax"> extension: English Language by Graham Nelson v1</span>
</pre>
<pclass="commentary">So now BalloonKit is indeed a dependency.
</p>
<pclass="commentary">See <ahref="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>
<ulclass="footnotetexts"><liclass="footnote"id="fn:3"><pclass="inwebfootnote"><supid="fnref:3"><ahref="#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.
<ahref="#fnref:3"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="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 <spanclass="extract"><spanclass="ConsoleText-extract-syntax">BalloonKit</span></span>.
This directory contains:
</p>
<ulclass="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 <ahref="../BasicInformKit/index.html"class="internal">BasicInformKit</a> for
an example of the result.) It is simple because it provides only a <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Contents.w</span></span>
page and a <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Sections</span></span> subdirectory — it has no manual, chapters, figures,
sounds or other paraphernalia.
</li><li>● A file called <spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="ConsoleText-extract-syntax">arch-A.interb</span></span>, where <spanclass="extract"><spanclass="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, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">arch-16d.interb</span></span> or <spanclass="extract"><spanclass="ConsoleText-extract-syntax">arch-32.interb</span></span>.
</li></ul>
<pclass="commentary firstcommentary"><aid="SP9"class="paragraph-anchor"></a><b>§9. </b>The source code is written in Inform 6 syntax.<supid="fnref:4"><ahref="#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>
<pclass="commentary">For <spanclass="extract"><spanclass="ConsoleText-extract-syntax">BalloonKit</span></span>, the contents page <spanclass="extract"><spanclass="ConsoleText-extract-syntax">BalloonKit/Contents.w</span></span> will be:
<spanclass="plain-syntax">Purpose: Inter-level support for inflating rubber-lined pockets of air.</span>
<spanclass="plain-syntax">Sections</span>
<spanclass="plain-syntax"> Inflation</span>
</pre>
<pclass="commentary">So there will be just one section, <spanclass="extract"><spanclass="extract-syntax">BalloonKit/Sections/Inflation.w</span></span>, which
<pclass="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.<supid="fnref:5"><ahref="#fn:5"rel="footnote">5</a></sup>
</p>
<ulclass="footnotetexts"><liclass="footnote"id="fn:4"><pclass="inwebfootnote"><supid="fnref:4"><ahref="#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.
<ahref="#fnref:4"title="return to text">↩</a></p></li><liclass="footnote"id="fn:5"><pclass="inwebfootnote"><supid="fnref:5"><ahref="#fn:5"rel="footnote">5</a></sup> At some point it may be developed out a little, but there's no great need.
<ahref="#fnref:5"title="return to text">↩</a></p></li></ul>
<pclass="commentary firstcommentary"><aid="SP10"class="paragraph-anchor"></a><b>§10. </b>The metadata file at <spanclass="extract"><spanclass="extract-syntax">BalloonKit/kit_metadata.txt</span></span> is going to be simple:
<spanclass="identifier-syntax">The</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">French</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">Laundry</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">is</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">a</span><spanclass="plain-syntax"></span><spanclass="identifier-syntax">room</span><spanclass="plain-syntax">. </span><spanclass="string-syntax">"This fancy Sonoma restaurant has, for some reason,</span>
<spanclass="string-syntax">become a haunt of the pioneers of aeronautics."</span>
<spanclass="ConsoleText-plain-syntax"> extension: Party Balloons by Joseph-Michel Montgolfier v2</span>
<spanclass="ConsoleText-plain-syntax"> ...</span>
</pre>
<pclass="commentary firstcommentary"><aid="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:
<pclass="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>
<pclass="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>
<pclass="commentary firstcommentary"><aid="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>
<pclass="commentary">Blank lines are ignored, as are lines whose first non-white-space character is <spanclass="extract"><spanclass="ConsoleText-extract-syntax">#</span></span>,
which are considered comments.
</p>
<pclass="commentary firstcommentary"><aid="SP13"class="paragraph-anchor"></a><b>§13. </b><spanclass="extract"><spanclass="ConsoleText-extract-syntax">version: V</span></span> gives the kit's version number. This follows Inbuild's usual semantic
<pclass="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>
<pclass="commentary firstcommentary"><aid="SP14"class="paragraph-anchor"></a><b>§14. </b><spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="extract-syntax">compatibility: all</span></span>. But for example:
<spanclass="plain-syntax"> compatibility: for 16-bit with debugging only</span>
<spanclass="plain-syntax"> compatibility: not for 32-bit</span>
<spanclass="plain-syntax"> compatibility: for Inform6 version 8</span>
<spanclass="plain-syntax"> compatibility: not for C</span>
</pre>
<pclass="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>
<pclass="commentary firstcommentary"><aid="SP15"class="paragraph-anchor"></a><b>§15. </b><spanclass="extract"><spanclass="extract-syntax">defines Main: yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">defines Main: no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>, so use this
only to specify that the kit contains within it a definition of the <spanclass="extract"><spanclass="extract-syntax">Main</span></span>
function. But only the shipped-with-Inform kits should ever do this.
</p>
<pclass="commentary firstcommentary"><aid="SP16"class="paragraph-anchor"></a><b>§16. </b><spanclass="extract"><spanclass="extract-syntax">natural language: yes</span></span> or <spanclass="extract"><spanclass="extract-syntax">natural language: no</span></span>. The default is <spanclass="extract"><spanclass="extract-syntax">no</span></span>; use
this only to say that the kit is a language support kit, like EnglishLanguageKit.
</p>
<pclass="commentary firstcommentary"><aid="SP17"class="paragraph-anchor"></a><b>§17. </b><spanclass="extract"><spanclass="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:
<spanclass="plain-syntax"> insert: Use maximum inflation level of 20.</span>
</pre>
<pclass="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>
<pclass="commentary firstcommentary"><aid="SP18"class="paragraph-anchor"></a><b>§18. </b><spanclass="extract"><spanclass="extract-syntax">kinds: F</span></span>, where <spanclass="extract"><spanclass="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
<ahref="../kinds-module/4-abgtn.html"class="internal">A Brief Guide to Neptune (in kinds)</a> for much more on this. The file <spanclass="extract"><spanclass="extract-syntax">F</span></span> should
be placed as <spanclass="extract"><spanclass="extract-syntax">BalloonKit/kinds/F</span></span>. For example:
<pclass="commentary firstcommentary"><aid="SP19"class="paragraph-anchor"></a><b>§19. </b><spanclass="extract"><spanclass="extract-syntax">extension: E</span></span>, where <spanclass="extract"><spanclass="extract-syntax">E</span></span> is the name of an extension. A version number
<spanclass="plain-syntax">extension: Party Balloons by Joseph-Michel Montgolfier</span>
<spanclass="plain-syntax">extension: version 2.1 of Party Balloons by Joseph-Michel Montgolfier</span>
</pre>
<pclass="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>
<pclass="commentary firstcommentary"><aid="SP20"class="paragraph-anchor"></a><b>§20. </b><spanclass="extract"><spanclass="extract-syntax">activate: F</span></span> and <spanclass="extract"><spanclass="extract-syntax">deactivate: F</span></span>. This says that if the kit is present, then
a given feature inside the compiler <spanclass="extract"><spanclass="extract-syntax">F</span></span> should be switched on or off. For
example, the metadata for CommandParserKit includes:
<pclass="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>
<pclass="commentary">The feature names <spanclass="extract"><spanclass="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 <ahref="../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 <spanclass="extract"><spanclass="extract-syntax">activate</span></span> or <spanclass="extract"><spanclass="extract-syntax">deactivate</span></span>.
</p>
<pclass="commentary firstcommentary"><aid="SP21"class="paragraph-anchor"></a><b>§21. </b><spanclass="extract"><spanclass="extract-syntax">dependency: if X then Y</span></span> and <spanclass="extract"><spanclass="extract-syntax">dependency: if not X then Y</span></span>. This specifies
dependencies between kits; often <spanclass="extract"><spanclass="extract-syntax">X</span></span> or <spanclass="extract"><spanclass="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:
<spanclass="plain-syntax">dependency: if CommandParserKit then WorldModelKit</span>
</pre>
<pclass="commentary">A few points to note:
</p>
<ulclass="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
<spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="extract-syntax">if ...</span></span> are considered first, and only then negative ones
<spanclass="extract"><spanclass="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 <spanclass="extract"><spanclass="extract-syntax">X</span></span> or <spanclass="extract"><spanclass="extract-syntax">Y</span></span>
at present.
</li></ul>
<pclass="commentary firstcommentary"><aid="SP22"class="paragraph-anchor"></a><b>§22. </b><spanclass="extract"><spanclass="extract-syntax">priority: N</span></span>, where <spanclass="extract"><spanclass="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>
<pclass="commentary firstcommentary"><aid="SP23"class="paragraph-anchor"></a><b>§23. </b><spanclass="extract"><spanclass="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>
<pclass="commentary firstcommentary"><aid="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>
<pclass="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.