DebugFileFormat.txt

   1 Format of Inform 6 Debugging Information Files
   2
   3 Version 1.0
   4
   5 0: Introduction
   6
   7 This is a specification of the Version 1 format for the debugging information
   8 files emitted by the Inform 6 compiler.  It replaces Version 0, which is
   9 documented in Section 12.5 of the Inform Technical Manual.
  10
  11 1: Overview
  12
  13 Debugging information files are written in XML and encoded in UTF-8.  They
  14 therefore begin with the following declaration:
  15
  16         <?xml version="1.0" encoding="UTF-8"?>
  17
  18 Beyond the usual requirements for well-formed XML, the file adheres to the
  19 conventions that all numbers are written in decimal, all strings are
  20 case-sensitive, and all excerpts from binary files are Base64-encoded.
  21
  22 2: The Top Level
  23
  24 The root element is given by the tag <inform-story-file> with three attributes,
  25 the version of the debug file format being used, the name of the program that
  26 produced the file, and that program's version.  For instance,
  27
  28         <inform-story-file version="1.0" content-creator="Inform"
  29                            content-creator-version="6.33">
  30           ...
  31         </inform-story-file>
  32
  33 The elements from Sections 3--8 may appear in the ellipses.
  34
  35 3: Story File Prefix
  36
  37 The story file prefix contains a Base64 encoding of the story file's first bytes
  38 so that a debugging tool can easily check whether the story and the debug
  39 information file are mismatched.  For example, the prefix for a Glulx story
  40 might appear as
  41
  42         <story-file-prefix>
  43           R2x1bAADAQEACqEAAAwsAAAMLAAAAQAAAAAAPAAIo2Jc
  44           6B2XSW5mbwABAAA2LjMyMC4zOAABMTIxMDE1wQAAMA==
  45         </story-file-prefix>
  46
  47 The story file prefix is mandatory, but its length is unspecified.  Version 6.33
  48 of the Inform compiler records 64 bytes, which seems sufficient.
  49
  50 4: Story File Sections
  51
  52 Story file sections partition the story file according to how the data will be
  53 used.  For the Inform 6 compiler, this partitioning is the same as the one that
  54 the `z' flag prints.
  55
  56 A record for a story file section gives a name for that section, its beginning
  57 address (inclusive), and its end address (exclusive):
  58
  59         <story-file-section>
  60           <type>abbreviations table</type>
  61           <address>64</address>
  62           <end-address>128</end-address>
  63         </story-file-section>
  64
  65 The names currently in use include those from Section 12.5 of the Inform
  66 Technical Manual:
  67
  68         abbreviations table
  69         header extension (Z-code only)
  70         alphabets table (Z-code only)
  71         Unicode table (Z-code only)
  72         property defaults
  73         object tree
  74         common properties
  75         class numbers
  76         individual properties (Z-code only)
  77         global variables
  78         array space
  79         grammar table
  80         actions table
  81         parsing routines (Z-code only)
  82         adjectives table (Z-code only)
  83         dictionary
  84         code area
  85         strings area
  86
  87 plus one addition for Z-code:
  88
  89         abbreviations
  90
  91 two additions for Glulx:
  92
  93         memory layout id
  94         string decoding table
  95
  96 and three additions for both targets:
  97
  98         header
  99         identifier names
 100         zero padding
 101
 102 Names may repeat; Glulx story files, for example, sometimes have two zero
 103 padding sections.
 104
 105 A compiler that does not wish to subdivide the story file should emit one
 106 section for the entirety and give it the name
 107
 108         story
 109
 110 5: Source Files
 111
 112 Source files are encoded as in the example below.  Each file has a unique index,
 113 which is used by other elements when referring to source code locations; these
 114 indices count from zero.  The file's path is recorded in two forms, first as it
 115 was given to the compiler via a command-line argument or include directive but
 116 without any path abbreviations like `>' (the form suitable for presentation to a
 117 human) and second after resolution to an absolute path (the form suitable for
 118 loading the file contents).  All paths are written according to the conventions
 119 of the host OS.  The language is, at present, either "Inform 6" or "Inform 7".
 120 More languages may added in the future.
 121
 122         <source index="0">
 123           <given-path>example.inf</given-path>
 124           <resolved-path>/home/user/directory/example.inf</resolved-path>
 125           <language>Inform 6</language>
 126         </source>
 127
 128 If the source file is known to appear in the story's Blorb, its chunk number
 129 will also be recorded:
 130
 131         <source index="0">
 132           <given-path>example.inf</given-path>
 133           <resolved-path>/home/user/directory/example.inf</resolved-path>
 134           <language>Inform 6</language>
 135           <blorb-chunk-number>18</blorb-chunk-number>
 136         </source>
 137
 138 6: Table Entries; Grammar Lines
 139
 140 Table entries are data defined by particular parts of the source code, but
 141 without any corresponding identifiers.  The <table-entry> element notes the
 142 entry's type, the address where it begins (inclusive), the address where it ends
 143 (exclusive), and the defining source code location(s), if any:
 144
 145         <table-entry>
 146           <type>grammar line</type>
 147           <address>1004</address>
 148           <end-address>1030</end-address>
 149           <source-code-location>...</source-code-location>
 150         </table-entry>
 151
 152 Version 6.33 of the Inform compiler only emits <table-entry> tags for grammar
 153 lines; these data are all located in the grammar table section.
 154
 155 7: Named Values; Constants, Attributes, Properties, Actions, Fake Actions,
 156    Objects, Classes, Arrays, and Routines
 157
 158 Records for named values store their identifier, their value, and the source
 159 code location(s) of their definition, if any.  For instance,
 160
 161         <constant>
 162           <identifier>MAX_SCORE</identifier>
 163           <value>40</value>
 164           <source-code-location>...</source-code-location>
 165         </constant>
 166
 167 would represent a named constant.  Attributes, properties, actions, fake
 168 actions, objects, arrays, and routines are also names for numbers, and differ
 169 only in their use; they are represented in the same format under the tags
 170 <attribute>, <property>, <action>, <fake-action>, <object>, <array>, and
 171 <routine>.  (Moreover, unlike Version 0 of the debug information format, fake
 172 actions are not recorded as both fake actions and actions.)
 173
 174 The records for constants include some extra entries for the system constants
 175 tabulated in Section 12.2 of the Inform Technical Manual, even though these are
 176 not created by Constant directives.  Entries for #undefed constants are also
 177 included, but necessarily without values.
 178
 179 Some records for objects will represent class objects.  In that case, they will
 180 be given with the tag <class> rather than <object> and include an additional
 181 child to indicate their class number:
 182
 183         <class>
 184           <identifier>lamp</identifier>
 185           <class-number>5</class-number>
 186           <value>1560</value>
 187           <source-code-location>...</source-code-location>
 188         </class>
 189
 190 Records for arrays also have extra children, which record their size, their
 191 element size, and the intended semantics for their zeroth element:
 192
 193         <array>
 194           <identifier>route</identifier>
 195           <value>1500</value>
 196           <byte-count>20</byte-count>
 197           <bytes-per-element>4</bytes-per-element>
 198           <zeroth-element-holds-length>true</zeroth-element-holds-length>
 199           <source-code-location>...</source-code-location>
 200         </array>
 201
 202 And finally, <routine> records contain an <address> and a <byte-count> element,
 203 along with any number of the <local-variable> and <sequence-point> elements,
 204 which are described in Sections 9 and 10.  The address is provided because the
 205 identifier's value may be packed.
 206
 207 Sometimes what would otherwise be a named value is in fact anonymous; unnamed
 208 objects, embedded routines, some replaced routines, veneer properties, and the
 209 Infix attribute are all examples.  In such a case, the <identifier> subelement
 210 will carry the XML attribute
 211
 212         artificial
 213
 214 to indicate that the compiler is providing a sensible name of its own, which
 215 could be presented to a human, but is not actually an identifier.  For instance:
 216
 217         <routine>
 218           <identifier artificial="true">lantern.time_left</identifier>
 219           <value>1820</value>
 220           <byte-count>80</byte-count>
 221           <source-code-location>...</source-code-location>
 222           ...
 223         </routine>
 224
 225 Artificial identifiers may contain characters, like the full stop in
 226 ``lantern.time_left'', that would not be legal in the source language.
 227
 228 8: Global Variables
 229
 230 Globals are similar to named values, except that they are not interpreted as a
 231 fixed value, but rather have an address where their value can be found.  Their
 232 records therefore contain an <address> tag in place of the <value> tag, as in:
 233
 234         <global-variable>
 235           <identifier>darkness_witnessed</identifier>
 236           <address>1520</address>
 237           <source-code-location>...</source-code-location>
 238         </global-variable>
 239
 240 9: Local Variables
 241
 242 The format for local variables mimics the format for global variables, except
 243 that a source code location is never included, and their memory locations are
 244 not given by address.  For Z-code, locals are specified by index:
 245
 246         <local-variable>
 247           <identifier>parameter</identifier>
 248           <index>1</index>
 249         </local-variable>
 250
 251 whereas for Glulx they are specified by frame offset:
 252
 253         <local-variable>
 254           <identifier>parameter</identifier>
 255           <frame-offset>4</frame-offset>
 256         </local-variable>
 257
 258 If a local variable identifier is only in scope for part of a routine, it's
 259 scope will be encoded as a beginning instruction address (inclusive) and an
 260 ending instruction address (exclusive):
 261
 262         <local-variable>
 263           <identifier>rulebook</identifier>
 264           <index>0</index>
 265           <scope-address>1628</scope-address>
 266           <end-scope-address>1678</end-scope-address>
 267         </local-variable>
 268
 269 Identifiers with noncontiguous scopes are recorded as one <local-variable>
 270 element per contiguous region.  It is possible for the same identifier to map to
 271 different variables, so long as the corresponding scopes are disjoint.
 272
 273 10: Sequence Points
 274
 275 Sequence points are stored as an instruction address and the corresponding
 276 single location in the source code:
 277
 278         <sequence-point>
 279           <address>1628</address>
 280           <source-code-location>...</source-code-location>
 281         </sequence-point>
 282
 283 The source code location will always be exactly one position with overlapping
 284 endpoints.
 285
 286 Sequence points are defined as in Section 12.4 of the Inform Technical Manual,
 287 but with the further stipulation that labels do not influence their source code
 288 locations, as they did in Version 0 of the debug information format.  For
 289 instance, in code like
 290
 291         say__p = 1; ParaContent(); .L_Say59; .LSayX59;
 292         t_0 = 0;
 293
 294 the sequence points are to be placed like this:
 295
 296         <*> say__p = 1; <*> ParaContent(); .L_Say59; .LSayX59;
 297         <*> t_0 = 0;
 298
 299 rather than like this:
 300
 301         <*> say__p = 1; <*> ParaContent(); <*> .L_Say59; .LSayX59;
 302         t_0 = 0;
 303
 304 11: Source Code Locations
 305
 306 Most source code locations take the following format, which describes their
 307 file, the line and character number where they begin (inclusive), the line and
 308 character number where they end (exclusive), and the file positions (in bytes)
 309 corresponding to those endpoints:
 310
 311         <source-code-location>
 312           <file-index>0</file-index>
 313           <line>1024</line>
 314           <character>4</character>
 315           <file-position>44153</file-position>
 316           <end-line>1025</end-line>
 317           <end-character>1</end-character>
 318           <end-file-position>44186</end-file-position>
 319         </source-code-location>
 320
 321 Line numbers and character numbers begin at one, but file positions count from
 322 zero.
 323
 324 In the special case where the endpoints coincide, as happens with sequence
 325 points, the end elements may be elided:
 326
 327         <source-code-location>
 328           <file-index>0</file-index>
 329           <line>1024</line>
 330           <character>4</character>
 331           <file-position>44153</file-position>
 332         </source-code-location>
 333
 334 At the other extreme, sometimes definitions span several source files or appear
 335 in two different languages.  The former case is dealt with by including multiple
 336 code location elements and indexing them to indicate order:
 337
 338         <!-- First Part of Inform 6 Definition -->
 339         <source-code-location index="0">
 340           <!-- Assuming file 0 was given with the language "Inform 6" -->
 341           <file-index>0</file-index>
 342           <line>1024</line>
 343           <character>4</character>
 344           <file-position>44153</file-position>
 345           <end-line>1025</end-line>
 346           <end-character>1</end-character>
 347           <end-file-position>44186</end-file-position>
 348         </source-code-location>
 349         <!-- Second Part of Inform 6 Definition -->
 350         <source-code-location index="1">
 351           <!-- Assuming file 1 was given with the language "Inform 6" -->
 352           <file-index>1</file-index>
 353           <line>1</line>
 354           <character>0</character>
 355           <file-position>0</file-position>
 356           <end-line>3</end-line>
 357           <end-character>1</end-character>
 358           <end-file-position>59</end-file-position>
 359         </source-code-location>
 360
 361 The latter case is also handled with multiple elements.  Note that indexing is
 362 only used to indicated order among locations in the same language.
 363
 364         <!-- Inform 7 Definition -->
 365         <source-code-location>
 366           <!-- Assuming file 2 was given with the language "Inform 7" -->
 367           <file-index>2</file-index>
 368           <line>12</line>
 369           <character>0</character>
 370           <file-position>308</file-position>
 371           <end-line>12</end-line>
 372           <end-character>112</end-character>
 373           <end-file-position>420</end-file-position>
 374         </source-code-location>
 375         <!-- Inform 6 Definition -->
 376         <source-code-location>
 377           <!-- Assuming file 0 was given with the language "Inform 6" -->
 378           <file-index>0</file-index>
 379           <line>1024</line>
 380           <character>4</character>
 381           <file-position>44153</file-position>
 382           <end-line>1025</end-line>
 383           <end-character>1</end-character>
 384           <end-file-position>44186</end-file-position>
 385         </source-code-location>
 386
 387 --
 388 This file is part of Inform.
 389
 390 Inform is free software: you can redistribute it and/or modify it
 391 under the terms of the GNU General Public License as published by the
 392 Free Software Foundation, either version 3 of the License, or (at your
 393 option) any later version.
 394
 395 Inform is distributed in the hope that it will be useful, but WITHOUT
 396 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 397 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 398 for more details.
 399
 400 You should have received a copy of the GNU General Public License
 401 along with Inform. If not, see https://gnu.org/licenses/