Build Cache - How Pre-Compiled Headers can Affect Efficiency

This feature is only available in Incredibuild's Enterprise and Business Plans and is currently in limited availability. For more details, speak to your Customer Success Representative.

Pre-compiled headers (PCH) are fully supported, however depending on how they are defined they may affect Build Cache performance. If a PCH contains frequently changing headers, the PCH will need to be re-compiled during most builds. This means that any source code that depends on the PCH will also need to re-compile, potentially leading to lower Build Cache hit rates.

The Role of Pre-Compiled Headers

Pre-compiled headers allow faster compilation of large projects where multiple source files use the same set of headers. These headers are pre-compiled (once) into an intermediate code, which is used in the compilation of multiple source files. This saves the compiler the need to pre-process all the headers over and over, reducing build time.

For example, consider source1.cpp through source25.cpp all use headers header1.h through header7.h. Pre-compiling all 7 headers into one PCH file once allows all 25 compilations to use the pre-compiled header, which is faster in most cases.

You can identify a pre-compiled header creation by the /YC option in the CL command.

The Issue with Pre-compiled Headers

Consider the above example, and let's assume that source13.cpp only needs header1.h (it doesn’t need header2.h through header7.h). This means that any change in header1.h should cause a re-compilation of source13.cpp.

However, if you use the pre-compiled header when compiling source13.cpp, then any change in header2.h causes a re-compilation of the pre-compiled header, which also cause a re-compilation of source13.cpp.

This can happen for incremental builds, and for Build Cache.

Inappropriate structure of pre-compiled headers may cause unnecessary re-compilations (i.e. cache misses). For example, if you place all the project headers in one giant pre-compiled header, then a change to any header (something that happens frequently) will cause a re-compilation of the entire project.

It is best not to mix in one pre-compiled header both frequently changing headers and those that rarely change.

Identifying Improperly Structured Pre-compiled Headers

If the builds show low hit rate continuously, enable the detailed build output (see Examining Cache Efficiency Further). If many cache misses show a pre-compiled header (PCH file) as the reason for the miss, then it’s possible that this pre-compiled header contains frequently changing headers and is included by most of the source files.

Best Practice for Using Pre-compiled Headers

Do not place frequently changing headers in pre-compiled headers. Certainly, avoid mixing those with headers that rarely change.