Build Cache - Setting Up

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.

How to Enable Build Cache on Initiators

1. Go to Coordinator > Agent List.

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

3. Click Actions >  Allocate Build Cache. If you do not see this option, make sure the agents have Initiator licenses.

   

4. Click Actions > Build Cache Configuration and set the cache size and location . 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.

   

5. On each Initiator Agent machine, you define if you want it to use a local cache, a remote cache, or both in the Agent Settings > Initiator > Build Cache Client tab.

   

   You can enhance the output in the command line and Build Monitor with more details using the Include more details in build output checkbox. Using this option will adversely affect the performance of your builds, so only enable this option when you want to analyze your Build Cache efficiency, such as when using Build Cache for the first time, or when its efficiency drops.

Build Cache Size

The cache must be large enough to hold 2-3 builds results (objects, precompiled headers, libraries, and executables), from any builds that will contribute to this file cache. These requirements may vary depending on your environment.

You can find out how much space the build results of a project require by looking at the size of the build output folder(s).

Make sure that the filesystem holding the cache has enough free space to allow it to grow to its full size. Build Cache will stop filling the cache if the filesystem has less than 3% free space.

Once Build Cache is operational, you can view how much of your cache has been used by each build in the output tab of the Build Monitor, as well as the output you see in the command line.

Override the Build Cache Behavior for a Specific Build

Clients define which Endpoint(s) are used by default in the Agent Settings, but this can be overridden in the build command for a specific build. Flags are defined to allow you to override the build cache behavior in the BuildConsole for Make and Build Tools, BuildConsole for Visual Studio, and IBConsole for DevTools CLIs.

For example, if you are using the BuildConsole command to run Incredibuild for make and build tools and you want to use a remote cache, you would add the /buildcacheremoteserver=[ip address:port] flag.

This is especially useful for CI builds, where the build command is part of the overall CI script.

Setting the Build Cache Behavior for a Specific Project

You can also configure Build Cache behavior to match a specific project using a build configuration file. You can create a configuration file with settings for a particular project, and store the file together with the project source code. This allows you to use the same settings (e.g., a specific shared cache) consistently across multiple agents and CI machines. For details, see Modify Settings per Build using a Configuration File.

File Cache Cleaning

The file cache is optimized in various ways such as removing duplicate files and automatic cleanups. If the file cache fills up to 95% of it's capacity, it is automatically cleaned up by removing some of the content until it reaches 85% capacity.

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.

Monitoring 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.

If the hit rate is low, you can investigate the reason by enhancing the output to include information about each task. Go to Agent Settings > Initiator > Build Cache Client Settings and check the Include more details in build output box.

The build output will now include extensive information about each task, including whether is was a hit or miss, and in case of cache miss it will show you the reason for the miss. This will allow you, for example, to identify frequently changing header files or auto-generated code which is not cache-friendly (not deterministic).