manski's blog

Projects in Visual C++ 2010 – Part 3: Precompiled Headers

In this part of the “Projects in Visual C++ 2010” mini series another important aspect of C++ programming is explain: precompiled headers. Precompiled headers (or precompiled header files) in many cases significantly reduce the time needed to compile a project.

Here at work I have a C++ project with about 50 .cpp files in it. The project uses the Qt library and all files only include the absolute minimum of header files required. Without precompiled headers, compiling the project takes about 56 seconds. With precompiled headers, the compile time goes down to about 7 seconds. That’s eight times faster.

Related Articles:

The procedure described here only applies to Visual C++ (if I’m correct since version 6.0). However, other C++ compilers may provide similar functionality.

The Problem

The problem precompiled headers solve is the long compile time when compiling a C++ project. (Note that other languages such as Java or C# don’t have this problem.) The underlying problem is the #include <...> statement. This simply copies the whole content of the file included into the source file. While one header file may not be that big, it may also include other header files. When using a framework (such as Qt or even Win32), one include statement will import a huge amount of source code. And this huge amount is what takes so long when compiling a C++ project. Furthermore, if this huge amount gets included in every source code file, all of it has to be compiled again for every source file.

So, the idea is to (pre)compile these huge amount of source code once, and then reuse it in every source code file of the project. This drastically reduces the compile time required.

Specifying the precompiled header (stdafx.h)

To be able to use a precompiled header in Visual C++, one first needs to specify which headers shall be precompiled. Visual C++ only allows one precompiled header file per project. By default, it’s called stdafx.h. This name can be changed in the project settings under “C++” –> “Precompiled Headers” –> “Precompiled Header File”.

The limitation that only one precompiled header is allowed is no real limitation because you can include any header file from within the precompiled header. For example, a precompiled header may look like this (for using the Qt framework):

#pragma message("Compiling precompiled headers.\n")
#include <QtCore>
#include <QtXml>
#include <QtGui>

So when this header is precompiled, all included headers will be precompiled as well. Thus, the more of the headers you use in your project are specified here, the faster the other files in the project compile. Note that including more header files than are actually used is not a problem.

You may also note the #pragma statement on the first line. This is just “helper statement”. With it, every time the precompiled header is compiled, the specified message will be printed to the build output. If you see this message twice or more while compiling a single project, something is wrong. (In most cases you won’t see the message at all because the precompiled header is already compiled.)

Using the Precompiled Header

Whether to use a precompiled header or not can be specified per project as well as per file. When you want to use a precompiled header in a project, you usually say “Use” for the whole project and then exclude certain .cpp file that shall not use the precompiled header. Both options are in the same section – it just depends on whether you open the project settings or the file settings (both being available through their context menus).

To enable precompiled headers in a project (or file), open the project settings (or file settings) and select “Use” under “C++” –> “Precompiled Headers” –> “Precompiled Header”. Also make sure, that you’ve selected “All Configurations” from the “Configuration” dropdown field. (Note that the option “Create” will be used below.)

Enabling precompiled headers on project level

The next thing you need to do is to #include "..." the precompiled header file in every source file (.cpp). You shouldn’t (can’t?) include it in the header files (.h) but only in the .cpp file. Also, the include statement must be the first statement in the file (only comments or whitespace is allowed above it). This is because Visual C++ assumes that everything before the include statement is already compiled.

So the beginning of a .cpp file in your project may look like this:

// File with some fancy functions.
#include "stdafx.h"
#include "myfancefunctions.h"

Note that the name of the precompiled header file is the one you specified above (or “stdafx.h” by default).

Compiling the Header

By now, we’ve specified which headers are to be compile and where these headers will be used. The last step is to actually compile the precompiled header. Without this you’ll get a “Cannot open precompiled header file” error message when compiling the project.

For this you need to add a new .cpp file to your project. By convention, it has the same name as the precompiled header but that’s no strict requirement. This file only needs to contain one statement:

// stdafx.cpp
#include "stdafx.h"

Next, you need to go to the file’s settings (via context menu) and change the value of “Precompiled Header” from “Use” to “Create”.

Setting options for creating a precompiled header

That’s it. Now, when compiling the project again for the first time, the precompiled header will be created. After that, compiling the other source files should be significantly faster than before. Also the precompiled header will only be compiled on the first run. After that it won’t be compiled again (which would somehow defeat its purpose) unless either the “stdafx.cpp” or “stdafx.h” file is modified.


  1. Simon said: ∞

    Hey Sebastian,

    thanks for all the provided information! After 5 (happy) years with C# I am currently reactivating my poor C++ knowledge again for a realtime 3D application. Last week I was confused of waiting 3 minutes every time I built my QT project. I thought this is the way how hacker of native programs spend their time… ok, I was wrong

  2. Mark said: ∞

    This is very very helpful. Just a quick question. Do you have any tutorial on how to create COM dll ( that can be used in VB) in VS2010 c++.

  3. Romain said: ∞

    Thanks a lot for that, experienced in C++ on linux not on windows and VS 2010 is giving me a headache with all these properties trees and all these settings that if not well configured before the i.e. first time you compile your project etc … prevent you to compile anything!

    Sometimes I regret gcc and makefiles even if they look cryptic they’re rather easy to use.

  4. Fabrizio said: ∞

    Good tutorial. Can I make you a question?? Related to the precompilation of the headers, how the “pragma hdrstop” does work??

  5. Jeroen said: ∞

    Thanks for this very helpfull guide. It has reduced the total build time for my QT/MSVC project from 90 minutes to 42 minutes. What strikes me is that now about half of the build time is spent on moc’ing my source files. It seems that the precompiled headers are not being used while moc’ing. Is there a way to use it during the moc’ing procedure? I recon that would reduce my build time even more…

  6. Harshal Chaudhari said: ∞

    Extremely simple and easy to understand. Great work. Thanks a lot.

  7. Javier Noa said: ∞

    it’s cool your comment…thank you!!

Leave a Reply

Your email address will not be published. Required fields are marked *