Provisional documentation on how to make and build new kits.


§1. Historical note. 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 printf. In builds from 2016 and earlier, this standard low-level code was provided as a set of "template files" with filenames like Mathematics.i6t, 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 Mathematics.i6t would be spliced in, and the result would, of course, be an I6 program.

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.)

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.

§2. Exactly how kit dependencies are worked out. 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:

BasicInformKit + Architecture32Kit + EnglishLanguageKit + WorldModelKit + CommandParserKit

That's for a 32-bit target, such as when Inform projects are compiled for Glulx: the alternative is to swap Architecture16Kit for Architecture32Kit.

However, if the "Basic Inform" checkbox is ticked on the Settings panel for the project, the kits will instead be:

BasicInformKit + Architecture32Kit + EnglishLanguageKit

And these are also the defaults when Inform projects are compiled from the command line, with the optional -basic switch forcing us into the second case. As a first step, then, let us see why these are the defaults.

§3. BasicInformKit is absolutely obligatory. No Inform project can ever compile without it: it contains essential functions such as BlkValueCreate or IntegerDivide. Inbuild therefore makes every Inform project have BasicInformKit as a dependency.

Inbuild also makes each project dependent on the language kit for whatever language bundle it is using. So if French is the language of play, the default configurations become:

BasicInformKit + Architecture32Kit + FrenchLanguageKit + WorldModelKit + CommandParserKit
BasicInformKit + Architecture32Kit + FrenchLanguageKit

Projects can specify their own unusual choices of kits using a project_metadata.json file: see A Guide to Project Metadata for more on this. But assuming they don't do this, Inbuild will always go for one of these defaults. By default it assumes it is making an interactive fiction of some kind and therefore goes for the non-Basic default, unless explicitly told not to — by using -basic on the command line, or by checking the "Basic Inform" checkbox in the apps.

§4. 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 kit_metadata.json describing its needs. The metadata for CommandParserKit includes:

    {
        "need": {
            "type": "kit",
            "title": "WorldModelKit"
        }
    }

Never mind the JSON syntax (all that punctuation) for now: what this is saying is that CommandParserKit always needs WorldModelKit in order to function. This means that any project depending on CommandParserKit automatically depends on WorldModelKit too.

For example, this can be used to say "unless we have kit MarthaKit, include GeorgeKit":

    {
        "unless": {
            "type": "kit",
            "title": "MarthaKit"
        },
        "need": {
            "type": "kit",
            "title": "GeorgeKit"
        }
    }

Inbuild acts on this by checking to see if MarthaKit is not present, and in that case GeorgeKit is automatically added instead. (Positive conditions can also be made, with "if" instead of "unless".)

§5. Kits can also use their metadata to specify that associated extensions should automatically be loaded into the project.1 For example, the kit_metadata.json for BasicInformKit includes the lines:

    {
        "need": {
            "type": "extension",
            "title": "Basic Inform",
            "author": "Graham Nelson"
        }
    }

...and similarly for another extension called English Language.

§6. 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 -build-needs option shows what is needed to build this project:

    $ inbuild/Tangled/inbuild -project 'French Laundry.inform' -build-needs
    projectbundle: French Laundry.inform
      kit: BasicInformKit
        extension: Basic Inform by Graham Nelson v1
        extension: English Language by Graham Nelson v1
      kit: Architecture32Kit
      kit: CommandParserKit
        extension: Standard Rules by Graham Nelson v6
        kit: WorldModelKit
          extension: Standard Rules by Graham Nelson v6
      language: English
        kit: EnglishLanguageKit
          extension: English Language by Graham Nelson v1

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.

As this shows, the same kit or extension may be needed for multiple reasons. But it is only included once, of course.

§7. Using project metadata (see A Guide to Project Metadata) alternative or additional kits can be required. Note that if this is done then CommandParserKit and (in consequence) WorldModelKit are no longer auto-included.

For example, if BalloonKit is specified, then we will end up with:

BasicInformKit + Architecture32Kit + EnglishLanguageKit + BalloonKit

But if CommandParserKit and BalloonKit are both specified, then:

BasicInformKit + Architecture32Kit + EnglishLanguageKit + WorldModelKit + CommandParserKit + BalloonKit

If so, then when we next look at the build requirements for the project, we see:

    $ inbuild/Tangled/inbuild -project 'French Laundry.inform' -build-needs
    projectbundle: French Laundry.inform
      kit: BasicInformKit
        extension: Basic Inform by Graham Nelson v1
        extension: English Language by Graham Nelson v1
      kit: Architecture32Kit
      kit: CommandParserKit
        extension: Standard Rules by Graham Nelson v6
        kit: WorldModelKit
          extension: Standard Rules by Graham Nelson v6
      kit: BalloonKit
      language: English
        kit: EnglishLanguageKit
          extension: English Language by Graham Nelson v1

So now BalloonKit is indeed a dependency.

§8. 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 BalloonKit. This directory contains:

§9. The source code is written in Inform 6 syntax.2 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.

For BalloonKit, the contents page BalloonKit/Contents.w will be:

Title: BalloonKit
Author: Joseph-Michel Montgolfier
Purpose: Inter-level support for inflating rubber-lined pockets of air.

Sections
    Inflation

So there will be just one section, BalloonKit/Sections/Inflation.w, which will read:

    Inflation.

    Vital Inter-level support for those balloons.

    @h Inflation function.

    =
    Constant MAX_SAFE_INFLATION_PUFFS 5;

    [ InflateBalloon N i;
        if (N > MAX_SAFE_INFLATION_PUFFS) N = MAX_SAFE_INFLATION_PUFFS;
        for (i=0: i<N: i++) {
            print "Huff... ";
        }
        print "It's inflated!^";
    ];

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.3

§10. The metadata file at BalloonKit/kit_metadata.json is required to exist in order for Inbuild to recognise this as being a kit at all; even if it doesn't say very much, as in this example. This is (almost) minimal:

{
    "is": {
        "type": "kit",
        "title": "BalloonKit",
        "author": "Jacques-Étienne Montgolfier"
        "version": "3.2.7"
    }
}

This is a JSON-format file: JSON, standing for Javascript Object Notation, is now nothing really to do with the language Javascript and has instead become an Internet standard for small packets of descriptive data, like ours. Many full descriptions of JSON are available, but here are some brief notes:

§11. Looking again at the minimal example, what do we have?

{
    "is": {
        "type": "kit",
        "title": "BalloonKit",
        "author": "Jacques-Étienne Montgolfier"
        "version": "3.2.7"
    }
}

The metadata is one big object. That object has a single named value, "is".

The value of "is" is another object — hence the second pair of { ... } after the colon. This second object gives the identity of the kit — says what it is, in other words. That has four values:

§12. To make for a more interesting demonstration, now suppose that the kit wants to require the use of an associated extension. We extend the metadata file to:

{
    "is": {
        "type": "kit",
        "title": "BalloonKit",
        "author": "Jacques-Étienne Montgolfier"
        "version": "3.2.7"
    },
    "needs": [
        {
            "need": {
                "type": "extension",
                "title": "Party Balloons",
                "author": "Joseph-Michel Montgolfier"
            }
        }
    ]
}

Now our metadata object has a second named value, "needs". This has to be a list, which in JSON is written in square brackets [ X, Y, Z, ... ]. Here the list has just one entry, in fact. The entries in the list all have to be objects, which can have three possible values:

The "if" and "unless" clauses are optional. (And only one can be given.) The "need" clause is compulsory. This can say that the kit needs another kit (there are examples above), but in this case it says the kit needs a particular extension to be present.

We can see an effect at once:

    $ inbuild/Tangled/inbuild -project 'French Laundry.inform' -build-needs
    projectbundle: French Laundry.inform
      ...
      kit: BalloonKit
        missing extension: Party Balloons by Joseph-Michel Montgolfier, any version will do
      ...

This will, in fact, now fail to build, because Inform needs an extension which it has not got. So suppose we provide one:

Version 2 of Party Balloons by Joseph-Michel Montgolfier begins here.

To perform an inflation with (N - a number) puff/puffs: (- InflateBalloon({N}); -).

Party Balloons ends here.

and place this file at:

French Laundry.materials/Extensions/Joseph-Michel Montgolfier/Party Balloons.i7x

To make use of this, we'll change the French Laundry source text to:

The French Laundry is a room. "This fancy Sonoma restaurant has, for some reason,
become a haunt of the pioneers of aeronautics."

When play begins:
    perform an inflation with 3 puffs.

Note that this text does not explicitly say "Include Party Balloons by Joseph-Michel Montgolfier" — it doesn't need to: the extension is automatically included by the kit.

And now Inbuild is happier:

    $ inbuild/Tangled/inbuild -project 'French Laundry.inform' -build-needs
    projectbundle: French Laundry.inform
      ...
      kit: BalloonKit
        extension: Party Balloons by Joseph-Michel Montgolfier v2
      ...

§13. 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:

    $ inbuild/Tangled/inbuild -build 'French Laundry.materials/Inter/BalloonKit'

This then issues a series of commands to the inter tool, which actually performs the work, compiling the kit for each architecture in turn. (These commands are echoed to the console, so you can see exactly what is done, and indeed you could always build the kit by hand using inter and not Inbuild.)

In fact, though, Inbuild can also make its own mind up about when a kit needs to be compiled. Rather than build the kit, we can build the story:

    $ inbuild/Tangled/inbuild -project French\ Laundry.inform -build

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.

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.

§14. Other ingredients of the kit metadata file. As noted above, kit_metadata.json must be a valid JSON file which encodes a single object. The following are the legal member names; only "is" is mandatory, and the rest sensibly default if not given.

    "compatibility": "for 16-bit with debugging only"
    "compatibility": "not for 32-bit"
    "compatibility": "for Inform6 version 8"
    "compatibility": "not for C"
    "activates": [ "interactive fiction", "multimedia" ]

§15. The "kit-details" object can contain the following, all of which are optional. Only the first is likely to be useful for a kit other than one of those built in to the Inform installation.

"provides-kinds": [ "Actions.neptune", "Times.neptune", "Scenes.neptune", "Figures.neptune", "Sounds.neptune" ]
    "inserts-source-text": "Use maximum inflation level of 20."

§16. Here are a few footnotes on how Inbuild resolves the "needs" requirements of multiple kits, which may clarify what happens in apparently ambiguous situations.

§17. Future directions. 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.

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.