Re: precompiled header suggestion

[Tom Tromey]

>>>>> "Rob" == Robert Collins <address@hidden> writes:

>> Recently gcc added precompiled header support.  This is mostly useful
>> for C++, but C might benefit in some cases too.

Rob> Are you planning on doing this, or just sketching the design and hoping
Rob> for volunteer contributions?

I'm hoping someone else will do it :-)


Rob> What might be a useful starting point is some manual test cases or
Rob> sample rules, to aim for.

No problem.  libstdc++ is already using it.  I've appended some
snippets from their Makefile.am.

We could probably already get most of this by abusing _PROGRAMS.
That's ugly though.

I've also appended the section of the gcc manual explaining
precompiled headers.

Tom


pch_input = ${host_builddir}/stdc++.h
pch_output_builddir = ${host_builddir}/stdc++.h.gch
pch_source = ${glibcxx_srcdir}/include/stdc++.h
PCHFLAGS=-Winvalid-pch -Wno-deprecated -x c++-header $(CXXFLAGS)
if GLIBCXX_BUILD_PCH
pch_build = ${pch_input}
pch_install = install-pch
else
pch_build =
pch_install =
endif

# Build a precompiled C++ include, stdc++.h.gch.
${pch_input}: ${allstamped} ${host_builddir}/c++config.h ${pch_source}
        touch ${pch_input}; \
        if [ ! -d "${pch_output_builddir}" ]; then \
          mkdir -p ${pch_output_builddir}; \
        fi; \
        $(CXX) $(PCHFLAGS) $(AM_CPPFLAGS) ${pch_source} -O0 -g -o 
${pch_output_builddir}/O0g; \
        $(CXX) $(PCHFLAGS) $(AM_CPPFLAGS) ${pch_source} -O2 -g -o 
${pch_output_builddir}/O2g;



@node Precompiled Headers
@section Using Precompiled Headers
@cindex precompiled headers
@cindex speed of compilation

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 users to
`precompile' a header file; then, if builds can use the precompiled
header file they will be much faster.

To create a precompiled header file, simply compile it as you would any
other file, if necessary using the @option{-x} option to make the driver
treat it as a C or C++ header file.  You will probably want to use a
tool like @command{make} to keep the precompiled header up-to-date when
the headers it contains change.

A precompiled header file will be searched for when @code{#include} is
seen in the compilation.  As it searches for the included file
(@pxref{Search Path,,Search Path,cpp.info,The C Preprocessor}) 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} with @samp{.gch} appended.  If
the precompiled header file can't be used, it is ignored.

For instance, if you have @code{#include "all.h"}, and you have
@file{all.h.gch} in the same directory as @file{all.h}, then the
precompiled header file will be used if possible, and the original
header will be used otherwise.

Alternatively, you might decide to put the precompiled header file in a
directory and use @option{-I} 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} command.

This also works with @option{-include}.  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 @option{-include} the precompiled header.  If the header files
have guards against multiple inclusion, they will be skipped because
they've already been included (in the precompiled header).

If you need to precompile the same header file for different
languages, targets, or compiler options, you can instead make a
@emph{directory} named like @file{all.h.gch}, and put each precompiled
header in the directory.  (It doesn't matter what you call the files
in the directory, every precompiled header in the directory will be
considered.)  The first precompiled header encountered in the
directory that is valid for this compilation will be used; they're
searched in no particular order.

There are many other possibilities, limited only by your imagination,
good sense, and the constraints of your build system.

A precompiled header file can be used only when these conditions apply:

@itemize
@item
Only one precompiled header can be used in a particular compilation.
@item
A precompiled header can't be used once the first C token is seen.  You
can have preprocessor directives before a precompiled header; you can
even include a precompiled header from inside another header, so long as
there are no C tokens before the @code{#include}.
@item
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.
@item
The precompiled header file must be produced by the same compiler
version and configuration as the current compilation is using.
The easiest way to guarantee this is to use the same compiler binary
for creating and using precompiled headers.
@item
Any macros defined before the precompiled header (including with
@option{-D}) 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 the they don't appear in the
precompiled header at all.
@item
Certain command-line options 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.
@end itemize

For all of these but the last, the compiler will automatically ignore
the precompiled header if the conditions aren't met.  For the last item,
some option changes will cause the precompiled header to be rejected,
but not all incompatible option combinations have yet been found.  If
you find a new incompatible combination, please consider filing a bug
report, see @ref{Bugs}.