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