Separate compilation and `.x' files
The Miranda compiler compiles to an intermediate code, based on
combinators. When a Miranda expressions are evaluated in the course of
a session this code is executed by an interpreter.
Since compilation is a complex process (involving lexical analysis,
parsing, type checking and code-generation, as well as a number of other
minor steps) it is undesirable that the results of compiling a script
should just be "thrown away" at the end of a session. To avoid
unnecessary acts of recompilation the Miranda system maintains an
object-code file in association with each source file containing a
Miranda script.
For each source file, called say `script.m', the Miranda system will
create an object code file, called `script.x'. No action is required by
the user to keep these files up-to-date, since this is taken care of
automatically by the Miranda system. The .x files are never referred to
directly by the Miranda user, and you should not try to edit them (they
contain binary data).
You may however safely remove any .x file (if for example you don't wish
it to use up filespace) since this will at worst cause the Miranda
compiler to do some extra work later to recreate it.
If you select a script as the current script of a Miranda session, and
it has an up-to-date .x file, this will be loaded instead, avoiding
recompilation. If the .x file does not exist, or any relevant source
file has been modified since the .x file was created, the script will be
recompiled (and a side effect of your having selected this source file
as the current script will be to bring into existence an up-to-date .x
file for it).
[Inductive definition - source file B is `relevant' to source file A iff
file A %inserts or %includes B or any file to which B is relevant. For
a discussion of `%include' and the other library directives see manual
sections on `The Library Mechanism'.]
Note that compiling a script containing %include statements will have
the side effect of triggering subsidiary compilation processes for any
relevant source files which have been modified since their corresponding
.x file was created. Users familiar with the UNIX program `make' will
recognise this process as essentially the same as that which happens
when a `makefile' is obeyed. In the case of Miranda however, the `make'
process is fully automated by being built into the compiler.
More advanced information
If you want to check that a given Miranda script has an up-to-date
object code file without entering a Miranda session, this can be
accomplished from UNIX by calling mira with a special flag, thus
mira -make script.m
will force the existence of an up-to-date `script.x', performing all
(and only) those compilations which are necessary. Any number of source
files can be given after the -make flag (and as usual if a `.m'
extension is omitted it will be added automatically).
Example:- to make sure every Miranda source file in your current
directory has an up-to-date object code file, say `mira -make *.m'.
Applying mira -make to a `.x' file is equivalent to applying it to the
corresponding `.m' file. So another way to make sure everything in your
current directory is up-to-date is to say `mira -make *.x'. This has
the advantage that it will also remove any `.x' files whose `.m' files
no longer exist.
In the best UNIX tradition mira -make does its work silently unless
something is wrong. If the source files are all correct closed scripts
with up-to-date `.x' files, mira -make says nothing at all. If
recompilations are necessary it informs you which source files are being
compiled, and, as a last step, the names of any scripts which contain
errors or undefined names are listed, to stdout.
The exit status of a `mira -make' (relevant if you are a shell
programmer, or wish to include a `mira -make' command in a makefile for
a larger setup) is as follows. If (AFTER any necessary recompilations
have been performed) all the source files have up-to-date `.x' files,
and do not contain any syntax errors, type errors, or undefined names
(these facts are recorded in .x files) the exit status will be zero
(=ok), otherwise it will be 1.
It is possible to find out what names are exported from one or more
Miranda scripts without entering a Miranda session by using the command
mira -exports files
(as always the `.m' extension is added automatically to each filename,
if missing). This command first calls `mira -make' on each file, to
make sure everything is uptodate, and then lists to standard output the
exported names together with their types (one per line). If more than
one file is specified each group of names will be preceded by the name
of the file to which they appertain.
Note that the export profile of a script includes information about its
free identifiers (if any).
It is also possible to find out the names of all files on which a given
set of Miranda scripts depend, via %include and %insert statements, by
using the command
mira -sources files
This lists to standard output, one per line, the names of all relevant
source files. The standard environment, <stdenv>, is always omitted
from the list.
Effect of `mv' and `rm'
Finally we note a couple of points about the behaviour of Miranda .x
files under applications of mv and rm to their corresponding sources.
A `.x' file records (inter alia) the names of all relevant source files
relative to the directory in which it is stored, together with their
`date and time last modified'. Note that the UNIX command `mv' does not
alter the time-last-modified of the file being moved. So it is possible
when moving a miranda source file (or a group of interdependant source
files) from one directory to another to save mira the bother of
recompiling them, simply by moving all the relevant `.x' files into the
new directory along with the sources. (This doesn't work however if you
change the name of any of the source files during the move.)
[Note that `tar' has the same property, so the up-to-date-ness of
Miranda .x files is preserved across a tape dump.]
If you use `rm' to remove a Miranda source file, the next time you
invoke mira with the (now non-existent) file as its current script, it
will promptly remove the corresponding `.x' file. The logic of this is
as follows:- `.x' files must be kept up-to-date with their sources, and
the way to make a `.x' file up-to-date with a non-existent source is to
make it too non-existent. As a consequence it is not possible to send
someone a Miranda object code file without the corresponding source
(mira will delete it as soon as they try to use it!).
From some points of view this last feature might be regarded as a bug -
a way round it may be provided in a later release of the Miranda system.