gcc: Precompiled Headers

1 
1 3.21 Using Precompiled Headers
1 ==============================
1 
1 Often large projects have many header files that are included in every
1 source file.  The time the compiler takes to process these header files
1 over and over again can account for nearly all of the time required to
1 build the project.  To make builds faster, GCC allows you to
1 "precompile" a header file.
1 
1  To create a precompiled header file, simply compile it as you would any
1 other file, if necessary using the '-x' option to make the driver treat
1 it as a C or C++ header file.  You may want to use a tool like 'make' to
1 keep the precompiled header up-to-date when the headers it contains
1 change.
1 
1  A precompiled header file is searched for when '#include' is seen in
11 the compilation.  As it searches for the included file (⇒Search
 Path (cpp)Search Path.) the compiler looks for a precompiled header in
1 each directory just before it looks for the include file in that
1 directory.  The name searched for is the name specified in the
1 '#include' with '.gch' appended.  If the precompiled header file cannot
1 be used, it is ignored.
1 
1  For instance, if you have '#include "all.h"', and you have 'all.h.gch'
1 in the same directory as 'all.h', then the precompiled header file is
1 used if possible, and the original header is used otherwise.
1 
1  Alternatively, you might decide to put the precompiled header file in a
1 directory and use '-I' to ensure that directory is searched before (or
1 instead of) the directory containing the original header.  Then, if you
1 want to check that the precompiled header file is always used, you can
1 put a file of the same name as the original header in this directory
1 containing an '#error' command.
1 
1  This also works with '-include'.  So yet another way to use precompiled
1 headers, good for projects not designed with precompiled header files in
1 mind, is to simply take most of the header files used by a project,
1 include them from another header file, precompile that header file, and
1 '-include' the precompiled header.  If the header files have guards
1 against multiple inclusion, they are skipped because they've already
1 been included (in the precompiled header).
1 
1  If you need to precompile the same header file for different languages,
1 targets, or compiler options, you can instead make a _directory_ named
1 like 'all.h.gch', and put each precompiled header in the directory,
1 perhaps using '-o'.  It doesn't matter what you call the files in the
1 directory; every precompiled header in the directory is considered.  The
1 first precompiled header encountered in the directory that is valid for
1 this compilation is used; they're searched in no particular order.
1 
1  There are many other possibilities, limited only by your imagination,
1 good sense, and the constraints of your build system.
1 
1  A precompiled header file can be used only when these conditions apply:
1 
1    * Only one precompiled header can be used in a particular
1      compilation.
1 
1    * A precompiled header cannot be used once the first C token is seen.
1      You can have preprocessor directives before a precompiled header;
1      you cannot include a precompiled header from inside another header.
1 
1    * The precompiled header file must be produced for the same language
1      as the current compilation.  You cannot use a C precompiled header
1      for a C++ compilation.
1 
1    * The precompiled header file must have been produced by the same
1      compiler binary as the current compilation is using.
1 
1    * Any macros defined before the precompiled header is included must
1      either be defined in the same way as when the precompiled header
1      was generated, or must not affect the precompiled header, which
1      usually means that they don't appear in the precompiled header at
1      all.
1 
1      The '-D' option is one way to define a macro before a precompiled
1      header is included; using a '#define' can also do it.  There are
1      also some options that define macros implicitly, like '-O' and
1      '-Wdeprecated'; the same rule applies to macros defined this way.
1 
1    * If debugging information is output when using the precompiled
1      header, using '-g' or similar, the same kind of debugging
1      information must have been output when building the precompiled
1      header.  However, a precompiled header built using '-g' can be used
1      in a compilation when no debugging information is being output.
1 
1    * The same '-m' options must generally be used when building and
1      using the precompiled header.  ⇒Submodel Options, for any
1      cases where this rule is relaxed.
1 
1    * Each of the following options must be the same when building and
1      using the precompiled header:
1 
1           -fexceptions
1 
1    * Some other command-line options starting with '-f', '-p', or '-O'
1      must be defined in the same way as when the precompiled header was
1      generated.  At present, it's not clear which options are safe to
1      change and which are not; the safest choice is to use exactly the
1      same options when generating and using the precompiled header.  The
1      following are known to be safe:
1 
1           -fmessage-length=  -fpreprocessed  -fsched-interblock
1           -fsched-spec  -fsched-spec-load  -fsched-spec-load-dangerous
1           -fsched-verbose=NUMBER  -fschedule-insns  -fvisibility=
1           -pedantic-errors
1 
1  For all of these except the last, the compiler automatically ignores
1 the precompiled header if the conditions aren't met.  If you find an
1 option combination that doesn't work and doesn't cause the precompiled
11 header to be ignored, please consider filing a bug report, see ⇒
 Bugs.
1 
1  If you do use differing options when generating and using the
1 precompiled header, the actual behavior is a mixture of the behavior for
1 the options.  For instance, if you use '-g' to generate the precompiled
1 header but not when using it, you may or may not get debugging
1 information for routines in the precompiled header.
1