mirror of
https://github.com/ganelson/inform.git
synced 2024-05-01 16:49:37 +03:00
627 lines
44 KiB
HTML
627 lines
44 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Using Inbuild</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<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 'Using Inbuild' 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>Using Inbuild</b></li></ul></div>
|
|
<p class="purpose">An introduction to the use of Inbuild on the command line.</p>
|
|
|
|
<ul class="toc"><li><a href="M-ui.html#SP1">§1. What Inbuild is</a></li><li><a href="M-ui.html#SP2">§2. Installation</a></li><li><a href="M-ui.html#SP3">§3. Basic concepts</a></li><li><a href="M-ui.html#SP5">§5. Graphs</a></li><li><a href="M-ui.html#SP11">§11. Building</a></li><li><a href="M-ui.html#SP13">§13. Specifying what to act on</a></li><li><a href="M-ui.html#SP15">§15. Nests and searches</a></li><li><a href="M-ui.html#SP18">§18. Copy, sync and archive</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. What Inbuild is. </b>Inbuild is a rudimentary build and package manager for the Inform tools.
|
|
It consists of a large part of the front end of the Inform 7 compiler,
|
|
together with a command-line interface to access its functions. Because
|
|
it doesn't contain the middle or back ends of Inform 7, it cannot itself
|
|
compile Inform projects. But it can issue shell commands which have
|
|
this effect. When used that way, it's a little like the traditional Unix
|
|
build tool <span class="extract"><span class="extract-syntax">make</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">It can also be used in <span class="extract"><span class="extract-syntax">make</span></span> scripts itself. Inbuild returns an exit code
|
|
of 0 if successful, or else it throws errors to <span class="extract"><span class="extract-syntax">stderr</span></span> and returns 1
|
|
if unsuccessful.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. Installation. </b>When it runs, Inbuild needs to know where it is installed in the file
|
|
system. There is no completely foolproof, cross-platform way to know this
|
|
(on some Unixes, a program cannot determine its own location), so Inbuild
|
|
decides by the following set of rules:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) If the user, at the command line, specified <span class="extract"><span class="extract-syntax">-at P</span></span>, for some path
|
|
<span class="extract"><span class="extract-syntax">P</span></span>, then we use that.
|
|
</li><li>(b) Otherwise, if the host operating system can indeed tell us where the
|
|
executable is, we use that. This is currently implemented only on MacOS,
|
|
Windows and Linux.
|
|
</li><li>(c) Otherwise, if the environment variable <span class="extract"><span class="extract-syntax">$INBUILD_PATH</span></span> exists and is
|
|
non-empty, we use that.
|
|
</li><li>(d) And if all else fails, we assume that the location is <span class="extract"><span class="extract-syntax">inbuild</span></span>, with
|
|
respect to the current working directory.
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. Basic concepts. </b>Inbuild manages "copies". A copy is an instance in the file system of an
|
|
asset like an Inform project, an extension, a kit of Inter code, and so on.
|
|
Those categories are called "genres". Any given copy will be a copy of
|
|
what is called an "edition", which in turn is a version of a "work".
|
|
</p>
|
|
|
|
<p class="commentary">For example, perhaps the user has two copies of version 3 of the extension
|
|
Locksmith by Emily Short, in different places in the file system, and also
|
|
a further copy of version 4. These are three different "copies", but only two
|
|
different "editions", and all are of the same "work". A work — in this case,
|
|
Locksmith by Emily Short — is identified by its title, author name and
|
|
genre — in this case, an Inform extension.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>Inbuild has a plethora of command-line options, but at its most basic, the
|
|
user should specify what to do and then give a list of things to do it to.
|
|
For example, here we run <span class="extract"><span class="extract-syntax">-inspect</span></span> on a single copy, and get a one-line
|
|
description of what it is:
|
|
</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"> -inspect</span><span class="ConsoleText-plain-syntax"> 'inform7/Internal/Extensions/Emily Short/Locksmith.i7x'</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Locksmith by Emily Short v12 in directory inform7/Internal/Extensions/Emily Short</span>
|
|
</pre>
|
|
<p class="commentary">This is reassuring — the file which looks as if it ought to be a copy of
|
|
Locksmith actually is. Inbuild always looks at the contents of something,
|
|
and doesn't trust its location as any indication of what it is. For
|
|
example:
|
|
</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"> -inspect</span><span class="ConsoleText-plain-syntax"> junk/Mystery.i7x</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Complex Listing by Emily Short v9 in directory junk.</span>
|
|
</pre>
|
|
<p class="commentary">If Inbuild can see that something is damaged in some way, it will report that.
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> extension: Skeleton Keys by Emily Short - 1 error</span>
|
|
<span class="ConsoleText-plain-syntax"> 1. extension misworded: the opening line does not end 'begin(s) here'</span>
|
|
</pre>
|
|
<p class="commentary">Only superficial problems can be spotted so far in advance of actually using
|
|
the software, but it's still helpful.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. Graphs. </b>More ambitiously, we can look at the "graph" of a copy.
|
|
</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"> -graph</span><span class="ConsoleText-plain-syntax"> 'Basic Help Menu.i7x'</span>
|
|
<span class="ConsoleText-plain-syntax"> [c0] Basic Help Menu by Emily Short</span>
|
|
<span class="ConsoleText-plain-syntax"> --use---> [c26] Menus by Emily Short v3</span>
|
|
<span class="ConsoleText-plain-syntax"> --use---> [c34] Basic Screen Effects by Emily Short v8</span>
|
|
</pre>
|
|
<p class="commentary">The graph begins at the copy we asked for, and then continues through arrows
|
|
to other copies. It gives a systematic answer to the question "how do I
|
|
build or use this?". There are two kinds of arrows, use arrows and build
|
|
arrows. A use arrow from A to B means that you need to have B installed
|
|
in order to be able to use A. The above example, then, tells us that we need
|
|
Menus in order to use Basic Help Menu, and we need Basic Screen Effects in
|
|
order to use Menus.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>Now suppose we have an Inform project called <span class="extract"><span class="ConsoleText-extract-syntax">Menu Time.inform</span></span>, whose
|
|
source text is as follows:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">Include</span><span class="plain-syntax"> </span><span class="identifier-syntax">Basic</span><span class="plain-syntax"> </span><span class="identifier-syntax">Help</span><span class="plain-syntax"> </span><span class="identifier-syntax">Menu</span><span class="plain-syntax"> </span><span class="identifier-syntax">by</span><span class="plain-syntax"> </span><span class="identifier-syntax">Emily</span><span class="plain-syntax"> </span><span class="identifier-syntax">Short</span><span class="plain-syntax">.</span>
|
|
|
|
<span class="plain-syntax"> </span><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>
|
|
</pre>
|
|
<p class="commentary">Once again, we can inspect this:
|
|
</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"> -inspect</span><span class="ConsoleText-plain-syntax"> 'Menu Time.inform'</span>
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: Menu Time.inform at path Menu Time.inform</span>
|
|
</pre>
|
|
<p class="commentary">We can also use <span class="extract"><span class="ConsoleText-extract-syntax">-graph</span></span>, but the output from this is surprisingly long,
|
|
because an innocent-looking source text like the above depends on many other
|
|
resources.
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> [f59] Menu Time.inform/Build/output.ulx</span>
|
|
<span class="ConsoleText-plain-syntax"> --build-> [f58] Menu Time.inform/Build/auto.inf</span>
|
|
<span class="ConsoleText-plain-syntax"> --build-> [f57] Menu Time.inform/Build/auto.inf</span>
|
|
<span class="ConsoleText-plain-syntax"> --build-> [c0] Menu Time.inform</span>
|
|
<span class="ConsoleText-plain-syntax"> --build-> [c53] Basic Help Menu by Emily Short</span>
|
|
<span class="ConsoleText-plain-syntax"> --use---> [c47] Menus by Emily Short v3</span>
|
|
<span class="ConsoleText-plain-syntax"> --use---> [c55] Basic Screen Effects by Emily Short v8</span>
|
|
<span class="ConsoleText-plain-syntax"> --build-> [f1] Menu Time.inform/Source/story.ni</span>
|
|
<span class="ConsoleText-plain-syntax"> --build-> [c12] BasicInformKit</span>
|
|
</pre>
|
|
<p class="commentary">...and so on. What's going on here is that if the user wants to compile the
|
|
source text, that will (by default) mean making a story file in Glulx format,
|
|
called <span class="extract"><span class="ConsoleText-extract-syntax">output.ulx</span></span>, which sits inside the project bundle. So that is the top
|
|
node. Note that it is a "file node", not a "copy node", as we can see from the
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">f</span></span> not <span class="extract"><span class="ConsoleText-extract-syntax">c</span></span> in its node number. This means that <span class="extract"><span class="ConsoleText-extract-syntax">output.ulx</span></span> is not a kind of
|
|
resource managed by Inbuild (like an extension, pr a project): it's just a
|
|
plain old file.
|
|
</p>
|
|
|
|
<p class="commentary">There's then a build arrow to another file called <span class="extract"><span class="ConsoleText-extract-syntax">auto.inf</span></span>. That's because
|
|
in order to build <span class="extract"><span class="ConsoleText-extract-syntax">output.ulx</span></span>, we first need <span class="extract"><span class="ConsoleText-extract-syntax">auto.inf</span></span> to exist. This is
|
|
a file in Inform 6 format. Something unexpected then happens: a further arrow
|
|
appears, and connects to another <span class="extract"><span class="ConsoleText-extract-syntax">auto.inf</span></span>. There aren't really two files
|
|
here: this is a device to capture the fact that generating <span class="extract"><span class="ConsoleText-extract-syntax">auto.inf</span></span> is a
|
|
two-stage process, with the intermediate results between the two stages
|
|
being held in memory rather than in a file. (These stages are, first,
|
|
converting I7 source text to inter code, and then code-generating that
|
|
inter code to I6.) Finally, though, we have a build arrow leading to the
|
|
place we might have expected to start: the <span class="extract"><span class="ConsoleText-extract-syntax">Menu Time.inform</span></span> project.
|
|
</p>
|
|
|
|
<p class="commentary">And that is where the graph branches outwards, because we need many
|
|
different resources in order to build <span class="extract"><span class="ConsoleText-extract-syntax">Menu Time.inform</span></span>. We finally see
|
|
that we need Basic Help Menu, and because that uses two other extensions
|
|
in turn, we'll need both of those as well. We need the actual file which
|
|
holds the source text inside the project bundle, <span class="extract"><span class="ConsoleText-extract-syntax">story.ni</span></span>. And then
|
|
we need various build-in extensions and kits, the first of which is
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">BasicInformKit</span></span>, and that turns out to need lots of files to exist.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. </b>The full <span class="extract"><span class="ConsoleText-extract-syntax">-graph</span></span> is not always what we want to see. Often all we really
|
|
want to know is: what do I need to use, or to build, something?
|
|
</p>
|
|
|
|
<p class="commentary">The command <span class="extract"><span class="ConsoleText-extract-syntax">-use-needs</span></span> applied to our example extension gives:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Help Menu by Emily Short</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Menus by Emily Short v3</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Screen Effects by Emily Short v8</span>
|
|
</pre>
|
|
<p class="commentary">and applied to our example story gives just:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: Menu Time.inform</span>
|
|
</pre>
|
|
<p class="commentary">That's because once Menu Time is built, nothing else is needed to use it.
|
|
On the other hand, <span class="extract"><span class="ConsoleText-extract-syntax">-build-needs</span></span> has the opposite effect. Applied to the
|
|
extension, we get:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Help Menu by Emily Short</span>
|
|
</pre>
|
|
<p class="commentary">because extensions need no building, so certainly nothing else is needed
|
|
to build them. But <span class="extract"><span class="ConsoleText-extract-syntax">-build-needs</span></span> on our story produces:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> projectbundle: Menu Time.inform</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Help Menu by Emily Short</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Menus by Emily Short v3</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Basic Screen Effects by Emily Short v8</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"> kit: WorldModelKit</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Standard Rules by Graham Nelson v6</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">And there it is: six extensions, four kits and one natural language definition
|
|
are needed. Two of the extensions are listed twice: that's because they are
|
|
each needed for two different reasons.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>The version numbers listed above do not mean that only those exact versions
|
|
will do: they mean that this is (the best) version Inbuild has access to.
|
|
They're given because two different versions of the same extension might
|
|
make different choices about which other extensions to include. We can say
|
|
that version 3 of Menus wants to have Basic Screen Effects, but maybe someday
|
|
there will be a version 4 which doesn't need it.
|
|
</p>
|
|
|
|
<p class="commentary">Another issue to watch out for is that a copy may use different other copies
|
|
when compiled to different virtual machines. For example, an extension can
|
|
contain a heading of material "for Glulx only", and that heading might
|
|
comtain a line which includes another extension X. If so, then we use X on
|
|
Glulx but not on other architectures. We can also flag material as being for
|
|
release only, or for debugging only.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild accepts the same command-line options as <span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> does to specify
|
|
these: <span class="extract"><span class="ConsoleText-extract-syntax">-debug</span></span> for debugging features, <span class="extract"><span class="ConsoleText-extract-syntax">-release</span></span> for a release run, and
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">-format=X</span></span> to select a virtual machine. (See the <span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> documentation.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b>Now suppose that the project asks for something impossible, with a line
|
|
such as:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Include Xylophones by Jimmy Stewart.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">No such extension exists. If we look at the graph, or the <span class="extract"><span class="ConsoleText-extract-syntax">-build-needs</span></span> list
|
|
for the project, we see that it includes:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> missing extension: Xylophones by Jimmy Stewart, any version will do</span>
|
|
</pre>
|
|
<p class="commentary">If we had instead written:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Include version 6.2 of Xylophones by Jimmy Stewart.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">we would see:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> missing extension: Xylophones by Jimmy Stewart, need version in range [6.2,7-A)</span>
|
|
</pre>
|
|
<p class="commentary">This slightly arcane mathematical notation means that Inform would accept any
|
|
version from 6.2 upwards, provided it still begins with a 6. This is a change
|
|
over pre-2020 versions of Inform, and has been brought about by the adoption
|
|
of the semantic version number standard.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild can list missing resources with <span class="extract"><span class="ConsoleText-extract-syntax">-use-missing</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">-build-missing</span></span>
|
|
respectively. At present, it has no means of fetching missing resources from
|
|
any central repository.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. </b>Finally, <span class="extract"><span class="ConsoleText-extract-syntax">-build-locate</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">-use-locate</span></span> are identical to <span class="extract"><span class="ConsoleText-extract-syntax">-build-needs</span></span>
|
|
and <span class="extract"><span class="ConsoleText-extract-syntax">-use-needs</span></span>, except that they print a list of the file system paths at
|
|
which the relevant resources have been found. This can be useful if you're
|
|
managing a complex mass of extensions, and aren't sure (say) which actual copy
|
|
of Xylophones inbuild proposes to use, and from where.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. Building. </b>The graph for a copy tells Inbuild not only what is necessary for a build,
|
|
but also how to perform that build.
|
|
</p>
|
|
|
|
<p class="commentary">As noted above, not everything needs building. Extensions do not, in particular,
|
|
so running <span class="extract"><span class="ConsoleText-extract-syntax">-build</span></span> on one will do nothing. Kits do need building: what this
|
|
does is to "assimilate" the Inform 6-notation source files inside the kit into
|
|
binary files of Inter, one for each possible architecture.
|
|
</p>
|
|
|
|
<p class="commentary">But building is mostly done with projects. If we run:
|
|
</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"> Example.inform</span>
|
|
</pre>
|
|
<p class="commentary">then Inbuild will first build everything needed to build the Example story
|
|
file, including everything needed to use the things needed to build it, and
|
|
so on; and then will build Example itself. As with the Unix utility <span class="extract"><span class="ConsoleText-extract-syntax">make</span></span>,
|
|
this is an incremental process, and looks at the timestamps of files to see
|
|
which steps are needed and which are not. If all the kits needed by Example
|
|
are up to date, then the kits will not be rebuilt, and so on. If the same
|
|
project is built twice in a row, and nothing about it has changed since
|
|
the first time, the second <span class="extract"><span class="ConsoleText-extract-syntax">-build</span></span> does nothing.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild uses the graph to work out what needs to be done, and then issues
|
|
a series of shell commands to other Inform tools. If any of those commands
|
|
fail (returning a non-zero exit code) then the build process halts at once.
|
|
</p>
|
|
|
|
<p class="commentary">As noted above, the <span class="extract"><span class="ConsoleText-extract-syntax">-release</span></span> switch tells Inbuild that we want to go all
|
|
the way to a release of the project, not just a build. This makes a more
|
|
extensive graph, and is likely to mean that the final step followed by
|
|
Inbuild is a call to <span class="extract"><span class="ConsoleText-extract-syntax">inblorb</span></span>, the releasing tool for Inform.
|
|
</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"> -release -build</span><span class="ConsoleText-plain-syntax"> Example.inform</span>
|
|
</pre>
|
|
<p class="commentary">Using the <span class="extract"><span class="ConsoleText-extract-syntax">-rebuild</span></span> command performs a build in a way which isn't incremental:
|
|
timestamps of files are ignored and everything is remade from scratch.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>§12. </b>It takes a certain trust to just let Inbuild rip, and if you don't feel that
|
|
trust, adding the <span class="extract"><span class="ConsoleText-extract-syntax">-dry</span></span> switch causes shell commands to be printed out but
|
|
not actually executed — a dry run. If you are debugging Inbuild, you may
|
|
also want to look at the copious output produced when <span class="extract"><span class="ConsoleText-extract-syntax">-build-trace</span></span> is used.
|
|
These are not commands: they simply modify the behaviour of <span class="extract"><span class="ConsoleText-extract-syntax">-build</span></span> and
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">-rebuild</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild uses a handful of standard Unix shell commands, but it also uses
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">inform6</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">inblorb</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">inter</span></span>. To do that, it needs to know
|
|
where they are installed. By default, Inbuild assumes they are in the same
|
|
folder as Inbuild itself, side by side. If not, you can use <span class="extract"><span class="ConsoleText-extract-syntax">-tools P</span></span> to
|
|
specify path <span class="extract"><span class="ConsoleText-extract-syntax">P</span></span> as the home of the other Intools.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>§13. Specifying what to act on. </b>In all of the examples above, Inbuild is given just one copy to act on.
|
|
(That action may end up involving lots of other copies, but only one is
|
|
mentioned on the command line.) In fact it's legal to give a list of
|
|
copies to work on, one at a time, except that only one of those copies
|
|
can be an Inform project. Multiple extensions, or kits, are fine.
|
|
</p>
|
|
|
|
<p class="commentary">We can also tell Inbuild to work on everything it finds in a given directory
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">D</span></span> using <span class="extract"><span class="ConsoleText-extract-syntax">-contents-of D</span></span>:
|
|
</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"> -inspect -contents-of</span><span class="ConsoleText-plain-syntax"> inform7/Internal/Inter</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: EnglishLanguageKit at path inform7/Internal/Inter/EnglishLanguageKit</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: CommandParserKit at path inform7/Internal/Inter/CommandParserKit</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BasicInformExtrasKit at path inform7/Internal/Inter/BasicInformExtrasKit</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: WorldModelKit at path inform7/Internal/Inter/WorldModelKit</span>
|
|
<span class="ConsoleText-plain-syntax"> kit: BasicInformKit at path inform7/Internal/Inter/BasicInformKit</span>
|
|
</pre>
|
|
<p class="commentary">For compatibility with the <span class="extract"><span class="ConsoleText-extract-syntax">inform7</span></span> command line syntax, we can also specify
|
|
the project target using <span class="extract"><span class="ConsoleText-extract-syntax">-project</span></span>:
|
|
</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 -project</span><span class="ConsoleText-plain-syntax"> Example.inform</span>
|
|
</pre>
|
|
<p class="commentary">But this is quite unnecessary: the effect is the same as if <span class="extract"><span class="ConsoleText-extract-syntax">-project</span></span> had
|
|
been missed out.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>§14. </b>Listing filenames or pathnames of copies on the command line, or using the
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">-contents-of D</span></span> switch, is only possible if we know where in the file system
|
|
these copies are; and sometimes we do not.
|
|
</p>
|
|
|
|
<p class="commentary">If we instead specify <span class="extract"><span class="ConsoleText-extract-syntax">-matching R</span></span>, where <span class="extract"><span class="ConsoleText-extract-syntax">R</span></span> is a list of requirements,
|
|
Inbuild will act on every copy it can find which matches that. For example,
|
|
</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"> -inspect -matching</span><span class="ConsoleText-plain-syntax"> 'genre=kit'</span>
|
|
</pre>
|
|
<p class="commentary">lists all the kits which Inbuild can see; and
|
|
</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"> -inspect -matching</span><span class="ConsoleText-plain-syntax"> 'genre=extension,author=Eric Eve'</span>
|
|
</pre>
|
|
<p class="commentary">lists all extensions by Eric Eve which Inbuild can see. The legal clauses to
|
|
specify are <span class="extract"><span class="ConsoleText-extract-syntax">title</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">author</span></span>, <span class="extract"><span class="ConsoleText-extract-syntax">genre</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">version</span></span>. Note that <span class="extract"><span class="ConsoleText-extract-syntax">version=5.1.1</span></span>
|
|
would match version numbers 5.1.1, 5.1.2, 5.2.0, etc., but not 6 or above:
|
|
again, this is following semver conventions. (Extensions giving their version
|
|
numbers in the old-fashioned format "N/YYMMDD" are read as if N.0.YYMMDD, with
|
|
the release date being treated as a patch number: see the Inform language
|
|
documentation for examples.)
|
|
</p>
|
|
|
|
<p class="commentary">To specify an explicit maximum and minimum version number, use <span class="extract"><span class="ConsoleText-extract-syntax">max</span></span> and <span class="extract"><span class="ConsoleText-extract-syntax">min</span></span>. For example:
|
|
</p>
|
|
|
|
<pre class="ConsoleText-displayed-code all-displayed-code code-font">
|
|
<span class="ConsoleText-plain-syntax"> -matching 'genre=extension,author=Emily Short,title=Locksmith,min=6.1-alpha.2,max=17.2'</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>§15. Nests and searches. </b>When searching with <span class="extract"><span class="ConsoleText-extract-syntax">-matching R</span></span>, or indeed when running Inform and needing
|
|
to find certain resources, Inbuild looks inside what are called "nests".
|
|
</p>
|
|
|
|
<p class="commentary">A nest is a directory with structured subdirectories, which correspond to
|
|
the genres of copies put into them. For example, in the standard distribution
|
|
of Inform as a command-line tool, the path <span class="extract"><span class="ConsoleText-extract-syntax">inform7/Internal</span></span> is a nest:
|
|
this contains the extensions, kits and so on which are built in to Inform
|
|
when it's used as an app.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild recognises the following subdirectories of a nest as significant:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Templates</span>
|
|
<span class="plain-syntax"> Pipelines</span>
|
|
<span class="plain-syntax"> Inter</span>
|
|
<span class="plain-syntax"> Languages</span>
|
|
<span class="plain-syntax"> Extensions</span>
|
|
</pre>
|
|
<p class="commentary">Other subdirectories can also exist, and Inbuild ignores those. The above
|
|
five containers hold website templates (used by Inblorb), Inter pipelines,
|
|
kits, language definitions, and extensions. In the case of extensions, where
|
|
there may be very many in total, a further level of subdirectory is used
|
|
for the author's name. Thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Extensions/Emily Short/Locksmith.i7x</span>
|
|
</pre>
|
|
<p class="commentary">(In some early releases of Inform 7, it was legal for this file not to have
|
|
the <span class="extract"><span class="extract-syntax">.i7x</span></span> extension: but now it is compulsory.)
|
|
</p>
|
|
|
|
<p class="commentary">As of 2020, nests can contain multiple versions of the same work. To do
|
|
this, they should have a filename (or pathname) which ends with <span class="extract"><span class="extract-syntax">-vN</span></span>, where
|
|
<span class="extract"><span class="extract-syntax">N</span></span> is semantic version number but with any dots replaced by underscores.
|
|
Thus, we can have e.g.:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Extensions/Emily Short/Locksmith-v3_2.i7x</span>
|
|
<span class="plain-syntax"> Extensions/Emily Short/Locksmith-v4_0_0-prealpha_13.i7x</span>
|
|
</pre>
|
|
<p class="commentary">co-existing side by side. If the user asks to
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Include Locksmith by Emily Short.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">then version <span class="extract"><span class="extract-syntax">4.0.0-prealpha.13</span></span> will be chosen, as the one with highest
|
|
precedence in this nest (but see below for how Inbuild chooses between
|
|
versions in the same nest). But if the user asks for
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Include version 3 Locksmith by Emily Short.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">then version <span class="extract"><span class="extract-syntax">3.2</span></span> is the winner, as the highest-numbered extension in the
|
|
nest with the right major version number (3).
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>§16. </b>In most runs of the Inform compiler, three nests are used: the "internal"
|
|
one, so-called, which holds built-in extensions and is read-only; the
|
|
"external" one, which will be somewhere outside of the Inform GUI app, and
|
|
will hold additional extensions downloaded by the user; and the Materials
|
|
folder for an Inform project, which is a nest all by itself.
|
|
</p>
|
|
|
|
<p class="commentary">Inbuild looks for these as follows:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) <span class="extract"><span class="extract-syntax">-internal N</span></span> tells Inbuild the path <span class="extract"><span class="extract-syntax">N</span></span> for the internal nest; if this
|
|
is not given, the default is <span class="extract"><span class="extract-syntax">inform7/Internal</span></span>.
|
|
</li><li>(b) <span class="extract"><span class="extract-syntax">-external N</span></span> tells Inbuild the path <span class="extract"><span class="extract-syntax">N</span></span> for the external nest; if this
|
|
is not given, the default depends on the host operating system. For example,
|
|
on MacOS it will be <span class="extract"><span class="extract-syntax">~/Library/Inform</span></span> (which is what the Inform GUI app
|
|
uses too if it is not sandboxed: if it is indeed sandboxed, then it will
|
|
have a deliberately obfuscated location which MacOS does not want tools
|
|
like ours to access externally).
|
|
</li><li>(c) The Materials nest is always the Materials folder associated with the
|
|
project Inbuild is working on; if it isn't working on a project, then this
|
|
nest is of course not present.
|
|
</li></ul>
|
|
<p class="commentary">In addition, extra nests can be specified with <span class="extract"><span class="extract-syntax">-nest N</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>§17. </b>When Inbuild searches for some resource needed by Inform — let's continue
|
|
to use the Locksmith extension as an example — it always has some range of
|
|
version numbers in mind: it will only accept a version in that range. (The
|
|
range can be unlimited, in which case any version is acceptable.)
|
|
</p>
|
|
|
|
<p class="commentary">This may well produce multiple results: as noted above, we might have multiple
|
|
copies of Locksmith around. Inbuild first reduces the list to just those
|
|
whose version lies in the acceptable range. It then applies the following
|
|
rules:
|
|
</p>
|
|
|
|
<ul class="items"><li>(1) A copy in the Materials nest takes precedence over all others.
|
|
</li><li>(2) Otherwise, all other copies take precedence over those in the
|
|
internal nest.
|
|
</li><li>(3) Otherwise, semantic version number rules are used to determine which
|
|
copy had precedence.
|
|
</li></ul>
|
|
<p class="commentary">Suppose the Materials folder for our project contains <span class="extract"><span class="extract-syntax">Locksmith-v3_2.i7x</span></span>,
|
|
while the external folder contains <span class="extract"><span class="extract-syntax">Locksmith-v3_3.i7x</span></span> and <span class="extract"><span class="extract-syntax">Locksmith-v4.i7x</span></span>.
|
|
Then the sentence:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Include Locksmith by Emily Short.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">would result in <span class="extract"><span class="extract-syntax">Locksmith-v3_2.i7x</span></span> from Materials being used, even though
|
|
there's a later version in the external area: Materials always wins. But
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>Include version 4 of Locksmith by Emily Short.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">would use <span class="extract"><span class="extract-syntax">Locksmith-v4.i7x</span></span> from the external area, because the copy in the
|
|
Materials folder doesn't qualify.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>§18. Copy, sync and archive. </b>Clerical work is generally best done automatically, and Inbuild offers some
|
|
useful filing commands.
|
|
</p>
|
|
|
|
<p class="commentary">The command <span class="extract"><span class="extract-syntax">-copy-to N</span></span> makes a duplicate copy in the nest <span class="extract"><span class="extract-syntax">N</span></span>. For example:
|
|
</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"> -inspect</span><span class="ConsoleText-plain-syntax"> junk/Mystery.i7x</span>
|
|
<span class="ConsoleText-plain-syntax"> extension: Complex Listing by Emily Short v9 in directory junk.</span>
|
|
<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"> -copy-to</span><span class="ConsoleText-plain-syntax"> MyNest junk/Mystery.i7x</span>
|
|
<span class="ConsoleText-plain-syntax"> cp -f 'junk/Mystery.i7x' 'MyNest/Extensions/Emily Short/Complex Listing-v9.i7x'</span>
|
|
</pre>
|
|
<p class="commentary">Note that Inbuild replies to the <span class="extract"><span class="ConsoleText-extract-syntax">-copy-to N</span></span> command by executing a shell
|
|
command to copy what is, in this case, a single file. As when building, the
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">-dry</span></span> option puts Inbuild into dry-run mode, where it prints the commands it
|
|
would like to execute but doesn't execute them.
|
|
</p>
|
|
|
|
<p class="commentary">The command <span class="extract"><span class="ConsoleText-extract-syntax">-sync-to N</span></span> is similar, but will overwrite any existing copy
|
|
already in <span class="extract"><span class="ConsoleText-extract-syntax">N</span></span>, rather than producing an error if a collision occurs.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>§19. </b>The <span class="extract"><span class="ConsoleText-extract-syntax">-archive-to N</span></span> command performs <span class="extract"><span class="ConsoleText-extract-syntax">-sync-to N</span></span> on any resource needed
|
|
to build the copy it is working on (with one exception, for technical reasons:
|
|
the configuration file telling Inform how to use the English natural language).
|
|
</p>
|
|
|
|
<p class="commentary">This is really only useful for Inform projects, and the abbreviated form
|
|
<span class="extract"><span class="ConsoleText-extract-syntax">-archive</span></span> performs <span class="extract"><span class="ConsoleText-extract-syntax">-archive-to</span></span> to the Materials folder for a project.
|
|
The net effect of this is that all extensions needed to build a story file
|
|
are gathered, with their correct versions, into the Materials folder; this
|
|
means that if the project and its Materials are moved to a different user's
|
|
computer, where a quite different set of extensions may be installed, then
|
|
the project will still work exactly as it originally did.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprevoff">❮</li><li class="progresscurrentchapter">M</li><li class="progresscurrent">ui</li><li class="progresssection"><a href="M-agtk.html">agtk</a></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-agtk.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|