14. Fast loading of frozen state

Some bigger m4 applications may be built over a common base containing hundreds of definitions and other costly initializations. Usually, the common base is kept in one or more declarative files, which files are listed on each m4 invocation prior to the user's input file, or else each input file uses include.

Reading the common base of a big application, over and over again, may be time consuming. GNU m4 offers some machinery to speed up the start of an application using lengthy common bases.

14.1 Using 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 section Searching for include files).

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.

14.2 Frozen file format

Frozen files are sharable across architectures. It is safe to write a frozen file on one machine and read it on another, given that the second machine uses the same or newer version of GNU m4. It is conventional, but not required, to give a frozen file the suffix of .m4f.

These are simple (editable) text files, made up of directives, each starting with a capital letter and ending with a newline (NL). Wherever a directive is expected, the character # introduces a comment line; empty lines are also ignored if they are not part of an embedded string. In the following descriptions, each len refers to the length of the corresponding strings str in the next line of input. Numbers are always expressed in decimal. There are no escape characters. The directives are:

C len1 , len2 NL str1 str2 NL

Uses str1 and str2 as the begin-comment and end-comment strings. If omitted, then `#' and NL are the comment delimiters.

D number, len NL str NL

Selects diversion number, making it current, then copy str in the current diversion. number may be a negative number for a non-existing diversion. To merely specify an active selection, use this command with an empty str. With 0 as the diversion number, str will be issued on standard output at reload time. GNU m4 will not produce the `D' directive with non-zero length for diversion 0, but this can be done with manual edits. This directive may appear more than once for the same diversion, in which case the diversion is the concatenation of the various uses. If omitted, then diversion 0 is current.

F len1 , len2 NL str1 str2 NL

Defines, through pushdef, a definition for str1 expanding to the function whose builtin name is str2. If the builtin does not exist (for example, if the frozen file was produced by a copy of m4 compiled with changeword support, but the version of m4 reloading was compiled without it), the reload is silent, but any subsequent use of the definition of str1 will result in a warning. This directive may appear more than once for the same name, and its order, along with `T', is important. If omitted, you will have no access to any builtins.

Q len1 , len2 NL str1 str2 NL

Uses str1 and str2 as the begin-quote and end-quote strings. If omitted, then ``' and `'' are the quote delimiters.

T len1 , len2 NL str1 str2 NL

Defines, though pushdef, a definition for str1 expanding to the text given by str2. This directive may appear more than once for the same name, and its order, along with `F', is important.

V number NL

Confirms the format of the file. m4 1.4.6 only creates and understands frozen files where number is 1. This directive must be the first non-comment in the file, and may not appear more than once.

This document was generated by System Administrator on September, 23 2007 using texi2html 1.70.