B.2.124 -xpch=v

This compiler option activates the precompiled-header feature. v can be auto, autofirst, collect:pch_filename, or use:pch_filename. You can take advantage of this feature through the -xpch (detailed in B.2.124 -xpch=v) and -xpchstop (detailed in B.2.125 -xpchstop=[file|<include>]) options in combination with the #pragma hdrstop directive (detailed under 2.8.8 hdrstop).

Use the -xpch option to create a precompiled-header file and improve your compilation time. The precompiled-header file is designed to reduce compile time for applications whose source files share a common set of include files containing a large amount of source code. A precompiled header works by collecting information about a sequence of header files from one source file, and then using that information when recompiling that source file, and when compiling other source files that have the same sequence of headers. The information that the compiler collects is stored in a precompiled-header file.

See Also:

• B.2.125 -xpchstop=[file|<include>].

• 2.8.8 hdrstop.

B.2.124.1 Creating a Precompiled-Header File Automatically

You can let the compiler generate the precompiled- header file for you automatically. Choose between one of the following two ways to do this. One way is for the compiler to create the precompiled-header file from the first include file it finds in the source file. The other way is for the compiler to select from the set of include files found in the source file starting with the first include file and extending through a well- defined point that determines which include file is the last one. Use one of the following two flags to determine which method the compiler uses to automatically generate a precompiled header:

B.2.124.2 Creating a Precompiled-Header File Manually

If you decide to create your precompiled-header file manually, you must start by first using -xpch, and specifying the collect mode. The compilation command that specifies -xpch=collect must only specify one source file. In the following example, the -xpch option creates a precompiled-header file called myheader.cpch based on the source file a.c:

cc -xpch=collect:myheader a.c

A valid precompiled-header filename always has the suffix .cpch. When you specify pch_filename, you can add the suffix or let the compiler add it for you. For example, if you specify cc -xpch=collect:foo a.c, the precompiled-header file is called foo.cpch.

B.2.124.3 How the Compiler Handles an Existing Precompiled-Header File

If the compiler cannot use the precompiled-header file, under -xpch=auto and -xpch=autofirst, it generates a new precompiled-header file. If the compiler cannot use the precompiled-header file under -xpch=use, a warning is issued and the compilation is done using the real headers.

B.2.124.4 Directing the Compiler to Use a Specific Precompiled-Header File

You can also direct the compiler to use a specific precompiled header. Specify -xpch=use:pch_filename to do this. You can specify any number of source files with the same sequence of include files as the source file that was used to create the precompiled-header file. For example, your command in use mode could look like this: cc -xpch=use:foo.cpch foo.c bar.c foobar.c.

You should only use an existing precompiled-header file if the following are true. If any of the following is not true, you should recreate the precompiled-header file:

• The compiler that you are using to access the precompiled-header file is the same as the compiler that created the precompiled-header file. A precompiled-header file created by one version of the compiler may not be usable by another version of the compiler.

• Except for the -xpch option, the compiler options you specify with -xpch=use must match the options that were specified when the precompiled-header file was created.

• The set of included headers you specify with -xpch=use is identical to the set of headers that were specified when the precompile header was created.

• The contents of the included headers that you specify with -xpch=use is identical to the contents of the included headers that were specified when the precompiled header was created.

• The current directory (that is, the directory in which the compilation is occurring and attempting to use a given precompiled-header file) is the same as the directory in which the precompiled-header file was created.

• The initial sequence of pre-processing directives, including #include directives, in the file you specified with -xpch=collect are the same as the sequence of pre-processing directives in the files you specify with -xpch=use.

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.

B.2.124.6 Screening a Header File for Problems

What makes a header file precompilable? A header file is precompilable when it is interpreted consistently across different source files. Specifically, when it contains only complete declarations. That is, a declaration in any one file must stand alone as a valid declaration. Incomplete type declarations, such as struct S;, are valid declarations. The complete type declaration can appear in some other file. Consider these example header files:

file a.h
struct S {
#include "x.h" /* not allowed */
};

file b.h
struct T; // ok, complete declaration
struct S {
   int i;
[end of file, continued in another file] /* not allowed*/

A header file that is incorporated into a precompiled-header file must not violate the following. The results of compiling a program that violates any of these constraints is undefined.

• The header file must not use __DATE__ and __TIME__.

• The header file must not contain #pragma hdrstop.

B.2.124.7 The Precompiled-Header File Cache

When the compiler creates a precompiled-header file automatically, the compiler writes it to the SunWS_cache directory. This directory always resides in the location where the object file is created. Updates to the file are preformed under a lock so that it works properly under dmake.

If you need to force the compiler to rebuild automatically-generated precompiled-header files, you can clear the precompiled-header file cache-directory with the CCadmin tool. See the CCadmin(1) man page for more information.

B.2.124.8 Warnings

• Do not specify conflicting -xpch flags on the command line. For example, specifying both -xpch=collect and -xpch=auto, or specifying both -xpch=autofirst with -xpchstop=<include> generates an error.

• If you specify -xpch=autofirst or you specify -xpch=auto without -xpchstop, any declaration, definition, or #line directive that appears prior to the first include file, or appears prior to the include file that is specified with -xpchstop for -xpch=auto, generates a warning and disables the automatic generation of the precompiled-header file.

• A #pragma hdrstop before the first include file under -xpch=autofirst or -xpch=auto disables the automatic generation of the precompiled-header file.

B.2.124.9 Precompiled-Header File Dependencies and make Files

The compiler generates dependency information for precompiled-header files when you specify -xpch=collect. You need to create the appropriate rules in your make files to take advantage of these dependencies. Consider this sample make file:

%.o : %.c shared.cpch
         $(CC) -xpch=use:shared -xpchstop=foo.h -c $<
default : a.out

foo.o + shared.cpch : foo.c
         $(CC) -xpch=collect:shared -xpchstop=foo.h foo.c -c

a.out : foo.o bar.o foobar.o
         $(CC) foo.o bar.o foobar.o

clean :
         rm -f *.o shared.cpch .make.state a.out

These make rules, along with the dependencies generated by the compiler, force a manually created precompiled- header file to be recreated if any source file you used with -xpch=collect, or any of the headers that are part of the precompiled-header file, have changed. This prevents the use of an out of date precompiled-header file.

You do not have to create any additional make rules in your makefiles for -xpch=auto or -xpch=autofirst.