GCC and Precompiled Headers

After reading this nice article (The Care and Feeding of Pre-Compiled Headers), I have some doubts regarding how these can actually work in real life. More specifically, how can I know that I need to trigger the rebuild of the pre-compiled header in the following scenarios:

I decide to #define something in one of my .cpp files that alters the way the pre-processor interprets some headers that are already included in my pre-compiled header
I include another header in one of my .cpp files which #defines a specific pre-processor directive that alters the way the pre-processor interprets a header already included in the precompiled header
Even worse, the previous issue can happen recursively, when certain headers #include other headers

Should the usage of pre-compiled headers enforce a certain restrictive coding style like limiting the number of headers included in .cpp files to one and never #defineing stuff in a .cpp file?

While Microsoft\'s compiler probably does a decent job with pre-compiled headers (by applying some MS-specific voodoo) because, as far as I know, it provides the /Yc and /Yu options that are supposed to do all the plumbing, for GCC it seems that this functionality requires a lot of manual work and creativity in the Makefile and I wasn\'t able to find a template that is supposed to address all the pitfalls of using pre-compiled headers.

For example, if I have a project which builds several libraries, in order not to rebuild all of them after each change, I have to use some really cute sed tricks in the Makefile to detect if one of the headers #included by the current library was modified (or it #includes a modified header). I fear to even think of the complications that pre-built headers would actually imply in order for the build script to rebuild them each time it is necessary.

Current GCC (i.e. 4.7) and previous versions of it works nicely with precompiled headers only when you have a single common header to your application, and when that single header (which includes in turn all the system ones, and the library specific ones, required by the application) is #include-d (as the first non-comment lexeme of your sources) by every source of your application.

So you should have a single yourapp.h and have every source file (i.e. every compilation unit) of yourapp starting with #include \"yourapp.h\" with the same preprocessing options (i.e. -D or -I or -U) on the command line. That youapp.h header file is usually #include-ing many others, e.g. system headers (or GTK or Qt ones) like <stdlib.h> or <sys/poll.h> or [in C++] <algorithm> or <gtk/gtk.h> or <QtGui> etc.

Recall that -H is a useful option to get gcc tell you what is included.

^{Your source files might have some additional #include after #include \"yourapp.h\" if so wanted.}

After a [single] precompiled header has been included by GCC, you may of course #define macros, #include some non-precompiled header, do conditional compilation with #ifdef, etc. But that preprocessing won\'t be \"pre-compiled\"!

This may not fit your needs or habits.

Some people (notably from Google, notably Diego Novillo) are working on the PreParsed Header (pph) branch to improve the situation, but the current GCC trunk has not got that work yet.

The explanation about that behavior of GCC is that a preprocessed header is essentially a persistent serialized checkpoint of the entire GCC heap (related to memory management inside GCC thru Ggc and GTY and gengtype). That checkpointed heap can be loaded only when gcc is in its initial empty state. As soon as something is known to gcc (actually cc1 or cc1plus) it cannot load any more any precompiled header file *.h.gch and will revert to parsing the textual header file *.h.

addenda ^{(november 2014)}

Even GCC 4.9 wants a single precompiled header. The pre-parsed header effort by Diego Novillo et al. has been abandoned.

Future versions (post C++14) of the C++ standard might define a module mechanism. See e.g. n4047 proposal.

^{(additional addenda, december 2015) This still holds for GCC-5 and the future GCC-6.}