# Caching

Overview

The caching feature of FASTBuild allows compilation results from one build to be shared with another. If the inputs are the same, the compilation can be replaced with a simple file copy.

Caching requires:

- Compatible compilation settings
- Configuration of cache location
- Activation of caching

There are some performance implications of the cache that should be considered for optimal benefit.

- Performance - GCC/SNC/Clang
- Performance - MSVC (Important!)

Compilation Settings

Some compilation settings are incompatible with caching. If any object cannot be safely cached, it will automatically be built without caching. A build can safely mix cacheable and uncacheable objects.

GCC/SNC/Clang

- No restrictions.

MSVC

- Z7 Debug format must be used. (Debug information embedded within obj, written to pdb at link time.)
- /ZW (Consume Windows Runtime) cannot be used.
- Precompiled Headers cannot be cached. They are machine-specific. (Object using PCH can be cached.)
- /clr (Managed C) cannot be used.

Cache Location

The cache location can be a local or network path, specified either by:

- The .CachePath property of the Settings function
- The FASTBUILD_CACHE_PATH Environment Variable

The Settings option overrides the Environment Variable.

Windows and UNC format paths are supported.

Activation

The cache can be activated by the use of:

- The -cache[read|write] command line argument
- The FASTBUILD_CACHE_MODE Environment Variable ('r', 'w' or 'rw')

Be sure to read the Performance Implications section for use of the best options.

Performance Implications

GCC/SNC/Clang
There are no adverse impacts on performance using the cache. The overhead is so low, it can be considered to be free in all situations.

MSVC
Microsoft's compiler has several implementation details that make optimal caching more difficult:

- The preprocessor is slow
- PCHs are machine-specific, and cannot be shared
- Objects built with PCH are tied to those machine-specific PCHs

The slow preprocessor (relative to GCC/SNC/Clang) simply means there is an overhead added to a build using the cache. As little as a single cache hit is usually enough to compensate for this, so this is not seen as a significant problem.

Precompiled Headers cannot be copied betwen machines, because they contain machine-specific information. (The MSVC compiler does a raw memory-dump of the PCH information, and relies on the specific environment of the original machine for subsequent use.) To work around this limitation in the MSVC toolchain, FASTBuild will automatically disable caching on PCH files and build them locally.

An object file using a PCH has debug information tied to that PCH. It cannot be safely combined with a PCH on another machine. To work around this limitation in the MSVC toolchain, FASTBuild will disable PCH usage when compiling objects that are to be written to the cache. This can add a significant overhead, which requires many cache hits to offset. If the cache is in read-only mode however, the object will be compiled using the PCH after a cache miss. In this way, it's possible to isolate this overhead only to some machines. For example, a continuous integration dashboard may pay the overhead of the cache in write mode, allowing users to benefit in read mode, without close to no overhead.