Upcoming changes to command-line arguments (I6)

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

The Reference Addendum doc is now up to date on all of this stuff:


1 Like

why not adding unix-style dash/double dash form also for the rest of the $ option ?

(adding because at least one major shell script (punyinform.sh) use the $ form for a critical switch (OMIT_UNUSED_ROUTINES), whose is the major byte-saver for the Z? format)

Best regards from Italy,
dott. Piergiorgio.

I think you’re looking for