Framework Target

Why it exists

Large iOS apps often need to share code across multiple executables: the main app, a widget extension, a watch app, a share extension. Compiling that shared code separately from each target avoids duplication and lets teams build and version it independently. A Framework target exists to package that shared code as one reusable, linkable unit.

The mental model

Think of an app target as a finished car and a framework target as a parts supplier building a reusable engine. The engine is built once, tested on its own, and then bolted into multiple cars. It has a defined interface, the parts that connect to the car, while everything inside stays hidden unless the supplier deliberately exposes it.

How it works

Creating a Framework target gives Xcode a different product type that compiles to a Mach-O dynamic library bundled with its headers or Swift module interface. Only symbols marked public or open in Swift are visible to code that imports the framework; everything else stays internal by default. An app or extension target adds the framework under Frameworks, Libraries, and Embedded Content, and for dynamic frameworks must choose Embed and Sign so the framework binary is physically copied into that target's bundle and code signed, not just linked at compile time. Each separate executable, the app, a widget, an extension, needs its own embedded copy.

When it matters

This matters whenever an app ships more than one executable, or when a team wants independently buildable, testable modules. It also affects build times, since a framework can be cached and only rebuilt when its own source changes. The main footgun is linking a framework without embedding it in every executable that needs it, which compiles without error but crashes on launch, and circular dependencies between two framework targets, which fail to build at all.

A concrete example

A team extracts networking and model code into a CoreKit framework shared by the main app and a new Share Extension target. The main app works fine, but the extension crashes immediately on launch with a dyld error reading Library not loaded, CoreKit. The cause is that CoreKit was linked in the extension target but never added under its own Embed and Sign setting, so the compiled binary was missing from the extension's bundle even though the app target had it.