How to Create an XCFramework

XCFramework allows you to package the binary codes of iPhone, iPhone simulator and many other platforms into a distributable .xcframework file. You only need to generate an XCFramework for your framework to support multiple platforms. Moreover, when a project that includes XCFramework is compiled for iPhone platform, the target will only contain the binary code of iPhone platform.

Before, we used lipo command to generate a fat framework that supports multiple platforms. However, as the name suggests, a fat framework is very fat. Because even if the project that includes the a framework only compiles iPhone platform, the final target will still contain the binary codes of all platforms in the fat framework, so that the target will be very fat.

Archive for Platforms You Want to Support

You first archive for all the platforms you want to support. For example, the command below is to archive for iOS platform.

xcodebuild archive \
  -workspace "WaynesTalk.xcworkspace" \
  -scheme "WaynesTalkScheme" \
  -destination "generic/platform=iOS" \
  -archivePath "archives/WaynesTalkScheme-iOS" \
  SKIP_INSTALL=NO \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES

• -workspace: Specify name of workspace. If your project does not use workspace but project, use -project to specify name of project.
• -scheme: Specify name of scheme.
• -destination: Specify platform to archive. The example is iOS simulator. This link lists all destination lists.
• -archivePath: Specify path of generated archive.
• SKIP_INSTALL=NO: Tell xcodebuild not to install the generated archive.
• BUILD_LIBRARY_FOR_DISTRIBUTION =YES: Tell xcodebuild to compile library for distribution.

The following command is to archive for iOS Simulator platform.

xcodebuild archive \
  -workspace "WaynesTalk.xcworkspace" \
  -scheme "WaynesTalkScheme" \
  -destination "generic/platform=iOS Simulator" \
  -archivePath "archives/WaynesTalkScheme-iOS-Simulator" \
  VALID_ARCHS="i386 x86_64" \
  SKIP_INSTALL=NO \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES

• VALID_ARCHS = “i386 x86_64”: If your framework uses such as GoogleSignIn framework, the error that xcodebuild only finds arm64 of GoogleSignIn framework but can’t find x86_64 may occur when compiling. This can be solved by adding it.

We just archived two platforms, iOS and iOS Simulator. Two .xcarchive folders were created under the archives/ folder. These two folders contain many files. WaynesTalk.framework can be found in .xcarchive/Products/Library/Frameworks/WaynesTalk.framework, as follows.

project % tree -d archives
archives
├── WaynesTalkScheme-iOS.xcarchive
│   ├── Products
│   │   └── Library
│   │       └── Frameworks
│   │           └── WaynesTalk.framework
└── WaynesTalkScheme-iOS-Simulator.xcarchive
│   ├── Products
│   │   └── Library
│   │       └── Frameworks
│   │           └── WaynesTalk.framework

Creating an XCFramework

Finally, use the following command to generate .xcframework.

xcodebuild -create-xcframework \
    -framework "WaynesTalkScheme-iOS.xcarchive/Products/Library/Frameworks/WaynesTalk.framework" \
    -framework "WaynesTalkScheme-iOS-Simulator.xcarchive/Products/Library/Frameworks/WaynesTalk.framework" \
    -output "archives/WaynesTalk.xcframework"

• -framework: Specify framework file for platform you want to support.
• -output: Specify the output path of .xcframework.

The archives/WaynesTalk.xcframework is finally generated. If you want to include it in your project, simply drag and drop .xcframework to your project, as shown here .

Creating XCFramework with Debug Symbols

In the previous section, the XCFramework we created does not include debug symbols. If you want to create a XCFramework that contains the debug symbols, then when generating XCFramework, we also need to specify the path of debug symbols.

We can find the debug symbols file under the .xcarchive.

project % tree -d archives
archives
├── WaynesTalkScheme-iOS.xcarchive
│   ├── BCSymbolMaps
│   │   └── 0324C88D-6ACC-3914-9F46-6B7D6540FA4A.bcsymbolmap
│   │   └── 0A656801-098A-3169-BC81-FDB08364A694.bcsymbolmap
│   │   └── 0B375D3D-C623-3E42-8F99-5D80A9F159B4.bcsymbolmap
│   ├── dSYMs
│   │   └── WaynesTalk.framework.dSYM
├── WaynesTalkScheme-iOS-Simulator.xcarchive
│   ├── dSYMs
│   │   └── WaynesTalk.framework.dSYM

Then, when generating XCFramework, use -debug-symbols to specify the path of the debug symbols files.

xcodebuild -create-xcframework \
    -framework "WaynesTalkScheme-iOS.xcarchive/Products/Library/Frameworks/WaynesTalk.framework" \
    -debug-symbols "WaynesTalkScheme-iOS.xcarchive/BCSymbolMaps/0324C88D-6ACC-3914-9F46-6B7D6540FA4A.bcsymbolmap" \
    -debug-symbols "WaynesTalkScheme-iOS.xcarchive/BCSymbolMaps/0A656801-098A-3169-BC81-FDB08364A694.bcsymbolmap" \
    -debug-symbols "WaynesTalkScheme-iOS.xcarchive/BCSymbolMaps/0B375D3D-C623-3E42-8F99-5D80A9F159B4.bcsymbolmap" \
    -debug-symbols "WaynesTalkScheme-iOS.xcarchive/dSYMs/WaynesTalk.framework.dSYM" \
    -framework "WaynesTalkScheme-iOS-Simulator.xcarchive/Products/Library/Frameworks/WaynesTalk.framework" \
    -debug-symbols "WaynesTalkScheme-iOS-Simulator.xcarchive/dSYMs/WaynesTalk.framework.dSYM" \
    -output "archives/WaynesTalk.xcframework"