B.2.124.5 The Viable Prefix

In order to share a precompiled-header file across multiple source files, those source files must share a common set of include files as their initial sequence of tokens. A token is a keyword, name or punctuation mark. Comments and code that is excluded by #if directives are not recognized by the compiler as tokens. This initial sequence of tokens is known as the viable prefix. In other words, the viable prefix is the top portion of the source file that is common to all source files. The compiler uses this viable prefix as the basis for creating a precompiled-header file and thereby determining which header files from the source are pre-compiled.

The viable prefix that the compiler finds during the current compilation must match the viable prefix that it used to create the precompiled-header file. In other words, viable prefix must be interpreted consistently across all the source files that use the same precompiled-header file.

The viable prefix of a source file can only be comprised of comments and any of the following pre-processor directives:

#include
#if/ifdef/ifndef/else/elif/endif
#define/undef
#ident (if identical, passed through as is)
#pragma (if identical)

Any of these may reference macros. The #else, #elif, and #endif directives must match within the viable prefix. Comments are ignored.

The compiler determines the end point of the viable prefix automatically when you specify -xpch=auto or -xpch=autofirst and is defined as follows. For -xpch=collect or -xpch=use, the viable prefix ends with a #pragma hdrstop.

• The first declaration/definition statement

• The first #line directive

• A #pragma hdrstop directive

• After the named include file if you specify -xpch=auto and -xpchstop

• The first include file if you specify -xpch=autofirst

  ---

  Note –

  An end point within a conditional statement generates a warning and disables the automatic creation of a precompiled-header file. Also, if you specify both the #pragma hdrstop and the -xpchstop option, then the compiler uses the earlier of the two stop points to terminate the viable prefix.

  ---

Within the viable prefix of each file that shares a precompiled-header file, each corresponding #define and #undef directive must reference the same symbol (in the case of #define, each one must reference the same value). Their order of appearance within each viable prefix must be the same as well. Each corresponding pragma must also be the same and appear in the same order across all the files sharing a precompiled header.