Next: Frozen file format, Up: Frozen files
Suppose a user has a library of m4 initializations in
base.m4, which is then used with multiple input files:
m4 base.m4 input1.m4
m4 base.m4 input2.m4
m4 base.m4 input3.m4
Rather than spending time parsing the fixed contents of base.m4 every time, the user might rather execute:
m4 -F base.m4f base.m4
once, and further execute, as often as needed:
m4 -R base.m4f input1.m4
m4 -R base.m4f input2.m4
m4 -R base.m4f input3.m4
with the varying input. The first call, containing the -F
option, only reads and executes file base.m4, defining
various application macros and computing other initializations.
Once the input file base.m4 has been completely processed, GNU
m4 produces on base.m4f a frozen file, that is, a
file which contains a kind of snapshot of the m4 internal state.
Later calls, containing the -R option, are able to reload
the internal state of m4, from base.m4f,
prior to reading any other input files. This means
instead of starting with a virgin copy of m4, input will be
read after having effectively recovered the effect of a prior run.
In our example, the effect is the same as if file base.m4 has
been read anew. However, this effect is achieved a lot faster.
Only one frozen file may be created or read in any one m4
invocation. It is not possible to recover two frozen files at once.
However, frozen files may be updated incrementally, through using
-R and -F options simultaneously. For example, if
some care is taken, the command:
m4 file1.m4 file2.m4 file3.m4 file4.m4
could be broken down in the following sequence, accumulating the same output:
m4 -F file1.m4f file1.m4
m4 -R file1.m4f -F file2.m4f file2.m4
m4 -R file2.m4f -F file3.m4f file3.m4
m4 -R file3.m4f file4.m4
Some care is necessary because not every effort has been made for
this to work in all cases. In particular, the trace attribute of
macros is not handled, nor the current setting of changeword.
Currently, m4wrap and sysval also have problems.
Also, interactions for some options of m4, being used in one call
and not in the next, have not been fully analyzed yet. On the other
end, you may be confident that stacks of pushdef definitions
are handled correctly, as well as undefined or renamed builtins, and
changed strings for quotes or comments. And future releases of
GNU M4 will improve on the utility of frozen files.
When an m4 run is to be frozen, the automatic undiversion
which takes place at end of execution is inhibited. Instead, all
positively numbered diversions are saved into the frozen file.
The active diversion number is also transmitted.
A frozen file to be reloaded need not reside in the current directory.
It is looked up the same way as an include file (see Search Path).
If the frozen file was generated with a newer version of m4, and
contains directives that an older m4 cannot parse, attempting to
load the frozen file with option -R will cause m4 to
exit with status 63 to indicate version mismatch.