12.6.5 The Hxcpp Cache

The hxcpp compile cache is used to share object files between projects. This can alleviate the need to ship static libraries with external projects, since developers who use the library can compile the library just once, and then reuse it between projects.

The cache uses a hashing mechanism to tell if the contents of a file or its dependencies have changed, and combines this with the compiler version and flags to make specific object files for each change and each compiler configuration. This also allows some common Haxe runtime and Haxe-generated files to share their object files between projects, even if in different directories.

Additional benefits include keeping some files outside the source tree, and being able to remove these temporary files easily.

Setup

A directory needs to be set aside to enable the cache. If possible, this should be on fast storage, such as an SSD. This is most easily done with an entry in the .hxcpp_config.xml file:

<set name="HXCPP_COMPILE_CACHE" value="c:/hxcpp/cache" />
<set name="HXCPP_CACHE_MB" value="4000" />

Keeping the path short can help in some border-line cases with some compilers where command-line length can become an issue.

The cache size defaults to 1 gigabyte. For many cases, this is big enough. However, on large projects, with several architectures and a lot of debug information, this default can lead to "cache churn" where some files are evicted from the cache, even though they are likely to be used again. Increasing the number of space allocated to the cache can help.

Using The Cache

To use the cache with your own libraries, the files group should have a cache entry to tell hxcpp that you have considered dependency issues when designing the group.

<cache value="true" project="name" asLibrary="true" />

See Files - cache for more details.

Management

When compiling normally, hxcpp will check the cache size and evict the least used files to maintain the specified cache size. Object files in the cache are grouped into "projects" to make management easier, and the hxcpp build tool can be used to explicitly manage the object files.

haxelib run hxcpp cache [command] [project]
  Perform command on cache, either on specific project or all. commands:
   clear -- remove all files from cache
   days #days -- remove files older than "days"
   resize #megabytes -- Only keep #megabytes MB
   list -- list cache usage
   details -- list cache usage, per file

Start with:

haxelib run hxcpp cache list

To get an idea of cache usage.

---