Xcode Build System: Module Cache Persistence After Clean Build Folder

Module Cache Behavior During Clean Build Folder

The "Clean Build Folder" operation in Xcode does not guarantee the removal of all cached modules. While it removes intermediate build artifacts and products associated with the current scheme, the Clang module cache (typically stored in ModuleCache.noindex) is designed for persistence to accelerate subsequent builds. Consequently, stale module entries can survive a standard clean operation, potentially leading to inconsistent build results.

Likely Explanation for Persistence

The module cache is an input-keyed cache used by the compiler to avoid re-parsing headers. Because these caches are often shared across different targets or versions of a project within the same Derived Data directory, Xcode treats them as persistent assets rather than transient build products. If the cache becomes corrupted or contains stale references that the build system does not detect as "dirty," a standard clean will not purge them.

Steps for a Guaranteed Fresh State

To ensure a completely fresh environment, especially on CI/CD agents, you must manually remove the Derived Data. Follow these steps:

1. Stop all Xcode processes: Quit Xcode and terminate any running xcodebuild instances to avoid file locks or partial deletions.
2. Identify the Derived Data path: Verify your path via Xcode > Settings > Locations. By default, this is ~/Library/Developer/Xcode/DerivedData.
3. Delete the directory: Remove the specific project folder within Derived Data or the entire directory for a global reset.

   rm -rf ~/Library/Developer/Xcode/DerivedData/YourProject-hash-folder

4. Rebuild: Restart Xcode and trigger a new build. Note that the first build will be significantly slower as indexes and modules are regenerated.

Verification Method

To verify if the cache is persisting, you can check the modification timestamps of the module cache directory before and after a clean:

ls -la ~/Library/Developer/Xcode/DerivedData/YourProject-hash/Build/Intermediates.noindex/ModuleCache.noindex

If the files and timestamps remain unchanged after "Clean Build Folder," the cache was not purged.

Diagnostic Detail Request

Are you using a custom DerivedData path via the -derivedDataPath flag in your CI/CD pipeline? If so, the default library path will not be the source of the stale artifacts.