Build Cache - How Pre-Compiled Headers can Affect Efficiency

This feature is only available in Incredibuild's Enterprise and Business Plans.

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.