1 Format of Inform 6 Debugging Information Files
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.
13 Debugging information files are written in XML and encoded in UTF-8. They
14 therefore begin with the following declaration:
16 <?xml version="1.0" encoding="UTF-8"?>
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.
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,
28 <inform-story-file version="1.0" content-creator="Inform"
29 content-creator-version="6.33">
33 The elements from Sections 3--8 may appear in the ellipses.
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
43 R2x1bAADAQEACqEAAAwsAAAMLAAAAQAAAAAAPAAIo2Jc
44 6B2XSW5mbwABAAA2LjMyMC4zOAABMTIxMDE1wQAAMA==
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.
50 4: Story File Sections
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
56 A record for a story file section gives a name for that section, its beginning
57 address (inclusive), and its end address (exclusive):
60 <type>abbreviations table</type>
62 <end-address>128</end-address>
65 The names currently in use include those from Section 12.5 of the Inform
69 header extension (Z-code only)
70 alphabets table (Z-code only)
71 Unicode table (Z-code only)
76 individual properties (Z-code only)
81 parsing routines (Z-code only)
82 adjectives table (Z-code only)
87 plus one addition for Z-code:
91 two additions for Glulx:
96 and three additions for both targets:
102 Names may repeat; Glulx story files, for example, sometimes have two zero
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
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.
123 <given-path>example.inf</given-path>
124 <resolved-path>/home/user/directory/example.inf</resolved-path>
125 <language>Inform 6</language>
128 If the source file is known to appear in the story's Blorb, its chunk number
129 will also be recorded:
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>
138 6: Table Entries; Grammar Lines
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:
146 <type>grammar line</type>
147 <address>1004</address>
148 <end-address>1030</end-address>
149 <source-code-location>...</source-code-location>
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.
155 7: Named Values; Constants, Attributes, Properties, Actions, Fake Actions,
156 Objects, Classes, Arrays, and Routines
158 Records for named values store their identifier, their value, and the source
159 code location(s) of their definition, if any. For instance,
162 <identifier>MAX_SCORE</identifier>
164 <source-code-location>...</source-code-location>
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.)
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.
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:
184 <identifier>lamp</identifier>
185 <class-number>5</class-number>
187 <source-code-location>...</source-code-location>
190 Records for arrays also have extra children, which record their size, their
191 element size, and the intended semantics for their zeroth element:
194 <identifier>route</identifier>
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>
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.
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
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:
218 <identifier artificial="true">lantern.time_left</identifier>
220 <byte-count>80</byte-count>
221 <source-code-location>...</source-code-location>
225 Artificial identifiers may contain characters, like the full stop in
226 ``lantern.time_left'', that would not be legal in the source language.
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:
235 <identifier>darkness_witnessed</identifier>
236 <address>1520</address>
237 <source-code-location>...</source-code-location>
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:
247 <identifier>parameter</identifier>
251 whereas for Glulx they are specified by frame offset:
254 <identifier>parameter</identifier>
255 <frame-offset>4</frame-offset>
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):
263 <identifier>rulebook</identifier>
265 <scope-address>1628</scope-address>
266 <end-scope-address>1678</end-scope-address>
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.
275 Sequence points are stored as an instruction address and the corresponding
276 single location in the source code:
279 <address>1628</address>
280 <source-code-location>...</source-code-location>
283 The source code location will always be exactly one position with overlapping
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
291 say__p = 1; ParaContent(); .L_Say59; .LSayX59;
294 the sequence points are to be placed like this:
296 <*> say__p = 1; <*> ParaContent(); .L_Say59; .LSayX59;
299 rather than like this:
301 <*> say__p = 1; <*> ParaContent(); <*> .L_Say59; .LSayX59;
304 11: Source Code Locations
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:
311 <source-code-location>
312 <file-index>0</file-index>
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>
321 Line numbers and character numbers begin at one, but file positions count from
324 In the special case where the endpoints coincide, as happens with sequence
325 points, the end elements may be elided:
327 <source-code-location>
328 <file-index>0</file-index>
330 <character>4</character>
331 <file-position>44153</file-position>
332 </source-code-location>
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:
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>
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>
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>
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.
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>
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>
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>
388 This file is part of Inform.
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.
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
400 You should have received a copy of the GNU General Public License
401 along with Inform. If not, see https://gnu.org/licenses/