GNU macro processor - 8. File inclusion

Go to the first, previous, next, last section, table of contents.

# 8. File inclusion

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

## 8.1 Including named files

There are two builtin macros in `m4` for including files:

    include(filename)
    sinclude(filename)

both of which cause the file named filename 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 filename.

It is an error for an `include`d file not to exist. If you do not want error messages about non-existent files, `sinclude` can be used to include a file, if it exists, expanding to nothing if it does not.

    include(`no-such-file')
    =>
    error-->30.include:2: m4: Cannot open no-such-file: No such file or directory
    sinclude(`no-such-file')
    =>

Assume in the following that the file ``incl.m4'` contains the lines:

    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:

    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'`:

    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.

The builtin macros `include` and `sinclude` are recognized only when given arguments.

## 8.2 Searching for include files

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

If a file is not found in the current working directory, and the file name is not absolute, the file will be looked for in a specified search path. First, the directories specified with the ``-I'` option will be searched, in the order found on the command line. Second, 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 6.3 Controlling debugging output) can help isolate the problem.

Go to the first, previous, next, last section, table of contents.