GCC include header files for portable C code

Every method below works by changing what GCC finds at one of these steps. Method 0 changes the -I list. Methods 1 to 3 change the name in the #include line. Method 4 adds a file before the search for main.c's own includes even begins.

If a build picks up the wrong header, ask the compiler to print its search list. The lines between "search starts here" and "End of search list" are the folders, in order. The system folders differ from one machine and toolchain to the next.

$ echo | gcc -v -E -I./platform_one - 2>&1 \
    | sed -n '/search starts here/,/End of search/p'
#include "..." search starts here:
#include <...> search starts here:
 ./platform_one
 (system folders for your toolchain)
End of search list.

Arrange the project so the two headers share a name and differ only by folder. GCC searches the -I folder before the system folders, so #include "foo.h" finds the copy you named.

To add more than one include directory, repeat the flag: gcc -I./platform_one -I./common main.c. GCC searches them left to right. A path can be relative to the folder you run GCC from, or absolute.

In a Makefile the flag usually goes in CFLAGS or CPPFLAGS, so the platform becomes one variable on the make command line.

.
├── platform_one
│   └── foo.h
├── platform_two
│   └── foo.h
└── main.c

$ gcc -I./platform_one main.c
$ ./a.out
Platform one foo!

$ gcc -I./platform_two main.c
$ ./a.out
Platform two foo! I can do more!

This is legal C:

#define USE_HEADER "foo.h"
#include USE_HEADER

So main.c shrinks to #include USE_HEADER, and the name arrives through -D. The awkward part is the command line: the macro must contain the quote marks, so you escape them for the shell. The outer pair of quotes is for the shell, and it matters when the file name contains spaces or other characters the shell would split on.

Angle brackets work as well, as in -DUSE_HEADER="<foo.h>" instead of -DUSE_HEADER="\"foo.h\"". The search then starts at the -I step.

#include USE_HEADER

int main(void)
{
    print_foo();
    return 0;
}

$ gcc -DUSE_HEADER="\"platform_one_foo.h\"" main.c
$ ./a.out
Platform one foo!

$ gcc -DUSE_HEADER="\"platform_two_foo.h\"" main.c
$ ./a.out
Platform two foo! I can do more!

According to the GCC preprocessor options, GCC looks for the file in the folder you run it from first, then along the usual quote-form search chain. Several -include options are read in the order given.

main.c then needs no include line. That is handy for a configuration header every file needs, and confusing in a small program, because nothing in the source says where print_foo() comes from. GCC accepts both -include foo.h and --include=foo.h.

More background: why GCC has an -include option.

int main(void)
{
    print_foo();
    return 0;
}

$ gcc -include platform_one_foo.h main.c
$ ./a.out
Platform one foo!

$ gcc --include=platform_two_foo.h main.c
$ ./a.out
Platform two foo! I can do more!