1<html lang="en"> 2<head> 3<title>Precompiled Headers - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Invoking-GCC.html#Invoking-GCC" title="Invoking GCC"> 9<link rel="prev" href="Environment-Variables.html#Environment-Variables" title="Environment Variables"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988-2013 Free Software Foundation, Inc. 13 14Permission is granted to copy, distribute and/or modify this document 15under the terms of the GNU Free Documentation License, Version 1.3 or 16any later version published by the Free Software Foundation; with the 17Invariant Sections being ``Funding Free Software'', the Front-Cover 18Texts being (a) (see below), and with the Back-Cover Texts being (b) 19(see below). A copy of the license is included in the section entitled 20``GNU Free Documentation License''. 21 22(a) The FSF's Front-Cover Text is: 23 24 A GNU Manual 25 26(b) The FSF's Back-Cover Text is: 27 28 You have freedom to copy and modify this GNU Manual, like GNU 29 software. Copies published by the Free Software Foundation raise 30 funds for GNU development.--> 31<meta http-equiv="Content-Style-Type" content="text/css"> 32<style type="text/css"><!-- 33 pre.display { font-family:inherit } 34 pre.format { font-family:inherit } 35 pre.smalldisplay { font-family:inherit; font-size:smaller } 36 pre.smallformat { font-family:inherit; font-size:smaller } 37 pre.smallexample { font-size:smaller } 38 pre.smalllisp { font-size:smaller } 39 span.sc { font-variant:small-caps } 40 span.roman { font-family:serif; font-weight:normal; } 41 span.sansserif { font-family:sans-serif; font-weight:normal; } 42--></style> 43<link rel="stylesheet" type="text/css" href="../cs.css"> 44</head> 45<body> 46<div class="node"> 47<a name="Precompiled-Headers"></a> 48<p> 49Previous: <a rel="previous" accesskey="p" href="Environment-Variables.html#Environment-Variables">Environment Variables</a>, 50Up: <a rel="up" accesskey="u" href="Invoking-GCC.html#Invoking-GCC">Invoking GCC</a> 51<hr> 52</div> 53 54<h3 class="section">3.20 Using Precompiled Headers</h3> 55 56<p><a name="index-precompiled-headers-2406"></a><a name="index-speed-of-compilation-2407"></a> 57Often large projects have many header files that are included in every 58source file. The time the compiler takes to process these header files 59over and over again can account for nearly all of the time required to 60build the project. To make builds faster, GCC allows you to 61<dfn>precompile</dfn> a header file. 62 63 <p>To create a precompiled header file, simply compile it as you would any 64other file, if necessary using the <samp><span class="option">-x</span></samp> option to make the driver 65treat it as a C or C++ header file. You may want to use a 66tool like <samp><span class="command">make</span></samp> to keep the precompiled header up-to-date when 67the headers it contains change. 68 69 <p>A precompiled header file is searched for when <code>#include</code> is 70seen in the compilation. As it searches for the included file 71(see <a href="../cpp/Search-Path.html#Search-Path">Search Path</a>) the 72compiler looks for a precompiled header in each directory just before it 73looks for the include file in that directory. The name searched for is 74the name specified in the <code>#include</code> with ‘<samp><span class="samp">.gch</span></samp>’ appended. If 75the precompiled header file can't be used, it is ignored. 76 77 <p>For instance, if you have <code>#include "all.h"</code>, and you have 78<samp><span class="file">all.h.gch</span></samp> in the same directory as <samp><span class="file">all.h</span></samp>, then the 79precompiled header file is used if possible, and the original 80header is used otherwise. 81 82 <p>Alternatively, you might decide to put the precompiled header file in a 83directory and use <samp><span class="option">-I</span></samp> to ensure that directory is searched 84before (or instead of) the directory containing the original header. 85Then, if you want to check that the precompiled header file is always 86used, you can put a file of the same name as the original header in this 87directory containing an <code>#error</code> command. 88 89 <p>This also works with <samp><span class="option">-include</span></samp>. So yet another way to use 90precompiled headers, good for projects not designed with precompiled 91header files in mind, is to simply take most of the header files used by 92a project, include them from another header file, precompile that header 93file, and <samp><span class="option">-include</span></samp> the precompiled header. If the header files 94have guards against multiple inclusion, they are skipped because 95they've already been included (in the precompiled header). 96 97 <p>If you need to precompile the same header file for different 98languages, targets, or compiler options, you can instead make a 99<em>directory</em> named like <samp><span class="file">all.h.gch</span></samp>, and put each precompiled 100header in the directory, perhaps using <samp><span class="option">-o</span></samp>. It doesn't matter 101what you call the files in the directory; every precompiled header in 102the directory is considered. The first precompiled header 103encountered in the directory that is valid for this compilation is 104used; they're searched in no particular order. 105 106 <p>There are many other possibilities, limited only by your imagination, 107good sense, and the constraints of your build system. 108 109 <p>A precompiled header file can be used only when these conditions apply: 110 111 <ul> 112<li>Only one precompiled header can be used in a particular compilation. 113 114 <li>A precompiled header can't be used once the first C token is seen. You 115can have preprocessor directives before a precompiled header; you cannot 116include a precompiled header from inside another header. 117 118 <li>The precompiled header file must be produced for the same language as 119the current compilation. You can't use a C precompiled header for a C++ 120compilation. 121 122 <li>The precompiled header file must have been produced by the same compiler 123binary as the current compilation is using. 124 125 <li>Any macros defined before the precompiled header is included must 126either be defined in the same way as when the precompiled header was 127generated, or must not affect the precompiled header, which usually 128means that they don't appear in the precompiled header at all. 129 130 <p>The <samp><span class="option">-D</span></samp> option is one way to define a macro before a 131precompiled header is included; using a <code>#define</code> can also do it. 132There are also some options that define macros implicitly, like 133<samp><span class="option">-O</span></samp> and <samp><span class="option">-Wdeprecated</span></samp>; the same rule applies to macros 134defined this way. 135 136 <li>If debugging information is output when using the precompiled 137header, using <samp><span class="option">-g</span></samp> or similar, the same kind of debugging information 138must have been output when building the precompiled header. However, 139a precompiled header built using <samp><span class="option">-g</span></samp> can be used in a compilation 140when no debugging information is being output. 141 142 <li>The same <samp><span class="option">-m</span></samp> options must generally be used when building 143and using the precompiled header. See <a href="Submodel-Options.html#Submodel-Options">Submodel Options</a>, 144for any cases where this rule is relaxed. 145 146 <li>Each of the following options must be the same when building and using 147the precompiled header: 148 149 <pre class="smallexample"> -fexceptions 150</pre> 151 <li>Some other command-line options starting with <samp><span class="option">-f</span></samp>, 152<samp><span class="option">-p</span></samp>, or <samp><span class="option">-O</span></samp> must be defined in the same way as when 153the precompiled header was generated. At present, it's not clear 154which options are safe to change and which are not; the safest choice 155is to use exactly the same options when generating and using the 156precompiled header. The following are known to be safe: 157 158 <pre class="smallexample"> -fmessage-length= -fpreprocessed -fsched-interblock 159 -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous 160 -fsched-verbose=<var>number</var> -fschedule-insns -fvisibility= 161 -pedantic-errors 162</pre> 163 </ul> 164 165 <p>For all of these except the last, the compiler automatically 166ignores the precompiled header if the conditions aren't met. If you 167find an option combination that doesn't work and doesn't cause the 168precompiled header to be ignored, please consider filing a bug report, 169see <a href="Bugs.html#Bugs">Bugs</a>. 170 171 <p>If you do use differing options when generating and using the 172precompiled header, the actual behavior is a mixture of the 173behavior for the options. For instance, if you use <samp><span class="option">-g</span></samp> to 174generate the precompiled header but not when using it, you may or may 175not get debugging information for routines in the precompiled header. 176 177<!-- Copyright (C) 2001-2013 Free Software Foundation, Inc. --> 178<!-- This is part of the GCC manual. --> 179<!-- For copying conditions, see the file gcc.texi. --> 180 </body></html> 181 182