gcc/doc/gcc/gcc-command-options/using-precompiled-headers.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. only:: not man
   7
   8   .. index:: precompiled headers, speed of compilation
   9
  10   .. _precompiled-headers:
  11
  12   Using Precompiled Headers
  13   *************************
  14
  15   Often large projects have many header files that are included in every
  16   source file.  The time the compiler takes to process these header files
  17   over and over again can account for nearly all of the time required to
  18   build the project.  To make builds faster, GCC allows you to
  19   :dfn:`precompile` a header file.
  20
  21   To create a precompiled header file, simply compile it as you would any
  22   other file, if necessary using the :option:`-x` option to make the driver
  23   treat it as a C or C++ header file.  You may want to use a
  24   tool like :command:`make` to keep the precompiled header up-to-date when
  25   the headers it contains change.
  26
  27   A precompiled header file is searched for when ``#include`` is
  28   seen in the compilation.  As it searches for the included file
  29   (see :ref:`cpp:search-path`) the
  30   compiler looks for a precompiled header in each directory just before it
  31   looks for the include file in that directory.  The name searched for is
  32   the name specified in the ``#include`` with :samp:`.gch` appended.  If
  33   the precompiled header file cannot be used, it is ignored.
  34
  35   For instance, if you have ``#include "all.h"``, and you have
  36   :samp:`all.h.gch` in the same directory as :samp:`all.h`, then the
  37   precompiled header file is used if possible, and the original
  38   header is used otherwise.
  39
  40   Alternatively, you might decide to put the precompiled header file in a
  41   directory and use :option:`-I` to ensure that directory is searched
  42   before (or instead of) the directory containing the original header.
  43   Then, if you want to check that the precompiled header file is always
  44   used, you can put a file of the same name as the original header in this
  45   directory containing an ``#error`` command.
  46
  47   This also works with :option:`-include`.  So yet another way to use
  48   precompiled headers, good for projects not designed with precompiled
  49   header files in mind, is to simply take most of the header files used by
  50   a project, include them from another header file, precompile that header
  51   file, and :option:`-include` the precompiled header.  If the header files
  52   have guards against multiple inclusion, they are skipped because
  53   they've already been included (in the precompiled header).
  54
  55   If you need to precompile the same header file for different
  56   languages, targets, or compiler options, you can instead make a
  57   *directory* named like :samp:`all.h.gch`, and put each precompiled
  58   header in the directory, perhaps using :option:`-o`.  It doesn't matter
  59   what you call the files in the directory; every precompiled header in
  60   the directory is considered.  The first precompiled header
  61   encountered in the directory that is valid for this compilation is
  62   used; they're searched in no particular order.
  63
  64   There are many other possibilities, limited only by your imagination,
  65   good sense, and the constraints of your build system.
  66
  67   A precompiled header file can be used only when these conditions apply:
  68
  69   * Only one precompiled header can be used in a particular compilation.
  70
  71   * A precompiled header cannot be used once the first C token is seen.  You
  72     can have preprocessor directives before a precompiled header; you cannot
  73     include a precompiled header from inside another header.
  74
  75   * The precompiled header file must be produced for the same language as
  76     the current compilation.  You cannot use a C precompiled header for a C++
  77     compilation.
  78
  79   * The precompiled header file must have been produced by the same compiler
  80     binary as the current compilation is using.
  81
  82   * Any macros defined before the precompiled header is included must
  83     either be defined in the same way as when the precompiled header was
  84     generated, or must not affect the precompiled header, which usually
  85     means that they don't appear in the precompiled header at all.
  86
  87     The :option:`-D` option is one way to define a macro before a
  88     precompiled header is included; using a ``#define`` can also do it.
  89     There are also some options that define macros implicitly, like
  90     :option:`-O` and :option:`-Wdeprecated` ; the same rule applies to macros
  91     defined this way.
  92
  93   * If debugging information is output when using the precompiled
  94     header, using :option:`-g` or similar, the same kind of debugging information
  95     must have been output when building the precompiled header.  However,
  96     a precompiled header built using :option:`-g` can be used in a compilation
  97     when no debugging information is being output.
  98
  99   * The same :option:`-m` options must generally be used when building
 100     and using the precompiled header.  See :ref:`submodel-options`,
 101     for any cases where this rule is relaxed.
 102
 103   * Each of the following options must be the same when building and using
 104     the precompiled header: :option:`-fexceptions`
 105
 106   * Some other command-line options starting with :option:`-f`,
 107     :option:`-p`, or :option:`-O` must be defined in the same way as when
 108     the precompiled header was generated.  At present, it's not clear
 109     which options are safe to change and which are not; the safest choice
 110     is to use exactly the same options when generating and using the
 111     precompiled header.  The following are known to be safe:
 112
 113     :option:`-fmessage-length=`  :option:`-fpreprocessed`  :option:`-fsched-interblock` |gol|
 114     :option:`-fsched-spec`  :option:`-fsched-spec-load`  :option:`-fsched-spec-load-dangerous` |gol|
 115     :option:`-fsched-verbose=number`  :option:`-fschedule-insns`  :option:`-fvisibility=` |gol|
 116     :option:`-pedantic-errors`
 117
 118   * Address space layout randomization (ASLR) can lead to not binary identical
 119     PCH files.  If you rely on stable PCH file contents disable ASLR when generating
 120     PCH files.
 121
 122   For all of these except the last, the compiler automatically
 123   ignores the precompiled header if the conditions aren't met.  If you
 124   find an option combination that doesn't work and doesn't cause the
 125   precompiled header to be ignored, please consider filing a bug report,
 126   see :ref:`bugs`.
 127
 128   If you do use differing options when generating and using the
 129   precompiled header, the actual behavior is a mixture of the
 130   behavior for the options.  For instance, if you use :option:`-g` to
 131   generate the precompiled header but not when using it, you may or may
 132   not get debugging information for routines in the precompiled header.