216 lines
10 KiB
HTML
216 lines
10 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1988-2016 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with the
|
||
|
|
Invariant Sections being "Funding Free Software", the Front-Cover
|
||
|
|
Texts being (a) (see below), and with the Back-Cover Texts being (b)
|
||
|
|
(see below). A copy of the license is included in the section entitled
|
||
|
|
"GNU Free Documentation License".
|
||
|
|
|
||
|
|
(a) The FSF's Front-Cover Text is:
|
||
|
|
|
||
|
|
A GNU Manual
|
||
|
|
|
||
|
|
(b) The FSF's Back-Cover Text is:
|
||
|
|
|
||
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
||
|
|
software. Copies published by the Free Software Foundation raise
|
||
|
|
funds for GNU development. -->
|
||
|
|
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Using the GNU Compiler Collection (GCC): Precompiled Headers</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC): Precompiled Headers">
|
||
|
|
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Precompiled Headers">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Invoking-GCC.html#Invoking-GCC" rel="up" title="Invoking GCC">
|
||
|
|
<link href="C-Implementation.html#C-Implementation" rel="next" title="C Implementation">
|
||
|
|
<link href="Environment-Variables.html#Environment-Variables" rel="prev" title="Environment Variables">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.indentedblock {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style:oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nocodebreak {white-space:nowrap}
|
||
|
|
span.nolinebreak {white-space:nowrap}
|
||
|
|
span.roman {font-family:serif; font-weight:normal}
|
||
|
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
||
|
|
<a name="Precompiled-Headers"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Previous: <a href="Environment-Variables.html#Environment-Variables" accesskey="p" rel="prev">Environment Variables</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="Using-Precompiled-Headers"></a>
|
||
|
|
<h3 class="section">3.21 Using Precompiled Headers</h3>
|
||
|
|
<a name="index-precompiled-headers"></a>
|
||
|
|
<a name="index-speed-of-compilation"></a>
|
||
|
|
|
||
|
|
<p>Often large projects have many header files that are included in every
|
||
|
|
source file. The time the compiler takes to process these header files
|
||
|
|
over and over again can account for nearly all of the time required to
|
||
|
|
build the project. To make builds faster, GCC allows you to
|
||
|
|
<em>precompile</em> a header file.
|
||
|
|
</p>
|
||
|
|
<p>To create a precompiled header file, simply compile it as you would any
|
||
|
|
other file, if necessary using the <samp>-x</samp> option to make the driver
|
||
|
|
treat it as a C or C++ header file. You may want to use a
|
||
|
|
tool like <code>make</code> to keep the precompiled header up-to-date when
|
||
|
|
the headers it contains change.
|
||
|
|
</p>
|
||
|
|
<p>A precompiled header file is searched for when <code>#include</code> is
|
||
|
|
seen in the compilation. As it searches for the included file
|
||
|
|
(see <a href="http://gcc.gnu.org/onlinedocs/cpp/Search-Path.html#Search-Path">Search Path</a> in <cite>The C Preprocessor</cite>) the
|
||
|
|
compiler looks for a precompiled header in each directory just before it
|
||
|
|
looks for the include file in that directory. The name searched for is
|
||
|
|
the name specified in the <code>#include</code> with ‘<samp>.gch</samp>’ appended. If
|
||
|
|
the precompiled header file can’t be used, it is ignored.
|
||
|
|
</p>
|
||
|
|
<p>For instance, if you have <code>#include "all.h"</code>, and you have
|
||
|
|
<samp>all.h.gch</samp> in the same directory as <samp>all.h</samp>, then the
|
||
|
|
precompiled header file is used if possible, and the original
|
||
|
|
header is used otherwise.
|
||
|
|
</p>
|
||
|
|
<p>Alternatively, you might decide to put the precompiled header file in a
|
||
|
|
directory and use <samp>-I</samp> to ensure that directory is searched
|
||
|
|
before (or instead of) the directory containing the original header.
|
||
|
|
Then, if you want to check that the precompiled header file is always
|
||
|
|
used, you can put a file of the same name as the original header in this
|
||
|
|
directory containing an <code>#error</code> command.
|
||
|
|
</p>
|
||
|
|
<p>This also works with <samp>-include</samp>. So yet another way to use
|
||
|
|
precompiled headers, good for projects not designed with precompiled
|
||
|
|
header files in mind, is to simply take most of the header files used by
|
||
|
|
a project, include them from another header file, precompile that header
|
||
|
|
file, and <samp>-include</samp> the precompiled header. If the header files
|
||
|
|
have guards against multiple inclusion, they are skipped because
|
||
|
|
they’ve already been included (in the precompiled header).
|
||
|
|
</p>
|
||
|
|
<p>If you need to precompile the same header file for different
|
||
|
|
languages, targets, or compiler options, you can instead make a
|
||
|
|
<em>directory</em> named like <samp>all.h.gch</samp>, and put each precompiled
|
||
|
|
header in the directory, perhaps using <samp>-o</samp>. It doesn’t matter
|
||
|
|
what you call the files in the directory; every precompiled header in
|
||
|
|
the directory is considered. The first precompiled header
|
||
|
|
encountered in the directory that is valid for this compilation is
|
||
|
|
used; they’re searched in no particular order.
|
||
|
|
</p>
|
||
|
|
<p>There are many other possibilities, limited only by your imagination,
|
||
|
|
good sense, and the constraints of your build system.
|
||
|
|
</p>
|
||
|
|
<p>A precompiled header file can be used only when these conditions apply:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> Only one precompiled header can be used in a particular compilation.
|
||
|
|
|
||
|
|
</li><li> A precompiled header can’t be used once the first C token is seen. You
|
||
|
|
can have preprocessor directives before a precompiled header; you cannot
|
||
|
|
include a precompiled header from inside another header.
|
||
|
|
|
||
|
|
</li><li> The precompiled header file must be produced for the same language as
|
||
|
|
the current compilation. You can’t use a C precompiled header for a C++
|
||
|
|
compilation.
|
||
|
|
|
||
|
|
</li><li> The precompiled header file must have been produced by the same compiler
|
||
|
|
binary as the current compilation is using.
|
||
|
|
|
||
|
|
</li><li> Any macros defined before the precompiled header is included must
|
||
|
|
either be defined in the same way as when the precompiled header was
|
||
|
|
generated, or must not affect the precompiled header, which usually
|
||
|
|
means that they don’t appear in the precompiled header at all.
|
||
|
|
|
||
|
|
<p>The <samp>-D</samp> option is one way to define a macro before a
|
||
|
|
precompiled header is included; using a <code>#define</code> can also do it.
|
||
|
|
There are also some options that define macros implicitly, like
|
||
|
|
<samp>-O</samp> and <samp>-Wdeprecated</samp>; the same rule applies to macros
|
||
|
|
defined this way.
|
||
|
|
</p>
|
||
|
|
</li><li> If debugging information is output when using the precompiled
|
||
|
|
header, using <samp>-g</samp> or similar, the same kind of debugging information
|
||
|
|
must have been output when building the precompiled header. However,
|
||
|
|
a precompiled header built using <samp>-g</samp> can be used in a compilation
|
||
|
|
when no debugging information is being output.
|
||
|
|
|
||
|
|
</li><li> The same <samp>-m</samp> options must generally be used when building
|
||
|
|
and using the precompiled header. See <a href="Submodel-Options.html#Submodel-Options">Submodel Options</a>,
|
||
|
|
for any cases where this rule is relaxed.
|
||
|
|
|
||
|
|
</li><li> Each of the following options must be the same when building and using
|
||
|
|
the precompiled header:
|
||
|
|
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">-fexceptions
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</li><li> Some other command-line options starting with <samp>-f</samp>,
|
||
|
|
<samp>-p</samp>, or <samp>-O</samp> must be defined in the same way as when
|
||
|
|
the precompiled header was generated. At present, it’s not clear
|
||
|
|
which options are safe to change and which are not; the safest choice
|
||
|
|
is to use exactly the same options when generating and using the
|
||
|
|
precompiled header. The following are known to be safe:
|
||
|
|
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">-fmessage-length= -fpreprocessed -fsched-interblock
|
||
|
|
-fsched-spec -fsched-spec-load -fsched-spec-load-dangerous
|
||
|
|
-fsched-verbose=<var>number</var> -fschedule-insns -fvisibility=
|
||
|
|
-pedantic-errors
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>For all of these except the last, the compiler automatically
|
||
|
|
ignores the precompiled header if the conditions aren’t met. If you
|
||
|
|
find an option combination that doesn’t work and doesn’t cause the
|
||
|
|
precompiled header to be ignored, please consider filing a bug report,
|
||
|
|
see <a href="Bugs.html#Bugs">Bugs</a>.
|
||
|
|
</p>
|
||
|
|
<p>If you do use differing options when generating and using the
|
||
|
|
precompiled header, the actual behavior is a mixture of the
|
||
|
|
behavior for the options. For instance, if you use <samp>-g</samp> to
|
||
|
|
generate the precompiled header but not when using it, you may or may
|
||
|
|
not get debugging information for routines in the precompiled header.
|
||
|
|
</p>
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Previous: <a href="Environment-Variables.html#Environment-Variables" accesskey="p" rel="prev">Environment Variables</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|