A meal-kit iOS app links a vendor analytics SDK, a dynamic framework inside an XCFramework, and is killed at launch before main runs; what in Xcode causes this and how do you fix it?
answer
- linking is not copying
- Do Not Embed versus Embed & Sign
- dyld, load commands and @rpath
- check the binary's Mach-O type
- signature check and mergeable libraries since Xcode 15
basics
~20 sThe dynamic framework is linked but set to Do Not Embed, so it is never copied into the app and dyld cannot load it at launch. Choose Embed & Sign in the target's Frameworks, Libraries, and Embedded Content list.
solid answer
~50 sLinking a framework records a dependency in the app's binary; embedding copies the framework into the app bundle. For a **dynamic** framework, dyld reads the app's load commands at launch, resolves each `@rpath/` path against the run path list (`LD_RUNPATH_SEARCH_PATHS`) and loads it before `main`. Set to **Do Not Embed**, the framework links fine but is missing from the bundle, so dyld fails and the process dies before any app code runs. The fix is **Embed & Sign**, which adds it to the Embed Frameworks copy phase and signs it. First confirm the binary's Mach-O type: a static library needs no embedding. Since Xcode 15, embedding a static framework copies its resources and omits its already-linked binary. Two neighbours: Xcode fails the build if the XCFramework's signature is removed, invalid or from a new signer, and mergeable libraries can cut the launch cost of in-house frameworks.
go deeper
Know that a dynamic framework must be embedded in the app with Embed & Sign, and that linking alone does not copy it.
Explain the Mach-O type setting, the Embed Frameworks copy phase, @rpath lookup, and why a static library needs no embedding.
Diagnose a pre-main launch crash from the crash report, fix embedding per Mach-O type, and handle a changed XCFramework signature safely.
Set a limit on how many dynamic frameworks the app ships, prefer mergeable or static in-house modules, and justify each vendor exception.
## Linking and embedding are two steps An app target's **Frameworks, Libraries, and Embedded Content** list drives two separate things: - **Linking** (the Link Binary With Libraries phase) resolves the app's references to the framework's symbols at build time. For a dynamic framework, the linker writes a load command into the app's executable naming the framework by its install path, usually beginning with `@rpath/`. - **Embedding** (a Copy Files phase that Xcode titles **Embed Frameworks**) copies the framework into the app bundle and, with **Embed & Sign**, signs it. **Do Not Embed** skips the copy. The build succeeds either way, because the linker found the framework on disk. The difference shows up at launch. ## What dyld does before main Apple's launch-time documentation describes the sequence. The dynamic loader, `dyld`, loads the executable, examines its Mach load commands to find the frameworks and dynamic libraries it needs, loads each one, and resolves the dynamic symbols to their addresses. For an `@rpath/` path, `man dyld` explains that dyld substitutes each entry of the run path list, built from the `LC_RPATH` load commands that `LD_RUNPATH_SEARCH_PATHS` produces, until it finds a loadable image. In the meal-kit app the vendor SDK was linked but left at Do Not Embed, so no entry of the run path list contains it. dyld cannot load it, and the process is terminated before `main`, before the app delegate, before any logging the app set up. The system crash report names the library dyld could not load, which is the clue to read first. ## Fixing it without breaking something else 1. **Check the Mach-O type.** For a target you build, the `MACH_O_TYPE` setting shows it: Dynamic Library (`mh_dylib`) or Static Library (`staticlib`). For a vendor binary, run `file` on the binary inside the framework. Only a dynamic framework has to be present at launch. 2. **Dynamic framework: choose Embed & Sign.** Xcode adds it to Embed Frameworks and signs the copy with the app's identity. 3. **Static framework: the rules changed in Xcode 15.** Apple's static-framework guide tells you to choose Embed & Sign; Xcode 15 or later then copies the framework bundle, so its resources, asset catalogs and privacy manifest travel with the app, while omitting the main binary that is already statically linked. 4. **Plain static library (`.a`)**: its code is already in the app binary; there is nothing to embed. ## What the XCFramework adds An **XCFramework** holds one framework or library per platform variant, the iOS Simulator included, and Xcode links the variant that matches the destination. That is why vendors ship one: a universal binary made with `lipo` holds one slice per architecture, and the device build and the Apple-silicon Simulator build are both `arm64`, so one fat binary cannot carry both; Apple's guide says to keep iOS and Simulator binaries separate. How a vendor builds that bundle is covered with XCFrameworks; what matters here is what Xcode checks when you link one. Xcode records the XCFramework's code signature when you add it. The File inspector shows the signing team, or a certificate's SHA-256 fingerprint for a self-issued identity. If the signature is later removed, becomes invalid, or a different developer signs an update, the build fails with an error saying the framework is not signed with the expected identity and may have been compromised. Confirm the change with the vendor before choosing **Accept Change**; otherwise **Move to Trash** and restore a trusted copy. ## The launch cost of every dynamic framework Each additional third-party framework adds launch time. dyld caches much of the work in a launch closure at install, but the closure's size and the work after loading it still grow with the number and size of the libraries. System frameworks cost far less because their memory is shared across processes. - **Mergeable libraries** (Xcode 15 or later) give release builds launch times close to static linking while debug builds keep dynamic linking's build speed. Set `MERGED_BINARY_TYPE` to `automatic` on the app target and Xcode builds its direct framework dependencies as mergeable and merges them in release builds, reexporting them in debug builds; with `manual`, only dependencies with `MERGEABLE_LIBRARY` enabled are merged. - A **prebuilt** XCFramework is merged only if its vendor built it as mergeable; Xcode adds a `MergeableMetadata` key to such an XCFramework's Info.plist. An ordinary vendor SDK stays a separate dynamic framework. - The **dyld Activity** instrument measures time spent in static initializers before `main`. The launch budget as a product decision, and which work belongs on the critical path, is covered in the system design material on startup.
- Xcode fails the build saying the vendor's XCFramework is not signed with the expected identity. What do you do?Treat it as a possible supply-chain problem first. Check the File inspector for the new signer, ask the vendor whether they changed signing, for example after an ownership transfer, and only then choose Accept Change. If nobody can account for it, Move to Trash, restore a copy from a trusted source, and audit how the altered one got in.
- Will MERGED_BINARY_TYPE = automatic merge the vendor's SDK into the app?Only if the vendor shipped a mergeable XCFramework. Automatic merging builds the project's own direct framework dependencies as mergeable and also merges prebuilt XCFrameworks that carry mergeable metadata. An ordinary vendor XCFramework without it stays a separately embedded dynamic framework.
- Why does the crash leave nothing in the app's own logs?dyld resolves and loads dependent libraries before `main`, so the app delegate, any logger and any crash-reporting SDK set up in app code have not run yet. The system crash report is the evidence: it names the library dyld could not load.
- If the app links, every framework is in the bundle
- The linker would fail the build for a missing embed
- Static libraries also need Embed & Sign to run
- Missing frameworks resolve to nil until first call
- Accept Change is routine whenever a vendor SDK updates
- Mergeable libraries merge any vendor XCFramework automatically
Assumes Xcode 27; mergeable libraries and the omitted binary when embedding a static framework need Xcode 15 or later.