On Solaris, for instance, Example 1 prints "James Brown." While you might guess that when using the precompiled headers in Visual C++, the program would print "Charlie Daniels," in fact, it instead prints "Charlie Brown." This command line creates a precompiled header when using Visual C++:

cl /c /Ycpch.h pch.cpp

The /Yc option instructs Visual C++ to create a precompiled header, checkpointing the compilation state after pch.h is processed. In Example 1, the precompiled data is kept in a file called "pch.pch" and includes the definition of STR1 and all of iostream.h. Compilation continues after pch.h is processed, but later data is not written to pch.pch. In this example, the definition of STR2 is not included in pch.pch.

The precompiled header data may be used with the following command:

cl /Yupch.h main.cpp

The /Yu option instructs Visual C++ that the source file will attempt to include pch.h. When the include statement is processed, the compiler uses the precompiled data in pch.pch rather than processing pch.h. In Example 1, STR1 is defined as "Charlie" in the precompiled header. STR2 is defined as "Brown" from main.cpp. "Charlie Brown" is printed.

Within the Microsoft development environment, Visual C++ precompiled header specifications for a project can be viewed by pressing Project, Settings, the C/C++ tab, and finally, the category Precompiled Headers.

Typically, one C++ file in the project is set to "Create precompiled header file (.pch) through header <some_filename.h>." This is the first file built for the project. When the debug configuration is built, the data from the compilation of this file, up to and including "<some_filename.h>," is placed in a file named "WinDebug/your_project_name.pch."

Most files will be set to "Use precompiled header file (.pch) through header: <some_filename.h>." This tells Visual C++ that when it parses #include <some_filename.h>, it should disregard "some_filename.h" and insert the precompiled header.

To ensure compatibility, do not put anything in pch.cpp, except #include <pch.h>. As in Example 2, move the definitions of STR1 and STR2 into pch.h using this approach. The performance benefits from the use of precompiled headers is not diminished, the code is easier to read, and the results are consistent with normal C++ semantics.

I was not able to find any documentation from Microsoft that specifically recommends the structure for precompiled header files. However, the comments that Visual C++ inserts into AppWizard projects are consistent with my approach. When Microsoft Visual C++ 6.0 creates a new Win32 Application project (A typical "Hello World" application), it creates a file called "stdafx.h" with the following text:

// stdafx.h : include file for standard system // include files,

// TODO: reference additional headers your // program requires here

It creates a file, "stdafx.cpp," with the text:

// stdafx.cpp : source file that includes just // the standard includes

#include "stdafx.h"

// TODO: reference any additional headers // you need in STDAFX.H

// and not in this file

Clearly, my approach is consistent with Microsoft's architecture, yet still enables compatibility with Solaris.

DDJ

(a) pch.h
// Solaris JUST includes this file.
#include 

(b) pch,cpp
// Visual C++ puts the start of this file into the
//				      precompiled header.
#define STR1 "Charlie "
#include "pch.h"
#define STR2 "Daniels"

(c) main.cpp
#include "pch.h"

#ifndef STR1
#  define STR1 "James "
#endif

#ifndef STR2
#  define STR2 "Brown"
#endif

int main()
{
    cout << STR1;
    cout << STR2;
    return 0;
}

Example 1: This program has different behaviors on NT and UNIX: (a) pch.h; (b) pch.cpp; (c) main.cpp.

(a) pch.h
// Sun Forte C++: The contents of this file will be
//           included through normal C++ semantics.
// MS Visual C++: The contents of this file will be 
//           included through the precompiled header.
#include <iostream.h>
#define STR1 "James "
#define STR2 "Brown"

(b) pch.cpp
// Do add anything to this file!
// Any additional code should be placed in pch.h.
#include "pch.h"

(c) main.cpp
#include "pch.h"

int main()
{
	cout << STR1;
	cout << STR2;
	return 0;
}