1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
4
<title>DM4 §39: Controlling compilation from without</title>
5
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6
<link rel="stylesheet" type="text/css" href="dm4.css">
10
<a href="index.html">home</a> /
11
<a href="contents.html">contents</a> /
12
<a href="ch6.html" title="Chapter VI: Using the Compiler">chapter VI</a> /
13
<a href="s38.html" title="§38: Controlling compilation from within">prev</a> /
14
<a href="s40.html" title="§40: Error messages">next</a> /
15
<a href="dm4index.html">index</a>
18
<a id="p295" name="p295"></a>
19
<h2>§39 Controlling compilation from without</h2>
21
<p class="normal"><span class="atleft"><img src="dm4-295_1.jpg" alt=""></span>
22
The Inform compiler has the equivalent of a dashboard of “command
23
line switches”, controlling its behaviour. Most of these have only
24
two settings, off or on, and most of them are off most of the time.
25
Others can be set to a number between 0 and 9. In this book switches are
26
written preceded by a minus sign, just as they would be typed if you
27
were using Inform from the command line of (say) Unix or RISC OS.
28
Setting <tt>-x</tt>, for instance, causes Inform to print a row of
29
hash signs as it compiles:</p>
31
<p class="output"><tt>inform -x shell<br>
32
RISC OS Inform 6.20 (10th December 1998)<br>
33
::##############################################################<br>
34
#################</tt></p>
36
<p class="normal">One hash sign is printed for every 100 textual lines
37
of source code compiled, so this row represents about eight thousand lines.
38
(During the above compilation, carried out by an Acorn Risc PC 700, hashes
39
were printed at a rate of about thirty per second.) <tt>-x</tt> is
40
provided not so much for information as to indicate that a slow compilation
41
is continuing normally. Contrariwise, the <tt>-s</tt> switch offers
42
more statistics than you could possibly have wanted, as in the following
43
monster compilation (of ‘Curses’):</p>
45
<p class="lynxonly"></p>
46
<pre style="margin-top:1em;margin-bottom;1em">
47
RISC OS Inform 6.20 (10th December 1998)
48
In: 25 source code files 17052 syntactic lines
49
22098 textual lines 860147 characters (ISO 8859-1 Latin1)
51
1925 symbols (maximum 10000) 1022182 bytes of memory
52
Out: Version 8 "Extended" story file 17.981218 (343.5K long):
53
37 classes (maximum 64) 579 objects (maximum 639)
54
169 global vars (maximum 233) 4856 variable/array space (m. 8000)
55
153 verbs (maximum 200) 1363 dictionary entries (m. 2000)
56
318 grammar lines (version 2) 490 grammar tokens (unlimited)
57
167 actions (maximum 200) 34 attributes (maximum 48)
58
51 common props (maximum 62) 153 individual props (unlimited)
59
267892 characters used in text 195144 bytes compressed (rate 0.728)
60
0 abbreviations (maximum 64) 891 routines (unlimited)
61
25074 instructions of Z-code 10371 sequence points
62
52752 bytes readable memory used (maximum 65536)
63
351408 bytes used in Z-machine 172880 bytes free in Z-machine
64
Completed in 8 seconds
67
<a id="p296" name="p296"></a>
68
<p class="normal">The complete list of switches is listed when you
69
run Inform with <tt>-h2</tt>, and also in <a href="tables.html#tbl3">Table 3</a>
70
at the back of this book, where there are notes on some of the odder-looking
73
<p class="indent">When the statistics listing claims that, for instance,
74
the maximum space for arrays is 10,000, this is so because Inform has
75
only allocated enough memory to keep track of 10,000 entries while
76
compiling. This in turn is because Inform's “memory setting”
77
<code>$MAX_STATIC_DATA</code> was set to 10,000 when the compilation
80
<p class="indent">Between them, the “memory settings” control
81
how much of your computer's memory Inform uses while running. Too little
82
and it may not be able to compile games of the size you need, but too
83
much and it may choke any other programs in the computer for space.
84
It's left up to you to adjust the memory settings to suit your own
85
environment, but most people leave them alone until an error message
86
advises a specific increase.</p>
88
<p class="indent">Finally, Inform has “path variables”,
89
which contain filenames for the files Inform uses or creates. Usage
90
of these varies widely from one operating system to another.
91
Run Inform with the <tt>-h1</tt> switch for further information.</p>
93
<p class="dotbreak">� � � � �</p>
95
<p class="normal">Inform's switches, path variables and memory settings
96
are set using “Inform Command Language” or ICL. The usual
97
way to issue ICL commands, at least on installations of Inform which
98
don't have windowed front-ends, is to squeeze them onto the command
99
line. The standard command line syntax is</p>
101
<p class="syntax"><tt>inform</tt>
102
‹<span class="token">ICL commands</span>›
103
‹<span class="token">source file</span>›
104
‹<span class="token">output file</span>›</p>
106
<p class="normal">where only the ‹<span class="token">source file</span>›
107
is mandatory. By default, the full names to give the source and output
108
files are derived in a way suitable for the machine Inform is running
109
on: on a PC, for instance, <tt>advent</tt> may be understood as asking
110
to compile <tt>advent.inf</tt> to <tt>advent.z5</tt>. This is called
111
“filename translation”. No detailed information on filenaming
112
rules is given here, because it varies so much from machine to machine:
113
see the <tt>-h1</tt> on-line documentation. Note that a filename can
114
contain spaces if it is written in double-quotes and if the operating
115
system being used can cope with spaces (as Mac OS can, for instance).</p>
117
<p class="indent">To specify sprawling or peculiar projects may need
118
more ICL commands than can fit comfortably onto the command line.
119
One possible ICL command, however, is to give a filename in (round)
122
<p class="lynxonly"></p>
123
<pre class="code">inform -x (skyfall_setup) ...</pre>
125
<a id="p297" name="p297"></a>
126
<p class="normal">which sets the <tt>-x</tt> switch, then runs through
127
the text file <tt>skyfall_setup</tt> executing each line as an ICL
128
command. This file then look like this:</p>
130
<p class="lynxonly"></p>
132
! Setup file for "Skyfall"
133
-d ! Contract double spaces
134
$max_objects=1000 ! 500 of them snowflakes
135
(usual_setup) ! include my favourite settings, too
136
+module_path=mods ! keep modules in the "mods" directory
139
<p class="normal">ICL can include comments if placed after <code>!</code>,
140
just as in Inform. Otherwise, an ICL file has only one command per line,
141
with no dividing semicolons. Using ICL allows you to compile whole
142
batches of files as required, altering switches, path variables
143
and memory settings as you go. Notice that ICL files can call up other
144
ICL files, as in the example above: don't allow a file to call up another
145
copy of itself, or the compilation will all end in tears.</p>
147
<p class="aside"><span class="warning">▲</span>
148
When typing such a command into a shell under a Unix-like operating systems,
149
you may need to quote the parentheses:</p>
151
<p class="lynxonly"></p>
152
<pre class="code">inform -x '(skyfall_setup)' ...</pre>
154
<p class="aside">This instructs the shell to pass on the command literally
155
to Inform, and not to react to unusual characters like <code>$</code>,
156
<code>?</code>, <code>(</code> or <code>)</code> in it. The same may
157
be needed for other ICL commands such as:</p>
159
<p class="lynxonly"></p>
160
<pre class="code">inform -x '$MAX_OBJECTS=2000' ...</pre>
162
<p class="aside"><span class="warning">▲</span>
163
Windowed front-ends for Inform sometimes work by letting the user select
164
various options and then, when the “Go” button is pressed,
165
convert the state of the dialogue box into an ICL file which is passed
168
<p class="aside"><span class="warning">▲▲</span>
169
If you need to use Inform without benefit of either a command line or
170
a fancy front-end, or if you want your source code to specify its own
171
switch settings, you can still set (most) switches by placing the directive</p>
173
<p class="syntax"><code>Switches</code> ‹<span class="token">some
174
settings</span>›<code>;</code></p>
176
<p class="aside">at the very beginning of your source code. (So that
177
you can still override such settings, the switch <tt>-i</tt> tells
178
Inform to ignore all <code>Switches</code> directives.)</p>
180
<p class="dotbreak">� � � � �</p>
182
<a id="p298" name="p298"></a>
183
<p class="normal">The ICL commands are as follows:</p>
185
<div class="clump"><p class="normal"><code>-</code>‹<span class="token">switches</span>›<br>
186
Set these switches; or unset any switch preceded by a tilde <code>~</code>.
187
(For example, <code>-a~bc</code> sets <code>a</code>, unsets <code>b</code>
188
and sets <code>c</code>.)</p></div>
190
<div class="clump"><p class="normal"><code>$list</code><br>
191
List current memory settings.</p></div>
193
<div class="clump"><p class="normal"><code>$?</code>‹<span class="token">name</span>›<br>
194
Ask for information on what this memory setting is for.</p></div>
196
<div class="clump"><p class="normal"><code>$small</code><br>
197
Set the whole collection of memory settings to suitable levels for a
198
small game.</p></div>
200
<div class="clump"><p class="normal"><code>$large</code><br>
201
Ditto, for a slightly larger game.</p></div>
203
<div class="clump"><p class="normal"><code>$huge</code><br>
204
Ditto, for a reasonably big one.</p></div>
206
<div class="clump"><p class="normal"><code>$</code>‹<span
207
class="token">name</span>›<code>=</code>‹<span
208
class="token">quantity</span>›<br>
209
Alter the named memory setting to the given level.</p></div>
211
<div class="clump"><p class="normal"><code>+</code>‹<span
212
class="token">name</span>›<code>=</code>‹<span
213
class="token">filename</span>›<br>
214
Set the named pathname variable to the given filename, which should be
215
one or more filenames of directories, separated by commas.</p></div>
217
<div class="clump"><p class="normal"><code>compile</code> ‹<span
218
class="token">filename</span>› ‹<span
219
class="token">filename</span>›<br>
220
Compile the first-named file, containing source code, writing the
221
output program to the (optional) second-named file.</p></div>
223
<div class="clump"><p class="normal"><code>(</code>‹<span
224
class="token">filename</span>›<code>)</code><br>
225
Execute this ICL file (files may call each other in this way).</p></div>
227
<p class="dotbreak">� � � � �</p>
229
<p class="normal">It's a nuisance to have to move all the memory settings
230
up or down to cope with a big game or a small computer, so <code>$small</code>,
231
<code>$large</code> and <code>$huge</code> are provided as short cuts.
232
Typically these might allocate 350K, 500K or 610K respectively.
235
<p class="lynxonly"></p>
236
<pre class="code">inform $list</pre>
238
<p class="normal">will list the various settings which can be changed,
239
and their current values. Thus one can compare small and large with:</p>
241
<p class="lynxonly"></p>
247
<a id="p299" name="p299"></a>
248
<p class="normal">If Inform runs out of allocation for something, it
249
will generally print an error message like:</p>
251
<p class="lynxonly"></p>
253
"Game", line 1320: Fatal error: The memory setting MAX_OBJECTS
254
(which is 200 at present) has been exceeded. Try running Inform
255
again with $MAX_OBJECTS=<some-larger-number> on the command line.
258
<p class="normal">and it would then be sensible to try</p>
260
<p class="lynxonly"></p>
261
<pre class="code">inform $MAX_OBJECTS=250 game</pre>
263
<p class="normal">which tells Inform to try again, reserving more memory
264
for objects this time. ICL commands are followed from left to right, so</p>
266
<p class="lynxonly"></p>
267
<pre class="code">inform $small $MAX_ACTIONS=200 ...</pre>
269
<p class="normal">will work, but</p>
271
<p class="lynxonly"></p>
272
<pre class="code">inform $MAX_ACTIONS=200 $small ...</pre>
274
<p class="normal">will not because the <code>$small</code> changes
275
<code>MAX_ACTIONS</code> back again. Changing some settings has
276
hardly any effect on memory usage, whereas others are expensive to
277
increase. To find out about, say, <code>MAX_VERBS</code>, run</p>
279
<p class="lynxonly"></p>
280
<pre class="code">inform $?MAX_VERBS</pre>
282
<p class="normal" style="margin-bottom:1em">(note the question mark) which will print some very
287
<a href="index.html">home</a> /
288
<a href="contents.html">contents</a> /
289
<a href="ch6.html" title="Chapter VI: Using the Compiler">chapter VI</a> /
290
<a href="s38.html" title="§38: Controlling compilation from within">prev</a> /
291
<a href="s40.html" title="§40: Error messages">next</a> /
292
<a href="dm4index.html">index</a>
added
removed
inform-6.31.1/manual/s39.html
