(m4.info.gz) Using frozen files

 
 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 (
 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.
Info Catalog
(m4.info.gz) Frozen files
(m4.info.gz) Frozen file format
automatically generated byinfo2html