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