2.4.1. Automatic PCH processing

When you use the --pch command-line option, automatic PCH processing is enabled. This means that the compiler automatically looks for a qualifying PCH file, and reads it if found. Otherwise, the compiler creates one for use on a subsequent compilation.

When the compiler creates a PCH file, it takes the name of the primary source file and replaces the suffix with .pch. The PCH file is created in the directory of the primary source file, unless you specify the --pch_dir option.

See Ordering command-line options for more information.

The header stop point

The PCH file contains a snapshot of all the code that precedes a header stop point. Typically, the header stop point is the first token in the primary source file that does not belong to a preprocessing directive. In the following example, the header stop point is int and the PCH file contains a snapshot that reflects the inclusion of xxx.h and yyy.h:

#include "xxx.h"
#include "yyy.h"
int i;

Note

You can manually specify the header stop point with #pragma hdrstop. You must place this before the first token that does not belong to a preprocessing directive. In this example, place it before int. See Controlling PCH processing for more information.

Conditions that affect PCH file generation

If the first non-preprocessor token, or a #pragma hdrstop, appears within a #if block, the header stop point is the outermost enclosing #if. For example:

#include "xxx.h"
#ifndef YYY_H
#define YYY_H 1
#include "yyy.h"
#endif
#if TEST
int i;
#endif

In this example, the first token that does not belong to a preprocessing directive is int, but the header stop point is the start of the #if block containing it. The PCH file reflects the inclusion of xxx.h and, conditionally, the definition of YYY_H and inclusion of yyy.h. It does not contain the state produced by #if TEST.

A PCH file is produced only if the header stop point and the code preceding it, mainly, the header files, meet the following requirements:

  • The header stop point must appear at file scope. It must not be within an unclosed scope established by a header file. For example, a PCH file is not created in this case:

    // xxx.h
    class A
    {
        // xxx.c
        #include "xxx.h"
        int i;
    }; 
    
  • The header stop point must not be inside a declaration that is started within a header file. Also, in C++, it must not be part of a declaration list of a linkage specification. For example, in the following case the header stop point is int, but because it is not the start of a new declaration, no PCH file is created:

    // yyy.h
    static
    // yyy.c
    #include "yyy.h"
    int i; 
    
  • The header stop point must not be inside a #if block or a #define that is started within a header file.

  • The processing that precedes the header stop point must not have produced any errors.

    Note

    Warnings and other diagnostics are not reproduced when the PCH file is reused.

  • No references to predefined macros __DATE__ or __TIME__ must appear.

  • No instances, the #line preprocessing directive must appear.

  • #pragma no_pch must not appear.

  • The code preceding the header stop point must have introduced a sufficient number of declarations to justify the overhead associated with precompiled headers.

More than one PCH file might apply to a given compilation. If so, the largest is used, that is, the one representing the most preprocessing directives from the primary source file. For instance, a primary source file might begin with:

#include "xxx.h"
#include "yyy.h"
#include "zzz.h"

If there is one PCH file for xxx.h and a second for xxx.h and yyy.h, the latter PCH file is selected, assuming that both apply to the current compilation. Additionally, after the PCH file for the first two headers is read in and the third is compiled, a new PCH file for all three headers might be created.

In automatic PCH processing mode the compiler indicates that a PCH file is obsolete, and deletes it, under the following circumstances:

  • if the PCH file is based on at least one out-of-date header file but is otherwise applicable for the current compilation

  • if the PCH file has the same base name as the source file being compiled, for example, xxx.pch and xxx.c, but is not applicable for the current compilation, for example, because you have used different command-line options.

These describe some common cases. You must delete other PCH files as required.

Copyright © 2002-2007 ARM Limited. All rights reserved.ARM DUI 0205H
Non-Confidential