m4: Using frozen files

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