Precompiled Headers

Watcom C/C++ supports the use of precompiled headers to decrease the time required to compile several source files that include the same header file. This chapter includes the following sections:

When to precompile header files

Using precompiled headers reduces compilation time when:

Because the compiler only uses the first include file to create a precompiled header, you may want to create a master or global header file that includes all the other header files that you wish to have precompiled. Then all source files should include this master header file as the first #include in the source file. Even if you don't use a master header file, you can benefit from using precompiled headers for Windows programs by using #include <windows.h> as the first include file, or by using #include <afxwin.h> as the first include file for MFC applications.

The first compilation - the one that creates the precompiled header file - takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled header.

You can precompile C and C++ programs. In C++ programming, it's common practice to separate class interface information into header files that can later be included in programs that use the class. By precompiling these headers, you can reduce the time a program takes to compile.

Although you can use only one precompiled header (.pch) file per source file, you can use multiple .pch files in a project.

Creating and using precompiled headers

Precompiled code is stored in a file called a precompiled header when you use the precompiled header option (-fh or fhq) on the command line:

  • The -fh option causes the compiler either to create a precompiled header or use the precompiled header if it already exists.
  • The -fhq option is similar, but prevents the compiler from issuing informational or warning messages about precompiled header files.

The default name of the precompiled header file is one of wcc.pch, wcc386.pch, wpp.pch, or wpp386.pch (depending on the compiler used). You can also control the name of the precompiled header that's created or used with the -fh=filename or -fhq=filename (``specify precompiled header filename'') options. For example, 

    -fh=projectx.pch
    -fhq=projectx.pch

-fh[q] (precompiled header) option

The -fh option instructs the compiler to use a precompiled header file with a default name of wcc.pch, wcc386.pch, wpp.pch, or wpp386.pch (depending on the compiler used) if it exists, or to create one if it does not. The file is created in the current directory. You can use the -fh=filename option to change the default name (and placement) of the precompiled header. Add the letter q (for ``quiet'') to the option name to prevent the compiler from displaying precompiled header activity information.

The following command line uses the -fh option to create a precompiled header: 

    wpp -fh myprog.cpp
    wpp386 -fh myprog.cpp

The following command line creates a precompiled header named myprog.pch, and places it in the /projpch directory: 

    wpp -fh=/projpch/myprog.pch myprog.cpp
    wpp386 -fh=/projpch/myprog.pch myprog.cpp

The precompiled header is created and/or used when the compiler encounters the first #include directive that occurs in the source file. In a subsequent compilation, the compiler performs a consistency check to see if it can use an existing precompiled header. If the consistency check fails then the compiler discards the existing precompiled header and builds a new one.

The -fhq form of the precompiled header option prevents the compiler from issuing warning or informational messages about precompiled header files. For example, if you change a header file, the compiler will tell you that it changed, and that it must regenerate the precompiled header file. If you specify -fhq then the compiler just generates the new precompiled header file without displaying a message.

Consistency rules for precompiled headers

If a precompiled header file exists (either the default file or one specified by the -fh=filename option), it's compared to the current compilation for consistency:

  • The current compiler options must match those specified when the precompiled header was created.
  • The current working directory must match that specified when the precompiled header was created.
  • The name of the first #include directive must match the one that was specified when the precompiled header was created.
  • All macros defined prior to the first #include directive must have the same values as the macros defined when the precompiled header was created. A sequence of #define directives doesn't need to occur in exactly the same order because there are no semantic order dependencies for #define directives.
  • The value and order of include paths specified on the command line with -i options must match those specified when the precompiled header was created.
  • The timestamps of all the header files (all files specified with #include directives) used to build the precompiled header must match those that existed when the precompiled header was created.

If these conditions aren't met, a new precompiled header file is created, and the new file overwrites the old.