Exact meaning of "system headers" for the GCC -MM flag

Question

According to the GCC documentation, the -MM flag will generate dependencies in this way:

Like -M but do not mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header.

I just found that the -MM flag when used in my projects not only suppresses dependencies to system headers, but also dependencies to third-party library headers I have locally installed in my home directory. Getting rid of system headers dependencies is usually convenient for me (as I do not edit them), but however I sometimes edit/customize third-party libraries, and of course I need to rebuild my code after such edits.

So, my question is what's a "system header" for GCC? Let's suppose you install a customized version of libpng in your home directory, and edit it to suit your needs... is that a "system header" for GCC?

I'm just moving to -M as a temporary workaround in the mean time.

Answer 1

System header directories

In GCC, system headers directories are just that; system header directories. There's no magic involved in determining what is and what is not a system header directory. GCC treats directories you tell it to be system header directories as system header directories.

Should you install the headers of a third-party library in you home directory, as in your example, and then go on to compile a project that needs this library with GCC, your compile will either fail due to missing said library, or it will use the system installed version of the library. This is because you haven't specified that you told GCC to include this local install and GCC will not magically do this for you. When you specify directories to include when searching for headers, you also tell GCC whether or not to treat these directories as system header directories.

Which directories become system header ones?

Directories added with the command line options -iwithprefix, -isystem, and -idirafter are treated as system header directories. The documentation for all three of these options are clear that they get the same special treatment as actual system headers. Additionally the paths in the environment variables C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, and OBJC_INCLUDE_PATH are treated as if they were passed with -isystem option and is thus also treated as system headers.

Obviously, it goes without saying that actual system headers, such as the ones that come with the compiler or are installed to the system is also treated as system headers.

Which directories does not?

Directories added with -iquote, -iwithprefixbefore, and -I are not treated as system header directories. This also includes directories from the CPATH environment variable, which is treated as being passed with the -I option.

Where is the source code that does this?

Since I spent some time searching through the GCC source code to find how this is defined, I'll leave this note for anyone interested: The precise definition of what is and what is not a system header can be seen in the add_path function in gcc/incfile.c. Here, sysp being non-zero means system header. In the same file you can also find register_include_chains which handles adding in the directories from the special environment variables. And finally, for the option parsing, add_path is called from gcc/c-family/c-opts.c for adding directories from various options.