Searching include files

Required behaviour

The standards for C and C++ don't says much about the behavior of #include <header> and #include "file".

The first form is replaced by the content of an header identified by the sequence of characters between < and >. What is an header (how it is different from a source file) and how it is found is specified by the implementation.

The second form is replaced by the content of an source file identified by the sequence of characters between the ". If the file is not found, an header identified by the same sequence of characters is searched.

A third form #include pp-tokens is even less precisely specified. The pp-tokens are macro expanded and then transformed in an implementation defined way in the two first forms. And implementation rarely describe their behavior, gcc being an exception.

Nearly universal behavior

For most compilers, headers and source files and OS level files. They allow to give a list of directories where to search for included files.

Source files (included with #include "file") are searched:

Headers (included with #include <header>) are searched:

Exceptions

It is not possible to achieve this behavior with some compilers.

Visual C++

Visual C++ has nearly the same behaviour but looks for source files in the directory of the file containing the directive and in the directories of all the files including this file (directly or indirectly) before searching the user specified list of directories.

Metrowerks CodeWarrior

Older versions of CodeWarrior weren't hable to search for included source files in the directory of the file containing the include directive. New version are now able to do it.

Other behaviors

List of directories to search for source files

It is common to be able to specify a list of directories where to search source files (included with #include "file"). Using this often disable searching in the directory containing the include directive.

Compilers having this capabilities include:

Searching in subdirectories

Metrowerks CodeWarrior allows to indicate for each of the directories given by the user that the search must be recursive, that is that the sub-directories are also searched.

Reported behaviour

Some compilers look for files included with #include "" in the directory where the compiler is launched and not in the directory of the file containing the directive. According to some, this is the standard behaviour on VMS but I don't remember so (I may be wrong, it's a long time since I've used VMS last) and that's not the case for the DECUS C preprocessor (whose sources are available somewhere on the net).