For the next release of Inform 6, which will be 6.40, I’m doing some cleanup work on the command-line arguments. This is a big change – sort of – because it completely redoes how the compiler handles trace options. But these trace options are used by almost nobody. (This is the alphabet soup which you see when you type inform -h2.) So you don’t really have to read this post, but I’m posting it anyway.
We don’t have a planned release for 6.40, but you can get the current source code from https://github.com/DavidKinder/Inform6 as usual.
New trace options
Here’s the deal: instead of a poorly-documented set of single-letter switches (-l, -m, -g), we will have a set of named trace options. So, instead of the -m switch, you write --trace MEM. The full list of trace options is appended below.
(As with other Inform options, there’s a “classic” form $!MEM and a “Unix-style” form --trace mem. I’m just going to use the dash format in this post. However, if you want to stick one of these options in a source header comment, you have to use the dollar format: !% $!MEM.)
Many trace options have a “more verbose” form, which you can get by setting a higher number. For example, --trace ASM shows the assembly opcodes for every statement; --trace ASM=2 also shows the hex code for those assembly opcodes.
The point is that in the future, it will be easier to add new trace options, or new verbosity levels.
A few of these options still have single-letter synonyms: -s, -z, -a, -g, and -f. (For STATS, MAP, ASM, RUNTIME, and FREQ respectively.) These are the most commonly-used options so it’s worth continuing to support the short forms. In particular, the I7 compiler uses -s; it would be real bad to remove that.
The Trace directive
The Trace directive has always been awkward. It supports a few trace options, but not nearly all of them, and its syntax was pretty ad-hoc. But it offered a couple of trace options which weren’t available through the command line. It also lets you change a couple of trace levels in mid-compile.
In the new world, the Trace directive is pretty well deprecated. Most everything it does has been migrated to the new trace options. (For example, you can display the game’s grammar table with --trace VERBS, or the game’s dictionary with --trace DICT.)
The Trace directive still exists, but I haven’t tried to add new functionality to it. Its syntax is a bit more consistent though. It’s still slightly useful for the “change trace level in mid-compile” thing, but that’s never been a very important feature.
Removal of temp-file and module features
While I’m on the subject of command-line options: I just deleted the -F1 option, which uses temporary files for workspace while compiling. This is irrelevant on any machine less than twenty years old, and even the older ones didn’t use it much. The module options (-M, -U) are next on the chopping block.
All the trace options
To see this list, type inform --helptrace. The option names are case-insensitive. The compiler accepts some obvious synonyms: --trace OBJ, --trace OBJS and --trace OBJECTS all work, for example.
ACTIONS: show actions defined
ASM: trace assembly (same as -a)
ASM=2: also show hex dumps
ASM=3: also show branch optimization info
ASM=4: more verbose branch info
BPATCH: show backpatch results
BPATCH=2: also show markers added
DICT: display the dictionary table
DICT=2: also the byte encoding of entries
EXPR: show expression trees
EXPR=2: more verbose
EXPR=3: even more verbose
FILES: show files opened
FINDABBREVS: show selection decisions during abbreviation optimization
(only meaningful with -u)
FINDABBREVS=2: also show three-letter-block decisions
FREQ: show how efficient abbreviations were (same as -f)
(only meaningful with -e)
LINKER: show module linking info
LINKER=2: more verbose (or 3, 4 for even more)
MAP: print memory map of the virtual machine (same as -z)
MAP=2: also show percentage of VM that each segment occupies
MEM: show internal memory allocations
OBJECTS: display the object table
PROPS: show attributes and properties defined
RUNTIME: show game function calls at runtime (same as -g)
RUNTIME=2: also show library calls (not supported in Glulx)
RUNTIME=3: also show veneer calls (not supported in Glulx)
STATS: give compilation statistics (same as -s)
SYMBOLS: display the symbol table
SYMBOLS=2: also show compiler-defined symbols
SYMDEF: show when symbols are noticed and defined
TOKENS: show token lexing
TOKENS=2: also show token types
TOKENS=3: also show lexical context
VERBS: display the verb grammar table