Too Long
Shocking reveals aplenty as I confess to the many lies and omissions above!
When things changed
In 6L02, -format
was -extension
, -project
was -package
, -internal
was -rules
, and -external
was -extensions
, so if you see any references to those they were for 6L02 or earlier.
Despite the level of detail of Inform’s change logs, 6L38’s doesn’t mention any of this.
Settings.plist, lack thereof
Maybe you’ve noticed I haven’t mentioned Settings.plist, a file the IDEs create in every project directory, even cheesy Perl. And that’s because none of ni, inform6, or cBlorb acknowledge it. Settings.plist is by and for the IDEs to store settings about how they should run these tools.
external and census
You don’t need to specify an -external directory. But on every invocation of ni, it takes a census of available extensions and writes about it to the external directory’s Documentation and Telemetry directories (creating them as necessary). So if you don’t have a $HOME/Inform directory and run ni without specifying -external, it will:
- create “$HOME/Inform” for you because it needs someplace to write its extension census data
- look for extensions and not find any beyond the Internal ones
- create Documentation and Telemetry directories to report
It’s going to write all that somewhere; if you don’t want it writing to “$HOME/Inform”, you have to give it something. But saying -external "$HOME/Inform"
is redundant since it’s the default. For IDE compatibility, you’re best off accepting the default.
(Despite the redundancy, I’ve included it throughout because I think it’d do more harm than good to promote the idea that -external
is optional. Someone who copy-pasted an example with just -project
and -internal
who was struggling with why things are failing wouldn’t have a lot to work with. I’m hoping -external
would give them a chance.)
It’s possible to steer where ni looks for the external directory without explicitly specifying -external
by changing $HOME, but that’s both less flexible and less clear.
There’s one case in which you can run ni without specifying a -project
: if you specify -census
. This goes through the process above; the intent is that IDEs do it after a user installs or uninstalls extensions via the IDE. For a build script, doing it explicitly after pulling the whole Friends of I7 Extensions repo would make some sense. But since ni also checks for changes to the census on every run, there’s not a lot of point to command-line users running it manually.
project directory naming
It doesn’t have to end in .inform. Surprise!
If it doesn’t, ni will create a Release directory under your project directory instead of creating an exact analog of the materials directory. And it’ll look for extensions in an Extensions directory under the project directory instead of in my-game.materials/Extensions. When Release.blurb is generated, this is taken into account so cBlorb’ll be just fine with it too. This only works for the non-.inform-named case: Release and Extensions directories under your project directory are ignored otherwise.
But the IDE simply won’t recognize a project directory whose name doesn’t end with .inform. You wouldn’t be able to open it. If you go back and forth between the command-line and the IDE, stick to its scheme. In fact, if you want to ever use the IDE with a project, stick to creating the project in the IDE or it’ll get cranky about the lack of a Settings.plist.
By default the IDE offers to put your project directories under the same directory it made to be your external directory, but there’s no essential relationship. This works (so long as you have relevant write permissions on /opt):
ni -noprogress -internal /usr/local/share/inform7/Internal -external /tmp -project /opt/my-game.inform
uuid.txt
Nothing breaks if you don’t have a uuid.txt. cBlorb will report an error, but it’ll build a blorb anyway. VERSION in your game would result in ‘Identification number: ////’.
But do you want the casualties of the conflict that the Treaty of Babel finally ended to have died in vain? Do you want IFDB’s archivists to declare a vendetta? (They never forget.) Don’t omit uuid.txt.
For anything you’re letting out the door. If in private during development you keep deleting them and churn through dozens, or go without some of the time? Eh.
But seriously, by the time you have testers, have one and stick to it.
noindex
If you don’t care about creating the Index, you can add the -noindex
flag. This will save a lot of disk space for large games. You’ll still get Index/headings.xml and an empty Index/Details dir as with the failed compile case, but that’s around 350K. Even a minimal game gets a 3.4M Index. Counterfeit Monkey’s Index takes 29M. In my wholly unscientific comparison of two data points, -noindex on CM also saved 3 seconds of time. That sounds like a lot until you consider that it was the difference between 31 and 34 seconds.
The Index isn’t particularly usable outside the IDE… without a bunch of munging I won’t try to describe now. So you might opt to skip making it while you’re working on the command-line. My guess is that the IDE might get confused if the source and index are out of sync because you’ve been building your project with -noindex
outside of the IDE – if nothing else, the Index’s links to specific lines of your story would be wrong. But all that should be cleared up on the next compile without -noindex
.
backup & cleanup
By default, a lot of stuff is left lying around your project directory. Provided you haven’t added other stuff manually, then so far as I know, story.ni, uuid.txt, and everything under the materials directory (with the exception of any generated .eps files) are the only things you need to keep. You could literally delete the Build and Index directories and they and everything in them would just be reproduced next time you compile. But this is at your own risk: if for some weird reason you can’t reproduce the build environment or you don’t have a working set of extensions on hand for the project, you could lose your only run-able copy of the game.
I mentioned above that on failed compilation ni left a 0-length Build/auto.inf file. This happens whether or not there was already an auto.inf there; it simply clobbers any existing one. So in the normal course of things, you would find out that you can no longer create a working auto.inf at the same time you lose your only copy. But hey, at least you’d still have output.ulx.
format
You can still specify -format=z5
or -format=z6
and ni will run just fine. But on even the minimal 1-room game inform6 will then choke if you try to compile the resultant auto.inf to a z5 or z6 game. (Maybe you could get something to work by twiddling constants, but I’m drawing a line on how much experimentation I do for this post.)
(Also, you don’t have to specify a format to run inform6. But without one, it defaults to v5 which isn’t much help to Inform 7 users.)
randomness
ni has an -rng
switch that turns pseudo-randomness into actual-determinism for testing purposes. Basically the same behavior as including the Inform 7 phrase “Seed the random-number generator with 12” (or any other integer greater than zero). Well, same behavior as in pseudo-randomness turns to determinism. Different actual results. Unless you strike on the same seed -rng
uses. I assume this is what you get when you turn off randomness in the IDE.
scoring
In 6L02, Inform 7 switched to ‘use no scoring’ by default. ni’s -scoring
command-line switch makes the default ‘use scoring’ again. But it’s just the default; ‘use no scoring’ in the source will trump it, like you’d expect.
The Debugging Log
Your reward for making it all the way to the bottom is something actually kinda useful. Way up top I made a passing reference to “Build/Debug Log.txt”. It includes the parameters with which ni was invoked.
Inform called as: /usr/libexec/gnome-inform7/ni -internal /usr/share/gnome-inform7 -format=ulx -project /home/user/Inform/my-game.inform
This may not sound like much now, but I’m guessing that’s how 6L02 users saw how the IDEs were doing it and knew how to change from -rules
and -package
. And if the next release of Inform massively invalidates the contents of this post, that’ll be the first place to look.
And at the bottom, it gives you instructions on how to customize it!
Its contents were as follows, and can be changed by placing
text like 'Include property creations in the debugging log.'
or 'Omit everything from the debugging log.' in the source.
Included:
debugging log contents debugging log inclusions
Omitted:
action creations action pattern compilation action pattern parsing assemblies assertions case insensitive filehandling
conditions constructed past participles constructed plurals description compilation excerpt meanings excerpt parsing
[many more elided...]
You can get a more readable form of the options by adding -log=list
to a ni invocation. It has to be a legit use of ni with the usual requirements, e.g.,
ni -noprogress -internal /usr/local/share/inform7/Internal -external "$HOME/Inform" -project "$HOME/Inform/my-game.inform" -log=list
If you don’t have a convenient project lying around, this could be another case for -census
. Anyway, the log aspects are
- action-creations
- action-pattern-compilation
- action-pattern-parsing
- assemblies
- assertions
- case-insensitive-filehandling
- conditions
- constructed-past-participles
- constructed-plurals
- debugging-log-contents
- debugging-log-inclusions
- description-compilation
- excerpt-meanings
- excerpt-parsing
- expressions
- extensions-census
- figure-creations
- grammar
- grammar-construction
- headings
- implications
- inferences
- kind-changes
- kind-checking
- kind-creations
- lexical-output
- local-variables
- matching
- meaning-list-allocation
- memory-allocation
- noun-resolution
- object-compilation
- object-creations
- object-tree
- phrase-comparisons
- phrase-compilation
- phrase-creations
- phrase-registration
- phrase-usage
- predicate-calculus
- predicate-calculus-workings
- pronouns
- property-creations
- property-provision
- property-translations
- relation-definitions
- rule-attachments
- rulebook-compilation
- spatial-map
- spatial-map-workings
- specification-permissions
- specification-usage
- specificities
- table-construction
- template-reading
- text-substitutions
- time-periods
- variable-creations
- verifications
- vocabulary
So Inform 7 offers a ludicrous amount of detail about what it’s doing during compilation if you know how to ask for it. I won’t try to describe them. Some of them are obvious… and I couldn’t tell you what the ones that aren’t obvious are. You can turn them on on the command line:
ni -noprogress -internal /usr/local/share/inform7/Internal -external "$HOME/Inform" -project "$HOME/Inform/my-game.inform" -log=pronouns -log=constructed-plurals
Two things are on by default, debugging-log-contents and debugging-log-inclusions. I don’t know whether it’s possible to turn them off by command-line switch. You can in your Inform 7 source.
Omit debugging-log-inclusions from the debugging log.
Or you can turn things on:
Include pronouns and constructed-plurals in the debugging log.
It’s even possible to say
Include everything in the debugging log.
But that’s 46M of detail for the minimal case.
The debugging log itself appears to be the only source of documentation on the debugging log. (The change log makes a couple of passing references to its existence.)
and the rest
I’m going to go out on a limb and guess that -gdb
and -gdball
are relevant to debugging ni itself and not relevant to anyone not developing ni.
The -clock
switch arrived in 6L02. -sigils
goes way back. They don’t take parameters. -transient
arrived with 6L38 and -case
with 6M62. They do require a parameter.
There are still mysteries in this world.