With the /Yc, /Yd, /Yu, and /Fp options and the hdrstop pragma, Microsoft C/C++ provides the ability to precompile code. Precompilation, especially when used the fast compile (/f) option, can dramatically reduce compile time for code that is frequently compiled without modification.
You can precompile a stable body of code, which can be header files and all or part of source files—including inline code. Precompilation works with both C and C++.
This process saves the state of a compilation (including CodeView information) in a precompiled header file with a .PCH extension. In later compilations, the compiler simply restores the saved compilation state from a precompiled header file.
Creation or use of precompiled headers is governed by the compilation options described in the next three sections. In many cases, the behavior dictated by these options is affected by the hdrstop pragma. For more information on both precompiled headers and the hdrstop pragma, see “Using Precompiled Headers” in the Programming Techniques manual. The related option to specify precompiled header filenames (/Fp) is described earlier in this chapter.
/Yc (Create Precompiled Header)
/Yc[[filename]]
The “create precompiled header” option (/Yc) instructs the compiler to create a precompiled header (.PCH) file that represents the state of compilation at a certain point. No space is allowed between /Yc and filename.
If you specify a filename with the /Yc option, it instructs the compiler to create a precompiled header in which to save the state of the compilation up to and including the preprocessing of the named include file. Consider the following code:
#include <afxwin.h> // Include header for class library
#include "resource.h" // Include resource definitions
#include "myapp.h" // Include information specific to this app.
...
When compiled with the command
CL /YcMYAPP.H PROG.CPP
the compiler saves all the preprocessing for AFXWIN.H, RESOURCE.H, and MYAPP.H in a precompiled header file called MYAPP.PCH.
If you specify the /Yc option with no filename, the entire source file—including every included header file—is compiled. The state of the compilation is saved to a file with the base name of the source file and a .PCH extension.
Because precompilation is most useful for compiling a stable body of code for use with a body of code that is under development, you will want to focus the precompilation process by using /Yc with its filename argument or by putting a hdrstop pragma in your source file.
#pragma hdrstop[[("filename")]]
If a C or a C++ file contains a hdrstop pragma, the compiler saves the state of the compilation up to the location of the pragma. The compiled state of any code that follows the pragma is not saved.
The hdrstop pragma cannot occur inside a header file. It must occur in the source file at the file level; that is, it cannot occur within any data or function declaration or definition.
The hdrstop pragma is ignored unless either /Yu or /Yc is specifed without a filename.
Use filename to name the precompiled header file in which the compiled state is saved. The filename must be a string (enclose it in quotation marks), and it must be enclosed in parentheses. A space between hdrstop and filename is optional. Note that you can also use the /Fp option to name the precompiled header file. If filename is not specified, the resulting filename is given the base name of the source file with a .PCH extension. The /Fp option is discussed earlier in this chapter.
Using hdrstop Without a Filename
If no filename is given with the hdrstop pragma, the name of the precompiled header file is derived from the base name of the source file with a .PCH extension.
/Yd (Include Debugging Information)
The “include debugging information” (/Yd) option instructs the compiler to place a precompiled header file's debugging information (symbols and type information) into the precompiled header instead of the object file. The option takes no argument and has effect only if both the create precompiled header (/Yc) and the generate CodeView information (/Zi) options are in effect.
By default, any debugging information for a precompiled header is saved in the object file for which the precompiled header is created rather than in the precompiled header. In subsequent inclusions of this precompiled header, the compiler does not insert symbol information in the object file; rather, it inserts cross-references to the original object file. Therefore, no matter how many times the header is included in compilations, the debugging information exists only in one object file.
Although this default behavior results in faster compilation and reduces disk-space demands, it can be undesirable if you are distributing a debugging library. The /Yd option overrides this behavior so that complete debugging information is included in each object file.
/Yu[[filename]]
The “use precompiled header” option (/Yu) instructs the compiler to restore its state from a previous compilation using a precompiled header file. No space is allowed between the option and the filename.
If filename is specified, it must correspond to one of the header files included in the source file using the #include preprocessor directive. The compiler skips to the specified #include directive, restores the compiled state from the precompiled header file, and then compiles only code that follows filename.
Unless the /Fp option is used, the compilation state is restored from a file that has the same base name as the include file and a .PCH extension. Consider the following code:
#include <afxwin.h> // Include header for class library
#include "resource.h" // Include resource definitions
#include "myapp.h" // Include information specific to this app.
...
When compiled with the command line
CL /YuMYAPP.H PROG.CPP
the compiler does not process the three #include statements but restores its state from the precompiled header MYAPP.PCH, thereby saving the time involved in preprocessing all three of the files (and any files they might include).
You can use the /Fp option with the /Yu option to specify the name of the .PCH file if the name is different from either the filename argument to /Yc or the base name of the source file.
CL /YuMYAPP.H /FpMYPCH.PCH PROG.CPP
This command specifies a precompiled header file named MYPCH.PCH. The compiler uses its contents to restore the precompiled state of all header files up to and including MYAPP.H. The compiler then compiles the code that occurs after the MYAPP.H include statement.
When you specify the /Yu option without a filename, your source program must contain a hdrstop pragma that specifies the filename. The compiler skips to the location of that pragma, restores the compiled state from the precompiled header file specified by the pragma, and then compiles only code that follows the pragma. If the hdrstop pragma does not specify a filename, the compiler looks for a file with a name derived from the base name of the source file, with the .PCH extension.
If you specify the /Yu option without a filename and fail to specify a hdrstop pragma, an error message is generated and the compilation is unsuccessful.