History: Precompiled headers

Source of version: 3 (current)

{TRANSCLUDE(page="tutbox")}In this tutorial you will learn how to speed up the compilation time of an Ogre application in Visual Studio, using precompiled headers.{TRANSCLUDE}

!Prerequisites
* This tutorial assumes you have knowledge of C++ programming and are able to setup and compile an Ogre application. See ((Setting Up An Application)) for instructions.

{maketoc}

!Introduction

Building a simple "hello world" Ogre application can take several seconds on a modern machine. Even when you haven't added your own code yet.
This waste of time
* breaks your workflow
* makes experimentation difficult
* is unnecessary
The solution: use precompiled headers in Visual Studio.
On an average laptop computer (WinXP, VC++2008 express, Core2Duo 1.5GHz, 2GB RAM) the build time for the Ogre ((Basic Tutorial 1)) goes from 20 seconds, to 1 second with precompiled headers. So that's 20 times faster! (:razz:)
{img fileId="1943" width="60%"}

!What are precompiled headers?

We won't explain here what precompiled headers are exactly, there are better places for that on the net.

Just know that precompiled headers are most useful when your project has lots of large includes to process. It is the case with Ogre. You tell Visual Studio which included headers rarely or never change, then Visual Studio will pre-compile them once, will save them in a file in your project folder, with a file extension of .pch (guess why (:wink:)), and will use this temporary output everytime you compile your project.

There will be no speed benefit when the headers are being pre-compiled, that is when you first compile your project, or when one of the headers to pre-compile has been changed (which should rarely or never happen), but after that, the gain is generally huge.

The good thing is, if one of the headers that have been pre-compiled change, Visual Studio will recreate the .pch file automatically for you. So once setup, precompiled headers won't get in your way.

!How to setup precompiled headers
Setting up precompiled headers is easy and takes only a few steps, especially if you're just starting a new project.

!!Create stdafx.h
stdafx.h is the header file where you include all those headers you need in your project that rarely or never change. These could be Ogre headers, or anything else you want. The name of this header file doesn't matter, but by convention we name it stdafx.h.
{CODE(wrap="1", colors="c++")}
// stdafx.h

// Ogre headers you need
#include <OgreException.h>
#include <OgreRoot.h>
#include <OgreConfigFile.h>
#include <OgreCamera.h>
#include <OgreViewport.h>
#include <OgreSceneManager.h>
#include <OgreRenderWindow.h>
#include <OgreEntity.h>
#include <OgreWindowEventUtilities.h>

// any other header can be included, as usual
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
#define WIN32_LEAN_AND_MEAN
#include "windows.h"
#endif
{CODE}

!!Create stdafx.cpp

Then, you need the associated .cpp file.
Create stdafx.cpp in your project. Again the name could be anything, but it is always best to follow conventions.
You can put anything you want in your stdafx.cpp, but the only requirement is to include stdafx.h as the first statement.
{CODE(wrap="1", colors="c++")}
// stdafx.cpp
#include "stdafx.h"

// anything you want after that
{CODE}

!!Include stdafx.h in every file of your project

Include stdafx.h
* as the first statement
* in ALL your .h and .cpp files

With large projects where you have hundreds of files, use some scripting, for example Python, to make sure this is done automatically for you.

In visual studio, you can do the following (make sure you select "All Configurations"):
 Configuration Properties -> C/C++ -> Advanced
Type "stdafx.h" in the "Force Include File" field; this will make the visual studio compiler insert the header file at the beginning of each file without having to include it manually.

!!Configure Visual Studio to use precompiled headers

Go to your project settings, make sure you select "All Configurations", then go to
Configuration Properties -> C/C++ -> Precompiled Headers,
and choose "Use Precompiled Header".
Make sure stdafx.h is the header file to be used, and leave the rest to the default value.
{img fileId="1944" width="75%"}
So now, Visual Studio will try to use precompiled headers the next time you build your project. But it won't work, since we don't have the precompiled header (the .pch file) yet. So let's tell Visual Studio to create it for us.

!!Configure Visual Studio to create precompiled headers

Finally, in the solution explorer, right-click on stdafx.cpp -> properties
choose "All Configurations",
then go to C/C++ -> Precompiled Headers,
choose "Create Precompiled Header", make sure stdafx.h is the header file to use, and leave the rest to the default value.
Click "OK".

We've just told Visual Studio to create the precompiled header when compiling stdafx.cpp.
The precompiled header will be (re)created with the next build:
* if it does not exist yet
* when one of the headers to precompile has been modified
* when stdafx.cpp has been modified

!Conclusion
Re-build your project. You shouldn't notice any difference since the precompiled header is first generated. It might even be slower than usual.
So try making a small change to one of your source files (for example add a space or semi colon in the main function), then build again:
enjoy the performance boost! (:cool:)
History: Precompiled headers

Source of version: 3 (current)

Search by Tags

Latest Changes

Search

Online Users
