Everything you need to know about XCFramework

Are you using an M1 chip Mac you will need this. Are you interested in Swift Package Manager you need XCFramework. Moreover Apple recommends it.

Framework have been here since long, now it’s time for brand new XCFramework. XCFramework is almost similar to Framework.

Both Framework and XCFramework contains different architecture variants for different platforms like iOS macOS, tvOS, watchOS and for simulator too.

XCFramework Primarily contains the following:

1. Header Files
2. Debug Symbols
3. Binary Files for each architectures

Debug symbols dSYMs and BCSymbolMaps will only be generated if it is a Dynamic XCFramework. Static ones doesn’t create debug symbols.

There is great article written by Andres on in-depth analysis between Static and Dynamic Framework

Major Difference between Framework and XCFramework

Framework generally contains different architectures in a single binary file. Which is called Fat / Universal binary.

However in XCFramework we have different binary files for different architecture.

You can create Framework by building for each architectures and the clubbing it together using

-lipo command

XCFramework can created by building for each architecture and then executing a xcodebuild command

xcodebuild -create-xcframework

I have written another article detailing all the differences between Framework and XCFramework.

How to create XCFramework?

There are two approaches to create XCFramework, either entirely through Xcodebuild command or mix of Xcode and Xcodebuild command.

Also you can use Fastlane which internally uses Xcodebuild command.

However the main steps are:

1. Build for all the architectures
2. merge it using xcodebuild command

Build for each architecture:

To build first you have to create a framework.

Select the framework option in Xcode templates and proceed to create a framework. Once the project is created tap on build and once build is successful, find the framework in local directory.

Similarly build for device and then locate the Framework.

Merge it to finally create XCFramework

xcodebuild -create-xcframework -framework <simulator binary path> -framework <device binary path> -output <path>

and this is how it looks like

xcodebuild -create-xcframework -framework /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphoneos/SampleXCFramework.framework  -framework /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphonesimulator/SampleXCFramework.framework  -output ~/Desktop/sample.xcframework

Then it takes couple of seconds to generate XCFramework

Including Debug Symbols in XCFramework

Debug symbols are of two types

1. dSYMs
2. BCSymbolMaps

As only dynamic framework generates debug symbols, which can only be included in XCFramework. So if your framework is a static one it won’t generate while building for each framework.

While creating XCFramework the dSYMs file gets included when we provide the dSYM path.

xcodebuild -create-xcframework 

-framework /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphoneos/SampleXCFramework.framework  

-framework /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphonesimulator/SampleXCFramework.framework  

-debug-symbols /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphoneos/SampleXCFramework.framework.dSYM 

-output ~/Desktop/sample.xcframework

Note: While trying out this command use your own path and don’t give space. The above code is just for representation purpose.

XCFramework now includes the dSYMs file:

Build Settings for creating XCFramework

When generating XCFramework there are some important build settings which needs to set while building for each framework.

1. Build Libraries for Distribution = Yes
2. Skip Install = No

Apple recommends to use these build settings in order to generate XCFramework.

These two are absolutely necessary to create XCFramework.

However I want to recommend from my experience that you also set build for active architecture only = Yes

This will make sure that it will have only architectures that are needed. Otherwise sometime Framework and XCFramework will have architectures which are not required.

If you know Fastlane or already using it then you can creating XCFramework using Fastlane.

Summary

XCFramework can be created by merging multiple Frameworks built for different architectures. XCFramework includes the following:

Header Files

Debug Symbols

Binary Files for each architectures

To create XCFramework first you need to create framework for each architectures. Create XCFramework by using the command.

xcodebuild -create-xcframework 

-framework /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphoneos/SampleXCFramework.framework  

-framework /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphonesimulator/SampleXCFramework.framework  

-debug-symbols /Users/sauravsatpathy/Library/Developer/Xcode/DerivedData/SampleXCFramework-eybawsbuaizkqtdprilhvfpykvrj/Build/Products/Debug-iphoneos/SampleXCFramework.framework.dSYM 

-output ~/Desktop/sample.xcframework