7 .. image:: /images/picA.png
10 |A|\lmost as rarely as an alchemist producing gold from base metal, the
11 compilation process turns your source file into a story file (though the
12 more usual outcome is a reproachful explanation of why -- *again* --
13 that hasn't happened). The magic is performed by the compiler program,
14 which takes your more or less comprehensible code and translates it into
15 a binary file: a collection of numbers following a specific format
16 understood only by Z-code interpreters.
18 On the surface, compilation is a very simple trick. You just run the
19 compiler program, indicating which is the source file from which you
20 wish to generate a game and presto! The magic is done.
22 However, the ingredients for the spell must be carefully prepared. The
23 compiler "reads" your source code, but not as flexibly as a human would.
24 It needs the syntax to follow some very precise rules, or it will
25 complain that it cannot do its job under these conditions. The compiler
26 cares little for meaning, and a lot about orthography, like a most
27 inflexible teacher; no moist Bambi eyes are going to save you here.
29 Although the spell made by the compiler is always the same one, you can
30 indicate up to a point how you want the magic to happen. There are a few
31 options to affect the process of compilation; some you define in the
32 source code, some with *switches* and certain commands when you run
33 the program. The compiler will work with some default options if you
34 don’t define any, but you may change these if you need to. Many of these
35 options are provided "just in case" special conditions apply; others are
36 meant for use of experienced designers with advanced and complex
37 requirements, and are best left (for now) to those proficient in the
43 If the source file is not written correctly the compiler will protest,
44 issuing either a *warning* message or an *error* message. Warnings are
45 there to tell you that there may be a mistake that could affect the
46 behaviour of the game at run-time; that won't stop the compiler from
47 finishing the process and producing a story file. Errors, on the other
48 hand, reflect mistakes that make it impossible for the compiler to
49 output such a file. Of these, *fatal* errors stop compilation
50 immediately, while *non-fatal* errors allow the compiler to continue
51 reading the source file. (As you’ll see in a minute, this is perhaps a
52 mixed blessing: while it can be useful to have the compiler tell you
53 about as many non-fatal errors as it can, you'll often find that many of
54 them are caused by the one simple slip-up.)
56 .. rubric:: Fatal errors
58 It's difficult – but not impossible – to cause a fatal error. If you
60 file name as source file, the compiler won’t even be able to start,
63 :samp:`Couldn't open source file {filename}`
65 If the compiler detects a large number of non-fatal errors, it may
66 abandon the whole process with:
68 :samp:`Too many errors: giving up`
70 Otherwise, fatal errors most commonly occur when the compiler runs out
71 of memory or disk space; with today's computers, that's pretty unusual.
72 However, you may hit problems if the story file, which must fit within
73 the fairly limited resources specified by the Z-machine, becomes too
74 large. Normally, Inform compiles your source code into a Version 5 file
75 (that’s what the ``.z5`` extension you see in the output file
76 indicates), with a maximum size of 256 Kbytes. If your game is larger
77 than this, you’ll have to compile into Version 8 file (``.z8``), which
78 can grow up to 512 Kbytes (and you do this very simply by setting the
79 :option:`-v8` switch; more on that in a minute). It takes a surprising amount
80 of code to exceed these limits; you won’t have to worry about game size
81 for the next few months, if ever.
83 .. rubric:: Non-fatal errors
85 Non-fatal errors are much more common. You'll learn to be friends with:
87 :samp:`Expected {something} but found {something else}`
89 This is the standard way of reporting a punctuation or syntax mistake.
90 If you type a comma instead of a semicolon, Inform will be looking for
91 something in vain. The good news is that you are pointed to the
92 offending line of code::
94 Tell.inf(76): Error: Expected directive, '[' or class name but found found_in
96 Compiled with 1 error (no output)
98 You see the line number (76) and what was found there, so you run to the
99 source file and take a look; any decent editor will display numbers
100 alongside your lines if you wish, and will usually let you jump to a
101 given line number. In this case, the error was caused by a semicolon
102 after the description string, instead of a comma:
104 .. code-block:: inform
106 Prop "assorted stalls"
107 with name 'assorted' 'stalls',
108 description "Food, clothing, mountain gear; the usual stuff.";
109 found_in street below_square,
112 Here's a rather misleading message which maybe suggests that things in
113 our source file are in the wrong order, or that some expected
114 punctuation is missing::
116 Fate.inf(459): Error: Expected name for new object or its textual short name
119 Compiled with 1 error (no output)
121 .. Generated by autoindex
123 pair: door; library attribute
125 In fact, there's nothing wrong with the ordering or punctuation. The
126 problem is actually that we've tried to define a new object with an
127 internal ID of :attr:`door` -- reasonably enough, you might think, since the
128 object *is* a door -- but Inform already knows the word (it's the name
129 of a library attribute). Unfortunately, the error message provides only
130 the vaguest hint that you just need to choose another name: we used
131 ``toilet_door`` instead.
133 Once the compiler is off track and can't find what was expected, it's
134 common for the following lines to be misinterpreted, even if there's
135 nothing wrong with them. Imagine a metronome ticking away in time with a
136 playing record. If the record has a scratch and the stylus jumps, it may
137 seem that the rest of the song is out of sync, when it's merely a bit
138 "displaced" because of that single incident. This also happens with
139 Inform, which at times will give you an enormous list of things Expected
140 but not Found. The rule here is: correct the first mistake on the list
141 and recompile. It may be that the rest of the song was perfect.
143 It would be pointless for us to provide a comprehensive list of errors,
144 because mistakes are numerous and, anyhow, the explanatory text usually
145 indicates what was amiss. You'll get errors if you forget a comma or a
146 semicolon. You'll get errors if your quotes or brackets don't pair up
147 properly. You'll get errors if you use the same name for two things.
148 You'll get errors -- for many reasons. Just read the message, go to the
149 line it mentions (and maybe check those just before and after it as
150 well), and make whatever seems a sensible correction.
154 Warnings are not immediately catastrophic, but you should get rid of them
155 to ensure a good start at finding run-time mistakes (see :doc:`16`). You
156 may declare a variable and then not use it; you may mistake assignment and
157 arithmetic operators (``=`` instead of ``==``); you may forget the comma
158 that separates properties, etc. For all these and many other warnings,
159 Inform has found something which is legal but doubtful.
161 One common incident is to return in the middle of a statement block,
162 before the rest of statements can be reached. This is not always as
163 evident as it looks, for instance in a case like this:
165 .. code-block:: inform
167 if (steel_door has open) {
168 print_ret "The breeze blows out your lit match.";
172 In the above example, the ``print_ret`` statement returns true after the
173 string has been printed, and the ``give match ~light`` line will never
174 happen. Inform detects the fault and warns you. Probably the designer's
177 .. code-block:: inform
179 if (steel_door has open) {
181 print_ret "The breeze blows out your lit match.";
184 Compiling *à la carte*
185 ======================
187 One of the advantages of Inform is its portability between different
188 systems and machines. Specific usage of the compiler varies accordingly,
189 but some features should be in all environments. To obtain precise
190 information about any particular version, run the compiler with the
191 :option:`-h1` switch -- see :ref:`switches`.
193 .. Generated by autoindex
197 Often the compiler is run with the name of your source file as its only
198 parameter. This tells the compiler to "read this file using Strict mode and
199 from it generate a Version 5 story file of the same name". The source file
200 is mostly full of statements which define how the game is to behave at
201 run-time, but will also include compile-time instructions directed at the
202 compiler itself (although such an instruction looks a lot like a
203 :term:`statement`, it's actually quite different in what it does, and is
204 known as a :term:`directive`). We have already seen the ``Include``
207 :samp:`Include "{filename}";`
209 When the compiler reaches a line like this, it looks for
210 :samp:`{filename}` -- another file also containing Inform code -- and
211 processes it as if the statements and directives included in
212 :samp:`{filename}` were in that precise spot where the ``Include``
215 .. image:: /images/includes.png
218 In every Inform game we Include the library files ``Parser``,
219 ``VerbLib`` and ``Grammar``, but we may Include other files. For
220 example, this is the way to incorporate library extensions contributed
221 by other people, as you saw when we incorporated ``pname.h`` into our
226 On some machines, a library file is actually called -- for example --
227 ``Parser.h``, on others just ``Parser``. The compiler automatically
228 deals with such differences; you can *always* type simply ``Include
229 "Parser";`` in your source file.
231 As you grow experienced in Inform, and your games become more complex,
232 you may find that the source file becomes unmanageably large. One useful
233 technique is then to divide it into a number of sections, each stored in
234 a separate file, which you Include into a short master game file. For
237 .. code-block:: inform
239 !============================================================================
240 Constant Story "War and Peace";
242 "^An extended Inform example
243 ^by me and Leo Tolstoy.^";
258 !============================================================================
265 When you run the compiler you can set some optional controls; these are
266 called *switches* because most of them are either on or off (although a
267 few accept a numeric value 0–9). Switches affect compilation in a
268 variety of ways, often just by changing the information displayed by the
269 compiler when it’s running. A typical command line (although this may
270 vary between machines) would be:
272 :samp:`inform {source_file story_file switches}`
274 where "``inform``" is the name of the compiler, the :samp:`{story_file}` is
275 optional (so that you can specify a different name from the
276 :samp:`{source_file}`) and the switches are also optional. Note that
277 switches must be preceded by a hyphen ``-``; if you want to set, for
278 instance, Strict mode, you'd write :option:`-S` , while if you want to
279 deactivate it, you’d write :option:`-~S`. The tilde sign can, as elsewhere,
280 be understood as "not". If you wish to set many switches, just write them
281 one after another separated by spaces and each with its own hyphen, or
282 merge them with one hyphen and no spaces::
284 inform MyGame.inf -S -s -X
286 inform MyGame.inf -Ssx
288 Although there's nothing wrong with this method, it isn't awfully
289 convenient should you need to change the switch settings. A more
290 flexible method is to define the switches at the very start of your
291 source file, again in either format::
297 Normally, all switches are off by default, except Strict mode
298 (:option:`-S`), which is on and checks the code for additional
299 mistakes. It's well worth adding Debug mode (:option:`-D`), thus making the
300 debugging verbs available at run time. This is the ideal setting while
301 coding, but you should turn Debug mode off (just remove the :option:`-D`)
302 when you release your game to the public. This is fortunately very easy to
303 check, since the game banner ends with the letter "D" if the game was
304 compiled in Debug mode:
306 .. code-block:: transcript
309 A simple Inform example
310 by Roger Firth and Sonja Kesserich.
311 Release 3 / Serial number 040804 / Inform v6.30 Library 6/11 SD
313 Switches are case sensitive, so you get different effects from ``-x``
314 and ``-X``. Some of the more useful switches are:
319 Set compiler Strict mode on or off, respectively. Strict mode activates
320 some additional error checking features when it reads your source file.
321 Strict mode is on by default.
326 .. Generated by autoindex
330 Compile to this version of story file. Versions 5 (on by default) and
331 8 are the only ones you should ever care about; they produce,
332 respectively, story files with the extensions .z5 and .z8. Version 5
333 was the Advanced Infocom design, and is the default produced by
334 Inform. This is the version you'll normally be using, which allows
335 file sizes up to 256 Kbytes. If your game grows beyond that size,
336 you'll need to compile to the Version 8 story file, which is very
337 similar to Version 5 but allows a 512 Kbytes file size.
342 Include respectively the debugging verbs and the Infix debugger in the
343 story file (see :doc:`16`).
348 Display help information about the compiler. :option:`-h1` produces
349 innformation about file naming, and :option:`-h2` about the available
355 :option:`-n` displays the number of declared attributes, properties and
356 actions. :option:`-j` lists objects as they are being read and constructed
362 Offer game statistics (or not). This provides a lot of information about
363 your game, including the number of objects, verbs, dictionary entries,
364 memory usage, etc., while at the same time indicating the maximum
365 allowed for each entry. This can be useful to check whether you are
366 nearing the limits of Inform.
370 Record all the text of the game into a temporary file, useful to check
371 all your descriptions and messages by running them through a spelling
374 If you run the compiler with the :option:`-h2` switch, you’ll find that
375 there are many more switches than these, offering mostly advanced or
376 obscure features which we consider to be of little interest to beginners.
377 However, feel free to try whatever switches catch your eye; nothing you try
378 here will affect your source file, which is strictly read-only as far as
379 the compiler is concerned.