Use Precompiled Header Files

When you use precompiled header files, the following restrictions apply:

To take full advantage of the precompiled header improvements, you may need to reorganize your source files. Using precompiled headers without organizing your source files can actually slow your compilation. There are several strategies you can use:

A precompiled header for each compilation unit
Use #pragma hdrfile in each primary source file to specify a distinct precompiled header object for each compilation unit.

Benefits
Each compilation unit has its own precompiled headers, so you can create the longest possible initial sequence for each compilation unit. You do not need to match the initial sequences in other compilation units, because you are not sharing the precompiled header object.

Drawbacks
If you change one header file, the compiler regenerates every precompiled header object that includes that header. This method can also require large amounts of disk space, since many precompiled headers are generated: a common header is precompiled separately for every compilation unit that includes it.
 
Single header file
Create a single header file that has include directives for every header in your application, and include it in each primary source file.

Benefits
You get the maximum possible benefit from using precompiled header files, and the maximum possible improvement in compile time. You have an exact match of the initial sequence for every compilation unit.

Drawbacks
If you are using a program maintenance utility such as the make utility, you will recompile the entire application every time you change even a single header file. For larger applications, this is probably unacceptable.
 
Global header file
Create a single header file that has include directives for those header files that are shared by many different compilation units. Include this global header file as the first step of the initial sequence in each primary source file, followed immediately by #pragma hdrstop.

Benefits
You get the benefit from precompiling common and shared headers, without having to recompile when you change less common headers.

Drawbacks
There is only one group of precompiled headers. Any headers outside of that group are compiled normally, and the precompiled header object must be regenerated every time you change even one of the common headers.
 
Grouping headers
1. Identify headers that are common throughout your source, and divide them into groups of associated headers. A header can be included in more than one group.
2. For each group, create a header that contains include directives for each header in the group.
3. In each primary source file, identify the precompiled header filename with #pragma hdrfile, include the appropriate group header, and end the initial sequence with #pragma hdrstop. If a source file does not use any of the precompiled header groups, make #pragma hdrstop the first directive in the file.

Benefits
Common headers are precompiled. Changing a header only affects the groups it belongs to, rather than requiring all precompiled headers to be regenerated. This method does not use as much disk space as having a precompiled header object for each compilation unit, and is more maintainable than a single global header file.

Drawbacks
Organizing headers into groups requires additional work.


Precompiled Headers
Initial Sequence of Headers


Create Precompiled Header Files