Specification of search rules for C/C++ include directive

Introduction

Most C and C++ compilers interpret the #include "..." preprocessor directive to mean ``look for the specified include file first in the directory of the including file, then search using #include <...> search rules.'' This behavior is incompatible with ``viewpathing'', which requires the ability to override the included file with a file in a another directory (typically a file in a closer viewpath node.) This document specifies modified include directive search rules that provide the needed functionality.

Enabling the modified search rules

The -I- compiler option

-I- search rules are enabled when the -I- argument appears on the compilation command line. Search directories are specified to a compiler through a sequence of command line arguments of the form:

    -Ilcl1 -Ilcl2 ... -Ilcln -I- -Istd1 -Istd2 ... -Istdn

This is similar to the -I option currently used by many C/C++ compilers, except that a -I- option appears within the -I list, beginning of the list, or at the end of the list.

The prefixinclude compiler option

For all known compilers, prefixinclude processing is required when -I- search rules are in effect. Consequently, prefixinclude processing should be automatically enabled when -I- processing is turned on. Conversely, there is no known requirement for prefixinclude processing without -I-. Therefore, currently we see no need for a separate compiler option to turn on prefixinclude.

Terminology

The following terms are used in the search rules specification:

local include search path

The ``local include search path'' is defined as the list of directories specified by -I options preceding the -I-. In terms of the prototypical command line presented above, the quoted include search path would be the directory list:

    lcl1 lcl2 ... lcln
    

The ``local include search path'' may be empty, in which case the -I- option is the first -I option on the compilation command line.

standard include search path

The ``standard include search path'' is defined as the list of directories specified by -I options following the -I-. In terms of the prototypical command line presented above, the quoted include search path would be the directory list:

    std1 std2 ... stdn
    

The ``standard include search path'' may be empty, in which case the -I- option is the last -I option on the compilation command line.

system include search path

The ``system include search path'' is the list of directories searched automatically by the compiler after searching the standard include directories. The system include search path normally inlcludes /usr/include and may include other directories bundled with the compiler or the operating system.

primary source file

The primary source file is the file specified on the compilation command line. Also known as the root file.

include file path

The ``include file path'' is the entire pathname specified in a preprocessor include directive. The compiler uses the include file search rules to resolve the include file path into a path to a physical file in the file system. The last component of the include file path always refers to a regular file, not a directory.

current include directive

The include directive whose include file path we are attempting to resolve.

input file

An input is a source file read by the compiler. This includes the primary source file and 0 or more include files.

including file (current input file)

The ``including file'' is the file containing the current include directive. The ``including file'' is different from the primary source file in the case of nested includes. In terms of compiler file processing, the ``including file'' is also known as ``the current input file.''

parent including file (current parent file)

The ``parent including file'' is the file which included the current input file, if any. Every file processed during a compilation, except the primary source file, has a parent including file.

parent include directive

The ``parent include directive'' is the include directive used to include the current input file into the parent including file.

directory of including file

The ``directory of the including file'' is the physical directory which contains the including file.

include path prefix

The ``include path prefix'' is the directory component of the include file path. If there is no directory component, the include path prefix is ".".

prefix path of an input file

The prefix path of an input file specifies the relative location of an input file and is conceptually the concatenation of the include path prefixes of all parent include directives, recursively up to the root. There is one fixed prefix path for each input file. It is used instead of the physical directory of the including file when the -I- and prefixinclude options are in effect. A detailed rule for calculating the prefix path of each input file is given below.

Search rules when -I- is specified

Note: currently there are no known compilers which require -I- search rule processing without also requiring prefixinclude processing. This section is included only to clarify the meaning of -I- without the extra complications of prefixinclude.

Files included using #include "..." are searched using the following directory search paths in the following order:

1. local include search path
2. standard include search path
3. system include search path

Do not look in the directory of the including file.

Files included using #include <...> are searched using the following directory search paths in the following order:

1. standard include search path
2. system include search path

For both "..." and <...> style includes, if the include file path is an absolute path (path begins with a '/'), do not follow the usual search rules. Just use the named file without any search.

Search rules when -I- is specified and prefixinclude option is in effect

This rule reduces to the non-prefixinclude case stated previously when all include path prefixes in a compilation are ".". The only differences are: 1) we maintain a prefix path for each input file and 2) we perform an additional search step when a file is included using "..." and the prefix path of the including file is not ".".

Initialize the prefix path of the primary source file to ".".

During path concatenation operations, the usual path optimizations such as "./x" => "x" and "x/../y" => "y" may be performed.

For both "..." and <...> style includes, if the include file path is an absolute path (path begins with a '/'), do not follow the usual search rules. Just use the named file without any search. Set the prefix path of newly found included file to ".".

<<cpp index