How GCC locates included files

It is a constantly raised issue: you write a C-program using a library. You #include "library_header.h" or #include <library_header.h>.

BUT: Not all is well: either your .h-file could not be found or another equally-named .h-file is included, ...

SO, one of the most asked questions in the interwebs about the C-compiler is: "where the hell does the C-compiler look for included files" (with more or less expletives included".

THE ANSWER is (as usual): it depends ...

As I was not really satisfied with what I could read, mainly because the concrete information was spread out all over the place, I'm trying to compile (sic!) the definitive information on the topic, but for one selected scenario:

• the AVR-GCC compiler used in the Arduino 1.8.12 development environment, running on Microsoft Windows 10. This should eliminate the "it depends.." factor by nailing down all variations to a specific constellation.

Quote-Syntax versus Angle-Bracket-Syntax for #include

• Quote-Syntax looks like: #include "library_header.h"
• Angle-Bracket-Syntax looks like #include <library_header.h>

The difference between these 2 variants is the location(s) the compiler looks for the files to be included.

Built-in default locations in the compiler

The default locations where the compiler looks for include-files are determined when building the compiler itself.

For the AVR-GCC used in Arduino 1.8.12, the documentation says:

...

The Command

echo | gcc -Wp,-v -x c++ - -fsyntax-only

shows the directories the GCC compiler looks up for includes.

Example:

ignoring nonexistent directory "c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/../../../../avr/include/c++/7.3.0"
ignoring nonexistent directory "c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/../../../../avr/include/c++/7.3.0/avr"
ignoring nonexistent directory "c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/../../../../avr/include/c++/7.3.0/backward"
ignoring nonexistent directory "c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/../../../../avr/sys-include"
ignoring nonexistent directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/../../../../avr/include/c++/7.3.0"
ignoring nonexistent directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/../../../../avr/include/c++/7.3.0/avr"
ignoring nonexistent directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/../../../../avr/include/c++/7.3.0/backward"
ignoring duplicate directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/include"
ignoring duplicate directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/include-fixed"
ignoring nonexistent directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/../../../../avr/sys-include"
ignoring duplicate directory "c:/program files (x86)/arduino/hardware/tools/avr/lib/gcc/../../lib/gcc/avr/7.3.0/../../../../avr/include"
#include "..." search starts here:
#include <...> search starts here:
 c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/include
 c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/include-fixed
 c:\program files (x86)\arduino\hardware\tools\avr\bin\../lib/gcc/avr/7.3.0/../../../../avr/include
End of search list.

Compiler Options to control where GCC looks for include files

There are a number of options when invoking the GCC compiler to control which file system locations are include-files looked up in:

https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html#Directory-Options