.. image:: /images/picA.png
:align: left
-.. raw:: latex
-
- \dropcap{a}
-
-lmost as rarely as an alchemist producing gold from base metal, the
+|A|\lmost as rarely as an alchemist producing gold from base metal, the
compilation process turns your source file into a story file (though the
more usual outcome is a reproachful explanation of why -- *again* --
that hasn't happened). The magic is performed by the compiler program,
Although the spell made by the compiler is always the same one, you can
indicate up to a point how you want the magic to happen. There are a few
options to affect the process of compilation; some you define in the
-source code, some with ``switches`` and certain commands when you run
+source code, some with *switches* and certain commands when you run
the program. The compiler will work with some default options if you
don’t define any, but you may change these if you need to. Many of these
options are provided "just in case" special conditions apply; others are
indicates), with a maximum size of 256 Kbytes. If your game is larger
than this, you’ll have to compile into Version 8 file (``.z8``), which
can grow up to 512 Kbytes (and you do this very simply by setting the
-``-v8`` switch; more on that in a minute). It takes a surprising amount
+:option:`-v8` switch; more on that in a minute). It takes a surprising amount
of code to exceed these limits; you won’t have to worry about game size
for the next few months, if ever.
-
.. rubric:: Non-fatal errors
Non-fatal errors are much more common. You'll learn to be friends with:
This is the standard way of reporting a punctuation or syntax mistake.
If you type a comma instead of a semicolon, Inform will be looking for
something in vain. The good news is that you are pointed to the
-offending line of code:
-
-.. code-block:: transcript
+offending line of code::
Tell.inf(76): Error: Expected directive, '[' or class name but found found_in
> found_in
Here's a rather misleading message which maybe suggests that things in
our source file are in the wrong order, or that some expected
-punctuation is missing:
-
-.. code-block:: transcript
+punctuation is missing::
Fate.inf(459): Error: Expected name for new object or its textual short name
but found door
> Object door
Compiled with 1 error (no output)
+.. Generated by autoindex
+.. index::
+ pair: door; library attribute
+
In fact, there's nothing wrong with the ordering or punctuation. The
problem is actually that we've tried to define a new object with an
-internal ID of ``door`` -- reasonably enough, you might think, since the
+internal ID of :attr:`door` -- reasonably enough, you might think, since the
object *is* a door -- but Inform already knows the word (it's the name
of a library attribute). Unfortunately, the error message provides only
the vaguest hint that you just need to choose another name: we used
.. rubric:: Warnings
-Warnings are not immediately catastrophic, but you should get rid of
-them to ensure a good start at finding run-time mistakes (see "Debugging
-your game" on page 197). You may declare a variable and then not use it;
-you may mistake assignment and arithmetic operators (``=`` instead of
-``==``); you may forget the comma that separates properties, etc. For
-all these and many other warnings, Inform has found something which is
-legal but doubtful.
+Warnings are not immediately catastrophic, but you should get rid of them
+to ensure a good start at finding run-time mistakes (see :doc:`16`). You
+may declare a variable and then not use it; you may mistake assignment and
+arithmetic operators (``=`` instead of ``==``); you may forget the comma
+that separates properties, etc. For all these and many other warnings,
+Inform has found something which is legal but doubtful.
One common incident is to return in the middle of a statement block,
before the rest of statements can be reached. This is not always as
happen. Inform detects the fault and warns you. Probably the designer's
intention was:
+.. code-block:: inform
+
+ if (steel_door has open) {
+ give match ~light;
+ print_ret "The breeze blows out your lit match.";
+ }
Compiling *à la carte*
======================
-
One of the advantages of Inform is its portability between different
systems and machines. Specific usage of the compiler varies accordingly,
but some features should be in all environments. To obtain precise
information about any particular version, run the compiler with the
-``-h1`` switch -- see "Switches" on page 193.
-
-Often the compiler is run with the name of your source file as its only
-parameter. This tells the compiler to "read this file using Strict mode
-and from it generate a Version 5 story file of the same name". The
-source file is mostly full of statements which define how the game is to
-behave at run-time, but will also include compile-time instructions
-directed at the compiler itself (although such an instruction looks a
-lot like a **statement**, it's actually quite different in what it does,
-and is known as a **directive**). We have already seen the ``Include``
+:option:`-h1` switch -- see :ref:`switches`.
+
+.. Generated by autoindex
+.. index::
+ single: Strict mode
+
+Often the compiler is run with the name of your source file as its only
+parameter. This tells the compiler to "read this file using Strict mode and
+from it generate a Version 5 story file of the same name". The source file
+is mostly full of statements which define how the game is to behave at
+run-time, but will also include compile-time instructions directed at the
+compiler itself (although such an instruction looks a lot like a
+:term:`statement`, it's actually quite different in what it does, and is
+known as a :term:`directive`). We have already seen the ``Include``
directive:
:samp:`Include "{filename}";`
.. note::
- on some machines, a library file is actually called -- for example --
+ On some machines, a library file is actually called -- for example --
``Parser.h``, on others just ``Parser``. The compiler automatically
deals with such differences; you can *always* type simply ``Include
"Parser";`` in your source file.
!============================================================================
+.. _switches:
Switches
========
:samp:`inform {source_file story_file switches}`
-where "``inform``" is the name of the compiler, the
-:samp:`{story_file}` is optional (so that you can specify a different
-name from the
-:samp:`{source_file}`) and the switches are also optional. Note that
-switches must be preceded by a hyphen ``-``; if you want to set, for
-instance, Strict mode, you'd write ``-S`` , while if you want to
-deactivate it, you’d write ``-~S``. The tilde sign can, as elsewhere, be
-understood as "not". If you wish to set many switches, just write them
-one after another separated by spaces and each with its own hyphen, or
-merge them with one hyphen and no spaces:
+where "``inform``" is the name of the compiler, the :samp:`{story_file}` is
+optional (so that you can specify a different name from the
+:samp:`{source_file}`) and the switches are also optional. Note that
+switches must be preceded by a hyphen ``-``; if you want to set, for
+instance, Strict mode, you'd write :option:`-S` , while if you want to
+deactivate it, you’d write :option:`-~S`. The tilde sign can, as elsewhere,
+be understood as "not". If you wish to set many switches, just write them
+one after another separated by spaces and each with its own hyphen, or
+merge them with one hyphen and no spaces::
- :samp:`inform MyGame.inf -S -s -X`
+ inform MyGame.inf -S -s -X
- :samp:`inform MyGame.inf -Ssx`
+ inform MyGame.inf -Ssx
Although there's nothing wrong with this method, it isn't awfully
convenient should you need to change the switch settings. A more
flexible method is to define the switches at the very start of your
-source file, again in either format:
+source file, again in either format::
- :samp:`!% -S -s -X`
+ !% -S -s -X
- :samp:`!% -Ssx`
+ !% -Ssx
-Normally, all switches are off by default, except Strict mode (``-S``),
-which is on and checks the code for additional mistakes. It's well worth
-adding Debug mode (``-D``), thus making the debugging verbs available at
-run time. This is the ideal setting while coding, but you should turn
-Debug mode off (just remove the ``-D``) when you release your game to
-the public. This is fortunately very easy to check, since the game
-banner ends with the letter "D" if the game was compiled in Debug mode:
+Normally, all switches are off by default, except Strict mode
+(:option:`-S`), which is on and checks the code for additional
+mistakes. It's well worth adding Debug mode (:option:`-D`), thus making the
+debugging verbs available at run time. This is the ideal setting while
+coding, but you should turn Debug mode off (just remove the :option:`-D`)
+when you release your game to the public. This is fortunately very easy to
+check, since the game banner ends with the letter "D" if the game was
+compiled in Debug mode:
.. code-block:: transcript
Switches are case sensitive, so you get different effects from ``-x``
and ``-X``. Some of the more useful switches are:
-:samp:`-~S`
- Set compiler Strict mode off. This deactivates some additional error
- checking features when it reads your source file. Strict mode is on by
- default.
-
-:samp:`-v5 -v8`
- Compile to this version of story file. Versions 5 (on by default) and
- 8 are the only ones you should ever care about; they produce,
- respectively, story files with the extensions .z5 and .z8 . Version 5
- was the Advanced Infocom design, and is the default produced by
- Inform. This is the version you'll normally be using, which allows
- file sizes up to 256 Kbytes. If your game grows beyond that size,
- you'll need to compile to the Version 8 story file, which is very
- similar to Version 5 but allows a 512 Kbytes file size.
-
-:samp:`-D -X`
- Include respectively the debugging verbs and the Infix debugger in the
- story file (see "Debugging your game" on page 197).
-
-:samp:`-h1 -h2`
- Display help information about the compiler. ``-h1`` produces
- information about file naming, and ``-h2`` about the available
- switches.
-
-:samp:`-n -j`
- ``-n`` displays the number of declared attributes, properties and
- actions. ``-j`` lists objects as they are being read and constructed
- in the story file.
-
-:samp:`-s`
- Offer game statistics. This provides a lot of information about your
- game, including the number of objects, verbs, dictionary entries,
- memory usage, etc., while at the same time indicating the maximum
- allowed for each entry. This can be useful to check whether you are
- nearing the limits of Inform.
-
-:samp:`-r`
- Record all the text of the game into a temporary file, useful to check
- all your descriptions and messages by running them through a spelling
- checker.
-
-If you run the compiler with the ``-h2`` switch, you’ll find that there
-are many more switches than these, offering mostly advanced or obscure
-features which we consider to be of little interest to beginners.
-However, feel free to try whatever switches catch your eye; nothing you
-try here will affect your source file, which is strictly read-only as
-far as the compiler is concerned.
+.. option:: -S
+.. option:: -~S
+
+ Set compiler Strict mode on or off, respectively. Strict mode activates
+ some additional error checking features when it reads your source file.
+ Strict mode is on by default.
+
+.. option:: -v5
+.. option:: -v8
+
+ .. Generated by autoindex
+ .. index::
+ single: Infocom
+
+ Compile to this version of story file. Versions 5 (on by default) and
+ 8 are the only ones you should ever care about; they produce,
+ respectively, story files with the extensions .z5 and .z8. Version 5
+ was the Advanced Infocom design, and is the default produced by
+ Inform. This is the version you'll normally be using, which allows
+ file sizes up to 256 Kbytes. If your game grows beyond that size,
+ you'll need to compile to the Version 8 story file, which is very
+ similar to Version 5 but allows a 512 Kbytes file size.
+
+.. option:: -D
+.. option:: -X
+
+ Include respectively the debugging verbs and the Infix debugger in the
+ story file (see :doc:`16`).
+
+.. option:: -h1
+.. option:: -h2
+
+ Display help information about the compiler. :option:`-h1` produces
+ innformation about file naming, and :option:`-h2` about the available
+ switches.
+
+.. option:: -n
+.. option:: -j
+
+ :option:`-n` displays the number of declared attributes, properties and
+ actions. :option:`-j` lists objects as they are being read and constructed
+ in the story file.
+
+.. option:: -s
+.. option:: -~s
+
+ Offer game statistics (or not). This provides a lot of information about
+ your game, including the number of objects, verbs, dictionary entries,
+ memory usage, etc., while at the same time indicating the maximum
+ allowed for each entry. This can be useful to check whether you are
+ nearing the limits of Inform.
+
+.. option:: -r
+
+ Record all the text of the game into a temporary file, useful to check
+ all your descriptions and messages by running them through a spelling
+ checker.
+If you run the compiler with the :option:`-h2` switch, you’ll find that
+there are many more switches than these, offering mostly advanced or
+obscure features which we consider to be of little interest to beginners.
+However, feel free to try whatever switches catch your eye; nothing you try
+here will affect your source file, which is strictly read-only as far as
+the compiler is concerned.
projects / ibg.git / blobdiff