Build Cache - Overview

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.

Build Cache saves time and resources by reusing portions of previous builds. As you run builds, we store the outputs in a file cache. When future builds are run, we check the cache to avoid regenerating portions of the build that have not changed.

This can have a major impact, as you can reuse previous build data stored in Build Cache to drastically reduce build times without impacting your bandwidth.

In order to achieve this, Build Cache has specific System Requirements and Supported Tools.

Benefits and Use Cases

  • Boost developer productivity from anywhere
    Stop running builds from scratch every time you switch branches, even when they've already been built elsewhere. Build Cache automatically stores previous build data and drastically reduces local build times.

  • Build from home without impacting your speed
    Working from home affects build speeds due to limited upstream bandwidth. Build Cache lets you rely more on downstream bandwidth, giving you greater speed and better performance when starting new builds.

  • Use cached data between CI builds
    Use Build Cache to share build artifacts generated by one CI server with another to save time and resources. Bring the incremental build experience to your CI.

  • Reuse CI results for faster development builds
    Instead of having to incorporate every single change made when restarting a build from version control, Build Cache lets developers reuse outputs generated on later CI builds and workflows, even when working on prior versions.

License Model

Build cache uses special licenses called Cache Cores. One Cache Core is consumed whenever using the Build Cache saves you one hour of a helper core's execution. Cache Cores are reusable and are refreshed every hour.

If you run out of Cache Cores, data is still written to the cache, but cannot be read until your Cache Cores are refreshed. You can view information about your license usage at the top of the Agent List.

If you are using Incredibuild Cloud in addition to an on-prem license, see Using Build cache with Incredibuild Cloud to learn about how these licenses interact.

How Build Cache Works 

Build Cache examines each task (compilation or other) and decides whether it can use existing cache contents, or the task needs to run. It assumes that if the inputs for the task (source files, header files, pre-compiled headers, etc.) did not change, then the resulting artifact (object file, PDB, etc.) will not have changed in a significant way either. There is an assumption that most tasks are deterministic, and that the entire build is deterministic. Whatever part of the build is not deterministic will need to be re-run for every build and will not be improved by Build Cache.

A deterministic build is a process of building the same source code with the same build environment and build instructions producing the same binary in two builds, even if they are made on different machines, build directories and with different names. They are also sometimes called reproducible or hermetic builds if it is guaranteed to produce the same binaries even compiling from different folders.

Creating and Managing the Cache

Builds are often processed in tree-like structures based on the dependencies in your code. The files in Layer 1 are used to create the files in Layer 2, Layer 2 is used to create the files in Layer 3, and so on until the final output is produced.

As builds are processed, Incredibuild saves details of the process for future use. Each part of the process that is generated from other files is saved as a pair of input files and output files in the cache. If you run a build after changing some of the files, Build Cache can reuse the portions that are identical to prevent parts of the process from running.

The build cache is optimized in various ways such as removing duplicate files and automatic cleanups.

Changing Source Code

When your source files change, obviously the compilation must be re-run. Build Cache identifies that the contents of the source file do not match anything in the cache and declare this a "cache miss". At this point, the task must be rerun as part of your build and the new results are stored in the Build Cache for future use.

The same thing happens if a header file which the source file includes is changed, or a header included by a header, and so on. Build Cache knows exactly which files were read in each task and can validate they did not change. The more your code changes, the less cache-hits Build Cache will find.

Build Cache is aware of the project folder structure. However, the root folder for the project does not need to be identical on all Initiators: one Initiator may place the project at C:\Project and anther Initiator may use D:\Project. They can use a shared cache efficiently.

Build Cache Components

An Incredibuild Initiator Agent using Build Cache is called a Build Cache Client. An Incredibuild Agent storing and serving Build Cache is called a Build Cache Endpoint. The Build Cache service is installed on every Incredibuild Agent. An Agent becomes an Endpoint when one or more clients use it as an Endpoint.

By default, any Initiator Agent that has Build Cache enabled acts as it's own Endpoint. You can work with a remote Endpoint that can be shared across multiple Clients by changing the Agent's Build Cache Client settings.

Deployment Types

Build cache can be deployed in different ways depending on how your Clients connect to Endpoints. A single Client can function as its own Endpoint (local), multiple Clients can connect to a single Endpoint (remote), and more complex or dynamic deployments are possible as well.

Local Cache refers to using the same Initiator Agents to host the Build Cache Endpoint and Build Cache Client. This means that each agent can only benefit from the cache of builds that were previously run on the same machine. This can be ideal if you are not sharing code with other developers, or if you are working from home with limited bandwidth.

Remote Cache refers to using a single dedicated Agent to host the Build Cache Endpoint. Multiple Initiator Agents contribute and benefit from the same build cache.

You can enable both Local and Remote Caches. If both are enabled, Incredibuild uses the following logic for each task whenever a build is run:

  1. Check the local cache. If there is a cache hit, it is used. If there is a cache miss, the remote cache is checked.

  2. If there is a remote cache hit, use the data and update the local cache.

  3. If there is no remote cache hit, run the task and update the local cache.

In this deployment, you have more than one Build Cache Endpoint that is used by more than one Client. The Clients define a default Endpoint, but you can override this in the build command to use a different Endpoint as well. This is ideal for CI environments that are running different builds. They can dynamically fetch the context of the build they are running and use the appropriate Endpoint.

How is Build Cache Different from the Helper Cache

When Helpers are given a task, the input files (e.g. source and header files) they need to process are stored in the Helper Cache. If the same exact file is sent, the Helpers still process it again, but the files do not need to be re-transferred.

In Build Cache, the Initiator recognizes tasks that have already been processed, and they are skipped entirely. Output files (e.g. object files) do not need to be re-transferred and tasks do not need to be rerun.

Supported Tools

  • Build Systems: All build systems supported by Incredibuild.

  • Compilers: 

    • cl.exe (Visual Studio 2012 or higher)

      • Support for 2012-2015 is limited, and requires adding a flag during builds

    • clang-cl.exe (beta)

    • prospero-clang.exe (PlayStation PS5 SDK)

    • orbis-clang.exe (Playstation PS4 SDK)

    • clang ++ (Nintendo Switch SDK)

  • Linker: link.exe (Visual Studio 2012 or higher). Link.exe support in Build Cache is disabled by default. Enable it if your project has many DLL's or executables that rarely change. Support for 2012-2015 requires adding a flag during builds

  • /Z7 is fully supported. /Zi is automatically converted to /Z7 when Build Cache is used