DavidKinder/Inform6 — pull request #4 by EmacsUser (2013-02-01 23:00:16+00:00)
Title: Patch to emit debug information files in a new XML format

# Summary

See DebugFileFormat.text for the specification of the debug file format that this patch follows. The original discussion can also be found at http://www.intfiction.org/forum/viewtopic.php?f=7&t=5986&start=10 and http://www.intfiction.org/forum/viewtopic.php?f=7&t=6079.

I took the approach that debug information should be emitted as soon as possible, which records backpatched much like the story file, mostly because that entailed fewer data structures and less data structure manipulation than saving everything until post-compilation. But the other tack is available if there are objections to this one.

# Known problems

* Debug information for linked-in modules isn't emitted. But it wasn't emitted before the patch either.

* I was unable to test with `-Cu`; despite my giving the switch, the compiler complained about illegal characters in my UTF-8 source file, which probably means that I don't know how to use the option. In any case, there is not yet any correction to the emitted character numbers for multibyte characters. A fix will probably involve some borrowing from `text_to_unicode`.

* I tried to limit new system calls to those that were either already in use or long since inaugurated into a cross-platform standard. The one exception is `realpath(...)`, which is invoked once in `files.c`. We will probably need to expand Part 4 of the OS-specific sections in `header.h` to provide equivalents on other platforms. Unfortunately, I'm not sure I know enough to write them.

# Other questions

* Section 7 of the specification now reads

> And finally, <routine> records contain an <address> and a <byte-count> element, along with any number of the <local-variable> and <sequence-point> elements, which are described in Sections 9 and 10. The address is provided because the identifier's value may be packed.

Obvious alternatives to giving both a value and an address would be to emit only the packed addresses and then give the scale factor in another element or else emit the actual addresses and again give the scale factor. Opinions welcome.

* Section 7 also reads:

> Sometimes what would otherwise be a named value is in fact anonymous; unnamed objects, embedded routines, some replaced routines, veneer properties, and the Infix attribute are all examples. In such a case, the <identifier> subelement will carry the XML attribute
>
> > artificial
>
> to indicate that the compiler is providing a sensible name of its own, which could be presented to a human, but is not actually an identifier.

The rules for generating some artificial identifiers were already in place. However, I have added the parentheticals `(replaced)` (see `asm.c`) and `(superseded replacement)` (see `files.c`) to anonymous routines plus `inheritance class` and `instance variables table address (Z-code)` for common properties 2 and 3 (see `objects.c`). We may want them reworded.

* Section 11 reads

> If the compiler doesn't track file positions, they will be omitted. If it doesn't track character numbers either, only line numbers will appear.

This was due to a comment from Zarf:

> On the other end of the stick, the current I6 compiler does not store file positions, only line numbers. (Not even column numbers.) So a first iteration of this might only have the <line> tags. Rather than requiring everything, I would rather take an as-much-information-as-is-available approach.

But with the patch the compiler does track everything, so perhaps we don't want the data to be optional anymore.