C++: #include file search?

Question

This MSDN document quotes:

look for include files in the same directory of the file that contains the #include statement, and then in the directories of any files that include (#include) that file

Wait, what?
What does that actually mean (the bold stuff)?

Answer 1

It probably means that if foo/bar/baz.c includes ../bog/bog.h, and the latter contains

#include "fix.h"

it would find foo/bar/fix.h. In other words, it looks in the directory that contained the C file that included the header containing the include. Clear? :)

So, the file layout rendered as gorgeous ASCII graphics, is:

  foo/
  |
  +-bar/
  | |
  | +-baz.c
  | |
  | +-fix.h
  |
  +-bog/
    |
    +-bog.h

And bog.h is then able to find fix.h in the sibling directory foo.

Answer 2

I think it says that if you have a file foo.h which is included in some other files bar.cpp, baz.cpp etc and then use an #include "somefile.h" statement in foo.h the compiler will also search in the directories of bar.cpp and baz.cpp for it.

Answer 3

Please read the below for the MSDN document.

If the filename enclosed in double quotation marks is an incomplete path specification, the preprocessor first searches the "parent" file's directory. A parent file is the file containing the #include directive. For example, if you include a file named file2 within a file named file1, file1 is the parent file.

Include files can be "nested"; that is, an #include directive can appear in a file named by another #include directive. For example, file2, above, could include file3. In this case, file1 would still be the parent of file2 but would be the "grandparent" of file3.

When include files are nested and when compiling from the command line, directory searching begins with the directories of the parent file and then proceeds through the directories of any grandparent files. Thus, searching begins relative to the directory containing the source currently being processed. If the file is not found, the search moves to directories specified by the /I compiler option. Finally, the directories specified by the INCLUDE environment variable are searched.