visus
/
toolchain-gcc-arm-embedded

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2020 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 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Precompiled Headers (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Precompiled Headers (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Precompiled Headers (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<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.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<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> &nbsp; [<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.22 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 &lsquo;<samp>.gch</samp>&rsquo; appended.  If
the precompiled header file cannot be used, it is ignored.
</p>
<p>For instance, if you have <code>#include &quot;all.h&quot;</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&rsquo;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&rsquo;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&rsquo;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 cannot 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 cannot 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&rsquo;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&rsquo;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><li> Address space layout randomization (ASLR) can lead to not binary identical
PCH files.  If you rely on stable PCH file contents disable ASLR when generating
PCH files.

</li></ul>

<p>For all of these except the last, the compiler automatically
ignores the precompiled header if the conditions aren&rsquo;t met.  If you
find an option combination that doesn&rsquo;t work and doesn&rsquo;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> &nbsp; [<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>