/Yu (Use precompiled header file)

Instructs the compiler to use an existing precompiled header (.pch) file in the current compilation.

Syntax

/Yu[filename]

Arguments

filename
The name of a header file, which is included in the source file using a #include preprocessor directive.

Remarks

The name of the include file must be the same for both the /Yc option that creates the precompiled header and for any later /Yu option that indicates use of the precompiled header.

For /Yc, filename specifies the point at which precompilation stops; the compiler precompiles all code though filename and names the resulting precompiled header using the base name of the include file and an extension of .pch.

The .pch file must have been created using /Yc.

The compiler treats all code occurring before the .h file as precompiled. It skips to just beyond the #include directive associated with the .h file, uses the code contained in the .pch file, and then compiles all code after filename.

On the command line, no space is allowed between /Yu and filename.

When you specify the /Yu option without a file name, your source program must contain a #pragma hdrstop pragma that specifies the file name of the precompiled header, .pch file. In this case, the compiler will use the precompiled header (.pch file) named by /Fp (Name .pch file). The compiler skips to the location of that pragma and restores the compiled state from the specified precompiled header file. Then it compiles only the code that follows the pragma. If #pragma hdrstop doesn't specify a file name, the compiler looks for a file with a name derived from the base name of the source file with a .pch extension. You can also use the /Fp option to specify a different .pch file.

If you specify the /Yu option without a file name and fail to specify a hdrstop pragma, an error message is generated and the compilation is unsuccessful.

If the /Ycfilename and /Yufilename options occur on the same command line and both reference the same file name, /Ycfilename takes precedence, precompiling all code up to and including the named file. This feature simplifies the writing of makefiles.

Because .pch files contain information about the machine environment and memory address information about the program, you should only use a .pch file on the machine where it was created.

For more information on precompiled headers, see:

To set this compiler option in the Visual Studio development environment

  1. Specify /Yc (Create precompiled header file) on a .cpp file in your project.

  2. Open the project's Property Pages dialog box. For details, see Set C++ compiler and build properties in Visual Studio.

  3. Select the Configuration Properties > C/C++ > Precompiled Headers property page.

  4. Modify the Precompiled Header property, the Create/Use PCH Through File property, or the Create/Use Precompiled Header property.

To set this compiler option programmatically

Example

If 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
...

is compiled by using the command line CL /YuMYAPP.H PROG.CPP, the compiler doesn't process the three include statements. Instead, it uses precompiled code from MYAPP.pch, which saves the time involved in preprocessing all three of the files (and any files they might include).

You can use the /Fp (Name .pch file) 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, as in the following example:

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 #include "MYAPP.h"* directive.

See also

MSVC compiler options
MSVC compiler command-line syntax