The 25 days of C++mas - December 7 - Precompiled Header Files

Posted by on in Blogs
C++Builder XE3 provides support for pre-compiling the header files used in your C++ applications. Creating and using precompiled headers can do two major things for you: 1) it can reduce the compilation time of C++ files, 2) it can reduce the number of lines of code that the compiler must process (in some cases, by several orders of magnitude). The IDE automatically generates a PCH.h file for every new C++ project for any target platform (Mac OS X, 32-bit Windows, or 64-bit Windows). You can see the PCH.h file as a node in the Project Manager:

You do not have to use the PCH.h file that is generated for you, but if you want to use a precompiled header with your application, you should edit and use the PCH.h file. The compilers will automatically use the PCH.h file. Using a precompiled header file on 64-bit Windows is different from using precompiled headers with BCC32.

The 32-bit C++Builder compiler has always had the default behavior of generating precompiled headers for you, and this behavior is not changed. Now, however, you can tell BCC32 to use the PCH.h file shown in the Project Manager if you simply #include the PCH.h file (followed by #pragma hdrstop;) in each source file in your project. You should, of course, edit the contents of the PCH.h file to #include all the headers needed in your project.

Creating a Precompiled Header for the C++Builder 64-bit compiler

The following procedure shows how to use precompiled headers in your C++ 64-bit Windows applications. The 64-bit Windows compiler accepts only one header file per project. Following the steps below, you create the single header file and use it as a precompiled header for a source file, in a 64-bit C++ project.

  • Step 1: Create a C++ application ( either Console Application, VCL or FireMonkey). You can use either a brand new application or an application that you created in a version of C++Builder prior to XE3; that is, you could have made changes and additions to the application since it was created or it could be a legacy application created in an earlier version of C++Builder).

  • Step 2: Select File > Save All. Save all the files of the project to a desired location.

  • Step 3: In the Project Manager, enable the 64-bit platform and the PCH file: a) Right-click Target Platforms, select Add Platform and select 64-bit Windows. b) Right-click your project's PCH.h file and make sure that Use for precompiling is enabled.

  • Step 4: Edit the header file (PCH.h) file, and include the header files that you want to precompile. The PCH.h file should end with: #pragma hdrstop

  • Step 5: Save the PCH.h file in the project folder.

  • Step 6: In the Project Manager, right-click the source file that you want to include the PCH.h precompiled header, and select Edit local options from the context menu.

  • Step 7: Press F9 to run the project.

Precompiled Header Files - Things to consider

When used indiscriminately, precompiled headers can actually increase compilation time. Watch out for the following potential issues:

  • Simple compilation units that refer to very few symbols may compile faster without precompiled headers. Having them use a precompiled header might result in slower compilation.

  • If a header that changes regularly is part of the precompiled header, the overhead of constantly recreating the precompiled header might offset any gains from using one.

  • For very large precompiled headers, the I/O involved in reading or updating the file might offset the gains of precompiled headers.

Some headers are not good candidates to include in a precompiled header. Use the following guidelines to determine whether a header should be precompiled.

  • Do not include the following types of headers in a precompiled header:

  • Any header that is not already properly guarded. That is, the header file does not contain preprocessor guards (using #define) that would ensure that it is *seen* only once by the compiler even if it is included multiple times.

  • A header that contains code that relies on certain macros that only a few compilation units define.

  • Any header that is undergoing frequent or regular changes.

  • Any header that contains any data. The compiler generates a message about headers that contain data and therefore cannot be part of a precompiled header.

Precompiled headers can hide incorrect code. For example, a .cpp file that fails to explicitly include a needed header might compile with no errors when using a precompiled header that includes the missing header file but fail when the precompiled header is disabled. It's a good idea to build without precompiled headers every once in a while to ensure that your source correctly includes all necessary headers.

C++ Precompiled Headers Project Options

In the IDE, you can use the Project > Options > C++ Compiler > Precompiled headers project options dialog box to set C++ Compiler Precompiled headers options.  You can find additional details about the precompiled headers project options dialog box on the Embarcadero DocWiki at

The Precompiled Header Wizard is currently designed for use with 32-bit Windows C++. This wizard does not produce the format used by 64-bit Windows C++ at this time.

CodeRage 7 C++ Conference, December 10-12, 2012

The CodeRage 7 C++ conference starts next Monday, December 10, 2012 at 6am Pacific Standard Time (14:00 UTC).  There are 3 days of C++ sessions including my special live, online conversation with Bjarne Stroustrup at 8am PST (16:00 UTC) on Monday.  Some of the C++ sessions you won’t want to miss are included in my blog post on November 21 -

Happy C++mas!

During the first 25 days of December leading up to Christmas, I will blog about the upcoming release of the C++Builder 64-bit compiler for Microsoft Windows and C++Builder XE3support for building VCL and FireMonkey 2 applications.

Gold User, Rank: 1, Points: 2466
David Intersimone (known to many as David I.) is a passionate and innovative software industry veteran-often referred to as a developer icon-who extols and educates the world on Embarcadero developer tools. He shares his visions as an active member of the industry speaking circuit and is tapped as an expert source by the media. He is a long-standing champion of architects, developers and database professionals and works to ensure that their needs are folded into Embarcadero's strategic product plans. David holds a bachelor's degree in computer science from California Polytechnic State University at San Luis Obispo, California.


Check out more tips and tricks in this development video: