Organizing Your C Source for Precompiled Headers

Precompiled headers can reduce the time required to compile C source. However, to get the most improvement, 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 to organize your files:

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.

Use a 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: You may have to recompile the entire application every time you change even a single header file. For larger applications, this is probably unacceptable.

Create a 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.

Group headers
Do the following:

  1. Identify headers that are common throughout your source, and divide them into smaller 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 file name 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, put #pragma hdrstop as 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: Requires additional work to organize headers into groups.

Examples
Example of an Initial Sequence for Precompiled C Headers
Example Matching Initial Sequences for C Precompiled Headers
Examples of Multiple Initial Sequences for C Precompiled Headers



C Compilation
Precompiled C Headers


Set Build Options
Build


C File Options