Build Cache

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.

Overview

Build Cache saves time and resources by reusing portions of previous outputs. 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 on your local machine to drastically reduce build times without impacting your bandwidth.

Build Cache requires additional resources and has specific System Requirements.

Limitations

  • Build cache can only be used with Visual Studio 2017 and higher.

  • Build cache only supports msbuild builds using the cl toolset (cl.exe).

How is Build Cache Different from the Helper Cache

When Helpers are given a task, the 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 (files do not need to be re-transferred and tasks do not need to be rerun).

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. Build Cache lets you store 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.

Build Cache Clients, Endpoints, and Cache Location

Build Cache is stored and managed in Build Cache Endpoints. Build Cache Endpoints can be hosted on any Incredibuild Agent. Initiator Agents accessing the Build Cache are called Build Cache Clients. An Endpoint and Client can be on the same agent.

You can define if a Client contributes to the cache or just reads from it.

Clients define a single Endpoint to be used by default, but this can be overridden in the build command if you want to use a different Endpoint for this build.

By default, the Build Cache Endpoint is the localhost of the Build Cache Client. This is called using a local Build Cache.

To implement a shared Build Cache, you assign multiple Clients to connect to the same Endpoint.

Deployment Examples

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 (shared), 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.

Shared Cache refers to using a single Agent to host the Build Cache Endpoint. Multiple Initiator Agents contribute and benefit from the same build cache. However, only one Initiator can edit/write to the cache at any given time.

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 Does Build Cache Work? 

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.

You can define if an Agent contributes to the cache or just reads from it in the Agent Settings. However , each Endpoint can only process content from one build at a time. If two builds attempt to write to the same Endpoint at once, only the content from the first build will be added to the cache.

File Cache Size and Cleaning

You define the size of the file cache for each Endpoint in the Agent Settings > Build Cache Endpoint > File Cache > Size Limit setting. The size limit should be 2-3 times the size of the output of all of the builds that will contribute to this file cache, but the requirements may vary depending on your environment.

The file cache is optimized in various ways such as removing duplicate files and automatic cleanups. If the file cache fills up, it is automatically cleaned up by removing around 40% of the content. You can manually clear the cache as well in the Agent Settings of the Build Cache Endpoint.

You can view how much of your cache has been used in the output tab of the Build Monitor, as well as the output you see in the command line.

How to Assign Build Cache Licenses

A special Build Cache license must be assigned to every initiator that will use Build Cache.

  1. Go to Coordinator > Agent List.

  2. Select every initiator agent that you want to enable Build Cache.

  3. Click Actions > Build Cache License > Allocate License.

Note: You can also assign a license to a single initiator using the options (...) menu next to each agent.

How to Configure a Build Cache Client

By default, as soon as a Build Cache license is allocated, the Agent is automatically configured to be a Build Cache Client. You can edit the Build Cache Client settings in the Agent Settings > Build Cache Client > General tab.

You define which Endpoint to use by default in the Endpoint field. You can override this in the build command to use a different Endpoint as well.

By default, every Agent that enables Build Cache functions as a client as well as a contributor (meaning that builds run on the client are saved as part of the build cache). If you do not want a particular Agent to contribute, disable the Cache contributor option.

As a best practice, builds that change less over time get the most value from being cached, and dynamic builds get the less value. Applying this generally, CI pipelines should be cache contributors and developer machines should be cache readers (disabled as cache contributors).

You can enhance the output in the command line and build monitor with more details using the Include more details in build output checkbox.

How to Configure a Build Cache Endpoint

  1. On the initiator machine, go to Agent Settings > Build Cache Endpoint > General and verify that the service is currently running.

  2. A database is automatically installed during Incredibuild's installation. If the folder requires credentials, specify them here.

  3. Define the size of your File Cache. If the folder requires credentials, specify them here.

  4. You can also modify the folder and file cache size in the Coordinator's Agent List. Select an Initiator Agent, open the options menu, and select Build Cache Configuration. This can be done at scale by selecting multiple agents and using the Actions menu.

Verifying the Effectiveness of Build Cache

Details of how much time was saved from using the Build Cache is included in the output of all of your builds. This can be seen in the output tab of the Build Monitor, as well as the output you see in the command line.

You can also see information in the Build Monitor graphs.

  • Tasks to cache are tasks that were executed and are candidates to be added to the Build Cache for future builds.

  • Cache hits are tasks that were retrieved from the Build Cache instead of being executed.