Build Cache - How Project Structure can Affect Efficiency

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

The elements used in your project, and the way your project is designed can have a major effect on Build Cache performance.

If your code has some of the elements below, we recommend running builds with and without these elements or configuration to determine how Build Cache is affected.

Using Different Build Tools

Each Visual Studio release has its own toolchain (compiler, linker, and other tools). If you are using a shared Build Cache across multiple Initiators, but different builds use different Visual Studio release, this may cause a high rate of cache misses. For example: if developers have different toolchain than the CI environment, they will not benefit from the contents that the CI places in the cache.

Using Different Build Configurations

Building for different targets (Debug vs. Release configurations, different CPU architectures, etc.) will generate different code. A build for a release configuration will not benefit from the cache contents generated with a debug configuration.

Build Cache also considers other factors that may affect the resulting artifacts. For example, command line options or environment variables may change the way that compilations and other tasks behave. Consider two compilations of the exact same code, one running with -DRUN1 and another running with -DRUN2. Build Cache considers these distinct tasks.

Managed C++

Managed C++ files are skipped by Build Cache by default. If you want to enable caching these files, speak to Customer Support.

Link Caching

Link caching is supported, but disabled by default as it would reduce Build Cache performance in most environments. However, if your project contains many DLL's or executables that rarely change, it might be beneficial to enable link caching. It can be enabled by speaking with your Customer Success Manager.

Pre-compiled Headers (PCH)

Pre-compiled headers 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.

For more details, see How Pre-Compiled Headers can Affect Efficiency.

Unity Builds

Unity builds are supported, but may affect Build Cache performance depending on the source doe unification scheme. If unrelated source code files are combined, where some of the files change frequently, then the entire combined compilation would need to run over and over. This may lead to lower Build Cache hit rates.

If your project uses unity builds, make sure you do not combine source files that change frequently with those that rarely change.

Automatically Generated Code and Ignoring Comments

Auto-generated code is fully supported, and typically does not reduce Build Cache efficiency.

Sometimes auto-generated code can be almost identical except for comments such as timestamps at the top of the files. These are ignored by Incredibuild when determining if we can provide a cache hit because they do not affect the results of compilation.

Note: If there are changes in comments after any line of code in the file, the file will be viewed as different and register a cache miss.

Use the Build Cache hit/miss report to analyze any unexpected cache misses that may result from auto-generated code.

Using Macros

Projects built with Build Cache behave exactly the same as-if they were built without Build Cache. The only exception is code that uses the following macros: __DATE__, __TIME__, __FILE__, and __TIMESTAMP__.

The aforementioned macros generate different values whenever the code that contains them is compiled. They are typically used in debug or versioning messages, such as the one presented when a program is run with a -version option, to show the time of compilation.

Build Cache will compile the code that contains these macros once, and store the resulting object file in the cache, with the compilation-time values embedded in the object file.

Later, when the same project is rebuilt, Build Cache will reuse the cache contents as-is, which means the resulting image will not produce the actual compilation-time value, but rather the original compilation-time value (when the object file was placed in the cache).