Clean Build Folder vs DerivedData removal for stale incremental artifacts

Comparison of Artifact Removal Methods

Clean Build Folder targets the build products for the active scheme. It removes compiled object files and the final binary, but it typically leaves the module caches and index data intact. DerivedData removal is a destructive action that deletes all cached data, including indices and module caches, for every project stored in the default directory.

Cache Layer Coverage

Artifact Layer	Clean Build Folder	DerivedData Removal
Compiled Binaries / .o files	Cleared	Cleared
Swift/Clang Module Caches	Retained	Cleared
Project Indexing Data	Retained	Cleared
Build Logs	Retained	Cleared

Scope and Impact

• Scope: Clean Build Folder is scoped to the active scheme of the current project. Full DerivedData removal (via ~/Library/Developer/Xcode/DerivedData) affects all projects managed by that Xcode instance.
• Indexing: Removing DerivedData forces Xcode to re-index the entire project from scratch, which can cause significant CPU load and temporary loss of autocomplete/symbol navigation.
• Module Caches: Because Clean Build Folder does not purge the module cache, it may fail to resolve issues caused by corrupted module maps or stale Swift interface files.

Recommended Workflow for Stale Artifacts

1. Step 1: Use Product > Clean Build Folder (Cmd+Shift+K). This is the fastest way to resolve basic linking errors.
2. Step 2: If errors persist (specifically "module not found" or unexpected symbol errors), close Xcode and delete the specific project folder within ~/Library/Developer/Xcode/DerivedData. This targets the specific project without wiping caches for all other projects.
3. Step 3: Perform a full wipe of the DerivedData directory only if global cache corruption is suspected.

Verification

To verify the behavior in your current Xcode version, you can monitor the file system:

# Open the DerivedData folder in Terminal
cd ~/Library/Developer/Xcode/DerivedData

# List folders before cleaning
ls -R

# Perform 'Clean Build Folder' in Xcode, then check if the 'ModuleCache' 
# or 'Index' directories were modified or deleted.

Diagnostic Detail Needed: Are you encountering specific "Module not found" errors or general linker failures? The former usually requires a module cache purge (DerivedData), while the latter is often solved by a simple Clean Build Folder.