9. File inclusion

m4 allows you to include named files at any point in the input.

9.1 Including named files

There are two builtin macros in m4 for including files:

Builtin: include (file)

Builtin: sinclude (file)

Both macros cause the file named file to be read by m4. When the end of the file is reached, input is resumed from the previous input file.

The expansion of include and sinclude is therefore the contents of file.

If file does not exist, is a directory, or cannot otherwise be read, the expansion is void, and include will fail with an error while sinclude is silent. The empty string counts as a file that does not exist.

The macros include and sinclude are recognized only with parameters.

include(`none')
error-->m4:stdin:1: cannot open `none': No such file or directory
⇒
include()
error-->m4:stdin:2: cannot open `': No such file or directory
⇒
sinclude(`none')
⇒
sinclude()
⇒

The rest of this section assumes that m4 is invoked with the ‘-I’ option (see section Invoking m4) pointing to the ‘m4-1.4.14/examples’ directory shipped as part of the GNU m4 package. The file ‘m4-1.4.14/examples/incl.m4’ in the distribution contains the lines:

$ cat examples/incl.m4
⇒Include file start
⇒foo
⇒Include file end

Normally file inclusion is used to insert the contents of a file into the input stream. The contents of the file will be read by m4 and macro calls in the file will be expanded:

$ m4 -I examples
define(`foo', `FOO')
⇒
include(`incl.m4')
⇒Include file start
⇒FOO
⇒Include file end
⇒

The fact that include and sinclude expand to the contents of the file can be used to define macros that operate on entire files. Here is an example, which defines ‘bar’ to expand to the contents of ‘incl.m4’:

$ m4 -I examples
define(`bar', include(`incl.m4'))
⇒
This is `bar':  >>bar<<
⇒This is bar:  >>Include file start
⇒foo
⇒Include file end
⇒<<

This use of include is not trivial, though, as files can contain quotes, commas, and parentheses, which can interfere with the way the m4 parser works. GNU m4 seamlessly concatenates the file contents with the next character, even if the included file ended in the middle of a comment, string, or macro call. These conditions are only treated as end of file errors if specified as input files on the command line.

In GNU m4, an alternative method of reading files is using undivert (see section Undiverting output) on a named file.

9.2 Searching for include files

GNU m4 allows included files to be found in other directories than the current working directory.

If the ‘--prepend-include’ or ‘-B’ command-line option was provided (see section Invoking m4), those directories are searched first, in reverse order that those options were listed on the command line. Then m4 looks in the current working directory. Next comes the directories specified with the ‘--include’ or ‘-I’ option, in the order found on the command line. Finally, if the M4PATH environment variable is set, it is expected to contain a colon-separated list of directories, which will be searched in order.

If the automatic search for include-files causes trouble, the ‘p’ debug flag (see section Controlling debugging output) can help isolate the problem.

This document was generated by root on November 9, 2023 using texi2html 1.82.