2020-01-28 00:51:46 +02:00
|
|
|
Using Inbuild.
|
|
|
|
|
2020-03-26 21:22:26 +02:00
|
|
|
An introduction to the use of Inbuild on the command line.
|
2020-01-28 00:51:46 +02:00
|
|
|
|
2020-03-26 21:22:26 +02:00
|
|
|
@h What Inbuild is.
|
|
|
|
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 |make|.
|
|
|
|
|
|
|
|
It can also be used in |make| scripts itself. Inbuild returns an exit code
|
|
|
|
of 0 if successful, or else it throws errors to |stderr| and returns 1
|
|
|
|
if unsuccessful.
|
|
|
|
|
|
|
|
@h Installation.
|
|
|
|
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:
|
|
|
|
|
|
|
|
(a) If the user, at the command line, specified |-at P|, for some path
|
|
|
|
|P|, then we use that.
|
|
|
|
(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.
|
|
|
|
(c) Otherwise, if the environment variable |$INBUILD_PATH| exists and is
|
|
|
|
non-empty, we use that.
|
|
|
|
(d) And if all else fails, we assume that the location is |inbuild|, with
|
|
|
|
respect to the current working directory.
|
|
|
|
|
|
|
|
@h Basic concepts.
|
|
|
|
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".
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
@ 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 |-inspect| on a single copy, and get a one-line
|
|
|
|
description of what it is:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect 'inform7/Internal/Extensions/Emily Short/Locksmith.i7x'
|
|
|
|
extension: Locksmith by Emily Short v12 in directory inform7/Internal/Extensions/Emily Short
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
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:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect junk/Mystery.i7x
|
|
|
|
extension: Complex Listing by Emily Short v9 in directory junk.
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
If Inbuild can see that something is damaged in some way, it will report that.
|
|
|
|
For example,
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
extension: Skeleton Keys by Emily Short - 1 error
|
|
|
|
1. extension misworded: the opening line does not end 'begin(s) here'
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
Only superficial problems can be spotted so far in advance of actually using
|
|
|
|
the software, but it's still helpful.
|
|
|
|
|
|
|
|
@h Graphs.
|
|
|
|
More ambitiously, we can look at the "graph" of a copy.
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -graph 'Basic Help Menu.i7x'
|
|
|
|
[c0] Basic Help Menu by Emily Short
|
|
|
|
--use---> [c26] Menus by Emily Short v3
|
|
|
|
--use---> [c34] Basic Screen Effects by Emily Short v7.140425
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
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
|
|
|
|
Menus in order to use Basic Help Menu, and we need Basic Screen Effects in
|
|
|
|
order to use Menus.
|
|
|
|
|
|
|
|
@ Now suppose we have an Inform project called |Menu Time.inform|, whose
|
|
|
|
source text is as follows:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as Inform 7)
|
|
|
|
Include Basic Help Menu by Emily Short.
|
|
|
|
|
|
|
|
The French Laundry is a room.
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
Once again, we can inspect this:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect 'Menu Time.inform'
|
|
|
|
projectbundle: Menu Time.inform at path Menu Time.inform
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
We can also use |-graph|, but the output from this is surprisingly long,
|
|
|
|
because an innocent-looking source text like the above depends on many other
|
|
|
|
resources.
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
[f59] Menu Time.inform/Build/output.ulx
|
|
|
|
--build-> [f58] Menu Time.inform/Build/auto.inf
|
|
|
|
--build-> [f57] Menu Time.inform/Build/auto.inf
|
|
|
|
--build-> [c0] Menu Time.inform
|
|
|
|
--build-> [c53] Basic Help Menu by Emily Short
|
|
|
|
--use---> [c47] Menus by Emily Short v3
|
|
|
|
--use---> [c55] Basic Screen Effects by Emily Short v7.140425
|
|
|
|
--build-> [f1] Menu Time.inform/Source/story.ni
|
|
|
|
--build-> [c12] BasicInformKit
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
...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 |output.ulx|, 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
|
|
|
|
|f| not |c| in its node number. This means that |output.ulx| is not a kind of
|
|
|
|
resource managed by Inbuild (like an extension, pr a project): it's just a
|
|
|
|
plain old file.
|
|
|
|
|
|
|
|
There's then a build arrow to another file called |auto.inf|. That's because
|
|
|
|
in order to build |output.ulx|, we first need |auto.inf| to exist. This is
|
|
|
|
a file in Inform 6 format. Something unexpected then happens: a further arrow
|
|
|
|
appears, and connects to another |auto.inf|. There aren't really two files
|
|
|
|
here: this is a device to capture the fact that generating |auto.inf| 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 |Menu Time.inform| project.
|
|
|
|
|
|
|
|
And that is where the graph branches outwards, because we need many
|
|
|
|
different resources in order to build |Menu Time.inform|. 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, |story.ni|. And then
|
|
|
|
we need various build-in extensions and kits, the first of which is
|
|
|
|
|BasicInformKit|, and that turns out to need lots of files to exist.
|
|
|
|
|
|
|
|
@ The full |-graph| 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?
|
|
|
|
|
|
|
|
The command |-use-needs| applied to our example extension gives:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
extension: Basic Help Menu by Emily Short
|
|
|
|
extension: Menus by Emily Short v3
|
|
|
|
extension: Basic Screen Effects by Emily Short v7.140425
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
and applied to our example story gives just:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
projectbundle: Menu Time.inform
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
That's because once Menu Time is built, nothing else is needed to use it.
|
|
|
|
On the other hand, |-build-needs| has the opposite effect. Applied to the
|
|
|
|
extension, we get:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
extension: Basic Help Menu by Emily Short
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
because extensions need no building, so certainly nothing else is needed
|
|
|
|
to build them. But |-build-needs| on our story produces:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
projectbundle: Menu Time.inform
|
|
|
|
extension: Basic Help Menu by Emily Short
|
|
|
|
extension: Menus by Emily Short v3
|
|
|
|
extension: Basic Screen Effects by Emily Short v7.140425
|
|
|
|
kit: BasicInformKit
|
|
|
|
extension: Basic Inform by Graham Nelson v1
|
|
|
|
extension: English Language by Graham Nelson v1
|
|
|
|
kit: CommandParserKit
|
|
|
|
kit: WorldModelKit
|
|
|
|
extension: Standard Rules by Graham Nelson v6
|
|
|
|
extension: Standard Rules by Graham Nelson v6
|
|
|
|
language: English
|
|
|
|
kit: EnglishLanguageKit
|
|
|
|
extension: English Language by Graham Nelson v1
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
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.
|
|
|
|
|
|
|
|
@ 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
|
|
|
|
tbere will be a version 4 which doesn't need it.
|
|
|
|
|
|
|
|
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 materual as being for
|
|
|
|
release only, or for debugging only.
|
|
|
|
|
|
|
|
Inbuild accepts the same command-line options as |inform7| does to specify
|
|
|
|
these: |-debug| for debugging features, |-release| for a release run, and
|
|
|
|
|-format=X| to select a virtual machine. (See the |inform7| documentation.)
|
|
|
|
|
|
|
|
@ Now suppose that the project asks for something impossible, with a line
|
|
|
|
such as:
|
|
|
|
|
|
|
|
>> Include Xylophones by Jimmy Stewart.
|
|
|
|
|
|
|
|
No such extension exists. If we look at the graph, or the |-build-needs| list
|
|
|
|
for the project, we see that it includes:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
missing extension: Xylophones by Jimmy Stewart, any version will do
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
If we had instead written:
|
|
|
|
|
|
|
|
>> Include version 6.2 of Xylophones by Jimmy Stewart.
|
|
|
|
|
|
|
|
we would see:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
missing extension: Xylophones by Jimmy Stewart, need version in range [6.2,7-A)
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
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.
|
|
|
|
|
|
|
|
Inbuild can list missing resources with |-use-missing| and |-build-missing|
|
|
|
|
respectively. At present, it has no means of fetching missing resources from
|
|
|
|
any central repository.
|
|
|
|
|
|
|
|
@h Building.
|
|
|
|
The graph for a copy tells Inbuild not only what is necessary for a build,
|
|
|
|
but also how to perform that build.
|
|
|
|
|
|
|
|
As noted above, not everything needs building. Extensions do not, in particular,
|
|
|
|
so running |-build| on one will do nothing. Kits do need building: what this
|
|
|
|
does is to "assimilate" the Unform 6-notation source files inside the kit into
|
|
|
|
binary files of Inter, one for each possible architecture.
|
|
|
|
|
|
|
|
But building is mostly done with projects. If we run:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -build Example.inform
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
then Inbuild will first build everthing 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 |make|,
|
|
|
|
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
|
2021-11-23 01:40:18 +02:00
|
|
|
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
|
2020-03-26 21:22:26 +02:00
|
|
|
the first time, the second |-build| does nothing.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
As noted above, the |-release| 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 |inblorb|, the releasing tool for Inform.
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -release -build Example.inform
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
Using the |-rebuild| command performs a build in a way which isn't incremental:
|
|
|
|
timestamps of files are ignored and everything is remade from scratch.
|
|
|
|
|
|
|
|
@ It takes a certain trust to just let Inbuild rip, and if you don't feel that
|
|
|
|
trust, adding the |-dry| 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 |-build-trace| is used.
|
|
|
|
These are not commands: they simply modify the behaviour of |-build| and
|
|
|
|
|-rebuild|.
|
|
|
|
|
|
|
|
Inbuild uses a handful of standard Unix shell commands, but it also uses
|
|
|
|
|inform7|, |inform6|, |inblorb| and |inter|. 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 |-tools P| to
|
|
|
|
specify path |P| as the home of the other Intools.
|
|
|
|
|
|
|
|
@h Specifying what to act on.
|
|
|
|
In all of the examples above, Inbuild is given just one copy to act on.
|
|
|
|
(That action may end up invplving 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.
|
|
|
|
|
|
|
|
We can also tell Inbuild to work on everything it finds in a given directory
|
|
|
|
|D| using |-contents-of D|:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect -contents-of inform7/Internal/Inter
|
|
|
|
kit: EnglishLanguageKit at path inform7/Internal/Inter/EnglishLanguageKit
|
|
|
|
kit: CommandParserKit at path inform7/Internal/Inter/CommandParserKit
|
|
|
|
kit: BasicInformExtrasKit at path inform7/Internal/Inter/BasicInformExtrasKit
|
|
|
|
kit: WorldModelKit at path inform7/Internal/Inter/WorldModelKit
|
|
|
|
kit: BasicInformKit at path inform7/Internal/Inter/BasicInformKit
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
For compatibility with the |inform7| command line syntax, we can also specify
|
|
|
|
the project target using |-project|:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -build -project Example.inform
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
But this is quite unnecessary: the effect is the same as if |-project| had
|
|
|
|
been missed out.
|
|
|
|
|
|
|
|
@ Listing filenames or pathnames of copies on the command line, or using the
|
|
|
|
|-contents-of D| switch, is only possible if we know where in the file system
|
|
|
|
these copies are; and sometimes we do not.
|
|
|
|
|
|
|
|
If we instead specify |-matching R|, where |R| is a list of requirements,
|
|
|
|
Inbuild will act on every copy it can find which matches that. For example,
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect -matching 'genre=kit'
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
lists all the kits which Inbuild can see; and
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect -matching 'genre=extension,author=Eric Eve'
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
lists all extensions by Eric Eve which Inbuild can see. The legal clauses to
|
|
|
|
specify are |title|, |author|, |genre| and |version|. Note that |version=5.1.1|
|
|
|
|
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. To specify an explicit maximum
|
|
|
|
and minimum version number, use |max| and |min|. For example:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
-matching 'genre=extension,author=Emily Short,title=Locksmith,min=6.1-alpha.2,max=17.2'
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
@h Nests and searches.
|
|
|
|
When searching with |-matching R|, or indeed when running Inform and needing
|
|
|
|
to find certain resources, Inbuild looks inside what are called "nests".
|
|
|
|
|
|
|
|
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 |inform7/Internal| is a nest:
|
|
|
|
this contains the extensions, kits and so on which are built in to Inform
|
|
|
|
when it's used as an app.
|
|
|
|
|
|
|
|
Inbuild recognises the following subdirectories of a nest as significant:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text)
|
2020-03-26 21:22:26 +02:00
|
|
|
Templates
|
|
|
|
Pipelines
|
|
|
|
Inter
|
|
|
|
Languages
|
|
|
|
Extensions
|
2020-04-08 01:02:44 +03:00
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
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 authpr's name. Thus:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text)
|
|
|
|
Extensions/Emily Short/Locksmith.i7x
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
(In some early releases of Inform 7, it was legal for this file not to have
|
|
|
|
the |.i7x| extension: but now it is compulsory.)
|
|
|
|
|
|
|
|
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 |-vN|, where
|
|
|
|
|N| is semantic version number but with any dots replaced by underscores.
|
|
|
|
Thus, we can have e.g.:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text)
|
|
|
|
Extensions/Emily Short/Locksmith-v3_2.i7x
|
|
|
|
Extensions/Emily Short/Locksmith-v4_0_0-prealpha_13.i7x
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
co-existing side by side. If the user asks to
|
|
|
|
|
|
|
|
>> Include Locksmith by Emily Short.
|
|
|
|
|
|
|
|
then version |4.0.0-prealpha.13| 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
|
|
|
|
|
|
|
|
>> Include version 3 Locksmith by Emily Short.
|
|
|
|
|
|
|
|
then version |3.2| is the winner, as the highest-numbered extension in the
|
|
|
|
nest with the right major version number (3).
|
|
|
|
|
|
|
|
@ 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.
|
|
|
|
|
|
|
|
Inbuild looks for these as follows:
|
|
|
|
(a) |-internal N| tells Inbuild the path |N| for the internal nest; if this
|
|
|
|
is not given, the default is |inform7/Internal|.
|
|
|
|
(b) |-external N| tells Inbuild the path |N| for the external nest; if this
|
|
|
|
is not given, the default depends on the host operating system. For example,
|
|
|
|
on MacOS it will be |~/Library/Inform| (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).
|
|
|
|
(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.
|
|
|
|
|
|
|
|
In addition, extra nests can be specified with |-nest N|.
|
|
|
|
|
|
|
|
@ 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.)
|
|
|
|
|
|
|
|
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:
|
|
|
|
(1) A copy in the Materials nest takes precedence over all others.
|
|
|
|
(2) Otherwise, all other copies take precendence over those in the
|
|
|
|
internal nest.
|
|
|
|
(3) Otherwise, semantic version number rules are used to determine which
|
|
|
|
copy had precedence.
|
|
|
|
|
|
|
|
Suppose the Materials folder for our project contains |Locksmith-v3_2.i7x|,
|
|
|
|
while the external folder contains |Locksmith-v3_3.i7x| and |Locksmith-v4.i7x|.
|
|
|
|
Then the sentence:
|
|
|
|
|
|
|
|
>> Include Locksmith by Emily Short.
|
|
|
|
|
|
|
|
would result in |Locksmith-v3_2.i7x| from Materials being used, even though
|
|
|
|
there's a later version in the external area: Materials always wins. But
|
|
|
|
|
|
|
|
>> Include version 4 of Locksmith by Emily Short.
|
|
|
|
|
|
|
|
would use |Locksmith-v4.i7x| from the external area, because the copy in the
|
|
|
|
Materials folder doesn't qualify.
|
|
|
|
|
|
|
|
@h Copy, sync and archive.
|
|
|
|
Clerical work is generally best done automatically, and Inbuild offers some
|
|
|
|
useful filing commands.
|
|
|
|
|
|
|
|
The command |-copy-to N| makes a duplicate copy in the nest |N|. For example:
|
2020-04-08 01:02:44 +03:00
|
|
|
= (text as ConsoleText)
|
|
|
|
$ inbuild/Tangled/inbuild -inspect junk/Mystery.i7x
|
|
|
|
extension: Complex Listing by Emily Short v9 in directory junk.
|
|
|
|
$ inbuild/Tangled/inbuild -copy-to MyNest junk/Mystery.i7x
|
|
|
|
cp -f 'junk/Mystery.i7x' 'MyNest/Extensions/Emily Short/Complex Listing-v9.i7x'
|
|
|
|
=
|
2020-03-26 21:22:26 +02:00
|
|
|
Note that Inbuild replies to the |-copy-to N| command by executing a shell
|
|
|
|
command to copy what is, in this case, a single file. As when building, the
|
|
|
|
|-dry| option puts Inbuild into dry-run mode, where it prints the commands it
|
|
|
|
would like to execute but doesn't execute them.
|
|
|
|
|
|
|
|
The command |-sync-to N| is similar, but will overwrite any existing copy
|
|
|
|
already in |N|, rather than producing an error if a collision occurs.
|
|
|
|
|
|
|
|
@ The |-archive-to N| command performs |-sync-to N| 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).
|
|
|
|
|
|
|
|
This is really only useful for Inform projects, and the abbreviated form
|
|
|
|
|-archive| performs |-archive-to| 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.
|