Caching

When doing an iterative build (the default), EBuild will use caches created during previous build cycles to avoid doing work that is unnecessary, and to result in overall faster build times.

Caching takes into account the change date of certain input files (inout validation), the existence of cache files kept in the project's (actually, the target's) Intermediate Folder, and the presence and timestamp of resulting files.

Input Validation

Input validation is specific for each task and can take into account

  • the timestamp of the project file
  • the timestamps of specific input files
  • the exact structure of specific input folders

If one of the inputs does not match the cache, the cache will be ignored and the task will run as normal. If the cache can be used, the task will instead be skipped, and information about objects and settings created by the previous run will be loaded from the cache file.

For tasks that work on a folder structure that is hard to keep track of with just relying on timestamps (for example, Cocoa Asset Catalogs, where files might simply have been removed), EBuild also stores a full listing of all files along with the cache, and uses that listing when validating the cache.

Caches and the Intermedia Folder

In EBuild, each target that gets build has an "Intermediate Folder", where all build output (including intermediate files that are not considered to be deliverables, and including the final deliverables, as well) gets created and stored during the build (the Final Deliverables are only copied to the designated output folder, at the very end of the build). This Intermediate Folder also stores caches, in the "./Caches" subfolder.

The Intermediate Folder can be located in one of two places, and during build, the target's IntermediateFolder setting refers to the full path of the folder.

By default, EBuild keeps the Intermediate Folder away from the project tree, and stores them in a central location called the "Intermediate Base Folder". On Windows, this is located in the non-roaming user data folder (%APPDATA\RemObjects Software\EBuild\Obj), on Mac under ~/Library/Application Support/RemObjects Software/EBuild/Obj. Its location can be overridden by the --intermediatebasefolder Command-Line Switch, and globally in ElementsPaths.xml.

Underneath the Intermediate Base Folder, EBuild will create a folder named as a combination of the project's name and the project's project ID (to ensure both discoverability and uniqueness), with a subfolder for each configuration and target. E.g.:

~/Library/Application Support/RemObjects Software/EBuild/Obj/MyApplication222-EC5A3A4C-B040-4DBB-BC0B-D4AEBA237A91/Debug/Toffee-macOS

For Cocoa projects build from Windows on a CrossBox 2 Server with a Shared Root, EBuild instead creates a folder named "obj" parallel to the project file (much like MSBuild used to do) and uses that as Intermediate Folder for the project, so that the intermediate files can be accessed both locally and by the build tasks running on the Mac.

Underneath that obj folder, EBuild will still create a subfolder for each configuration and target. E.g.:

C:\Code\MyApp\obj\Debug\Toffee-macOS

How Caching Works

When a task that supports caching succeeds, it writes an XML file with details about all the EBuild objects and settings it created to the ./Caches folder, under a unique name. Oftentimes, a single task will create separate cache files, for example one for each architecture, in case of the compiler and linker for Island. This file contains, among other info, the full paths of generated files (within the Intermediate Folder), as well as their meta data. In some cases, for example for Reference Resolving, it may also contain paths to external files.

When a cache is restored, EBuild will verify that all referenced files still exist, and otherwise will discard the cache.

Cached Tasks

The following EBuild tasks currently support caching: