Build Cache - Basic Settings and Configuration

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

How to Enable and Configure Build Cache

1. Enable Build Cache on your Initiator Agents:

   1. If you are using floating Initiators and want to enable Build Cache on all of them by default, go to Coordinator Manager > Settings > Agents and check Automatic Build Cache Allocation.

      

   2. If you are using fixed Initiator Agents, or just want to control which floating agents have Build Cache:

      1. Go to Coordinator Manager > Agent List and select the desired Initiators.

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

         

2. On each Initiator Agent machine (you can configure them together or individually), define if you want it to use a local cache, a remote cache.

   1. In the Agent List, select the desired Initiators.

   2. Click Actions >  Enable Build Cache and select Local Cache, Shared Cache, or both. If you select Shared Cache, specify the location of the machine that has the Shared Cache.

      

3. Select all of the Initiators that have Build Cache and click Actions > Build Cache Configuration to set the cache size and location of the cache that exists on the selected machines. 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. For more details, see below.

   

Customizing Build Cache Settings for Specific Builds or Projects

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.

Use Cases and Best Practices

Developer Machines - Working from home or in the office

For most machines, we recommend enabling both local and remote cache. This assumes that these machines are persistent (laptops, desktops, or persistent VMs), and that there are other machines (typically CI servers) that use only the remote cache and are writing to that cache. If no machines are writing exclusively using the shared cache, developer machines should only use local cache.

When you enable both local and remote cache on an agent, that agent can only contribute to the local cache.

When a build is run, the local cache is checked first. If there is a hit, the cache is used. Otherwise, Incredibuild checks the remote cache. If there is a hit, we use it and also update the local cache so that future executions will use the local cache and reduce network traffic. This is particularly useful when working from home due to the lower upload bandwidth. If there are no hits, the build is run and the information is added to the local cache.

CI Machines

CI builds can typically be considered a “source of truth”: they usually contain code that is trustworthy, stable, and is shared by other CI builds and developers. For the most part, code that is merged so that it is part of a CI build will change less often. As a result, its compiled artifacts (object files, etc.) are likely to be used by others, improving Build Cache efficiency and faster builds for everyone. When using machines for CI use cases, we recommend only using remote (shared) cache. The machines will then both read and write to the remote cache. This ensures that their content will be available even if the CI machine is torn down (as is done in many use cases). This also allows this cache to be shared with your developers working from home or in the office.

Remote (Shared) Cache Endpoints

For endpoints that host a remote cache, use the following recommendations to maximize performance: 

• Install Incredibuild on an Agent, but do not assign any licenses to the Agent so that it does not assist with or initiate any builds.

• Do not run other programs on this machine, it should be a dedicated machine.

• Add an Agent description to clearly identify the Agent as your remote cache.

Managing the Build Cache Size and Storage

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.

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.