Symbol leakage after incremental build with unchanged Mergeable setting

Symbol Leakage and the Mergeable Setting

Toggling the Mergeable (MERGEABLE_BINARY) setting to NO does not guarantee that previously exported symbols are stripped during a subsequent incremental build in Xcode 15. Because incremental builds rely on existing object files and cached debug information, changing a build setting often fails to invalidate all previously generated artifacts. Consequently, stale symbols may persist in the resulting dSYM and archive.

Likely Explanation for Symbol Persistence

The Mergeable setting is designed to facilitate the merging of binaries in modular build environments; it is not a primary mechanism for controlling symbol visibility. Symbol leakage during incremental builds typically occurs because:

• Stale Object Files: The build system may not detect that a change in build settings requires a full re-link or re-generation of all object files.
• dSYM Accumulation: dSYM files are generated from the debug information embedded in object files. If old object files remain in the build directory, the linker may still include their symbols.
• Visibility Overlap: When target membership is set to Project and public header visibility is expanded, the compiler exports more symbols than necessary. If these are captured in an incremental build, they remain until the build folder is purged.

Steps to Ensure Symbol Stripping

To guarantee that only the intended public API is present in your final archive, follow these steps:

1. Set Visibility: Ensure Swift symbols are explicitly marked public or open, and that Target Membership is restricted to the necessary targets.
2. Disable Mergeable: Set Mergeable to NO if you do not require modular binary merging.
3. Purge Build Artifacts: Perform a Clean Build Folder (Cmd + Shift + K) to remove all cached object files and stale dSYMs. This is the only way to ensure the linker starts from a clean state.
4. Archive: Generate a fresh Archive to verify the final distribution symbols.

Verification Process

Use the following scoped commands to verify that leaked symbols have been removed from the final binary and dSYM:

# List all exported global symbols in the binary
nm -gU Path/To/Your.app/YourBinary

# Inspect the dSYM for specific leaked symbol names
dwarfdump --debug-info Path/To/Your.dSYM | grep "SymbolName"

Missing Diagnostic Detail: Are you using a custom build script or a third-party dependency manager (e.g., CocoaPods) that might be overriding the MERGEABLE_BINARY setting at the target level?