How to build and use an XCFramework

 原文链接

XCFramework were introduced on wwdc 2019. They allow us to package different architectures of the same module into one entity.

On iOS, frameworks (dynamic or static) and libraries (static only) are two types of module that can be linked to another module, either in a compiled state or not.

Building an XCFramework is a two step process. First the framework or library needs to be compiled from source code. Xcode calls this product an archive. Then the archive is packaged into an XCFramework.

This article will show you how to proceed with both steps.

Why an archive

There are two main reasons for picking an archive (a compiled state of code) over source code.

The most obvious one is when you have no other choice. The framework or library might be from a vendor that only shares the compiled version of their code.

The second reason is to improve compile time. Even though Xcode gets smarter with the years, linking against a non compiled framework or library will increase your app compile time. If your project includes a framework or library that doesn’t change very often, it makes sense to consider compiling it and linking against its archive.

How to archive a framework

iPhone and Simulators run apps on different architectures. When Xcode builds an archive, it builds it for a specific architecture. Therefore if you want to create an XCFramework to run on both iPhone and Simulators, you will need to create two versions of the archive. Here’s the command line for archiving a framework with the iPhone sdk:

xcodebuild archive 
    -project SomeFramework.xcodeproj
    -scheme SomeFramework 
    -destination "generic/platform=iOS"
    -archivePath "archives/SomeFramework"
    SKIP_INSTALL=NO
    BUILD_LIBRARY_FOR_DISTRIBUTION=YES

One small edit will archive the framework for the simulators: -destination "generic/platform=iOS Simulator". Notice the BUILD_LIBRARY_FOR_DISTRIBUTION flag. You need it to create a stable Swift module, i.e a module that is compatible with different version of Swift.

How to archive a library

Building an archive for a library is quite similar to the process of archiving a framework. Except if you want to make it available to Swift. Whereas the default option for a framework is to define a module, it is not the case for a library.

Packaging a library into a module requires editing two build settings and adding a build phase:

• Turn the Define Module setting to YES.
• Create a module.modulemap (create a new file, pick the empty template) and place it in your library directory. A simple module map file can look like: (see http://clang.llvm.org/docs/Modules.html#module-map-file for documentation on module maps)

module SomeLibrary {
    umbrella header "SomeLibrary.h"
    export *
}

• Edit the Module Map setting with your file locationSomeLibrary/module.modulemap. Make sure the module map is in the same directory than the public header files. Or modify the header’s path accordingly.
• Add a Copy Files build phases and include the umbrealla header and the module map.

After completing these preliminary steps, run the following command line for archiving a library with the iPhone sdk:

xcodebuild archive 
    -project SomeLibrary.xcodeproj
    -scheme SomeLibrary 
    -destination "generic/platform=iOS"
    -archivePath "archives/SomeLibrary"
    SKIP_INSTALL=NO
    BUILD_LIBRARY_FOR_DISTRIBUTION=YES

One small edit will archive the library for the simulators: -destination "generic/platform=iOS Simulator".Notice the BUILD_LIBRARY_FOR_DISTRIBUTION flag. You need it to create a stable Swift module, i.e a module that is compatible with different version of Swift.

Why an XCFramework

Or why is an archive not enough.

As mentioned above, Xcode builds an archive for a specific architecture. Therefore an archive could be run on the iPhone or on the simulator but not on both.

One solution is to combine different archives, each supporting a targeted architecture, into one package and let Xcode pick the correct archive at compile time.

Before XCFramework was introduced, developers packaged multiple archives into a so called Fat Framework. This enabled developers to ship only one package, supporting different architectures, but it also meant that it was upon the package users to add a build phase to strip the Fat Framework from not compatible archives.

Apple introduced XCFramework in 2019. XCFramework packages different archives into one xcframework product. On top of that, XCFramework format is supported by Xcode, removing the need to manually strip out not compatible archives during a build phase. Xcode takes care of it automatically.

How to build an XCFramework

You can create an archive by running a command line, as shown above. Or you can use Xcode interface. At the time of this writing, Xcode doesn’t provide any graphical interface to create an XCFramework. You are left with the command line (official documentation):

xcodebuild -create-xcframework
    -framework "archives/SomeFramework-Sim.xcarchive/Products/Library/Frameworks/SomeFramework.framework"
    -framework "archives/SomeFramework.xcarchive/
Products/Library/Frameworks/SomeFramework.framework"
    -output "xcframeworks/SomeFramework.xcframework"

It takes as input all your targeted architectures archives. If you have archived a library instead of a framework, simply change -framework with -library .

How to use an XCFramework

Drag and drop your .xcframework into the Frameworks, Libraries, and Embedded Content section of your target’s General tab.

Now is time to tell Xcode where to look for the module.

If your XCFramework includes a framework, edit the Framework Search Paths setting.

If your XCFramework includes a library, edit the Header Search Paths and Library Search Paths . If you link against a library that is not part of the same repo, you will need to copy over the public header files as well (in addition of the XCFramework of course!).

That’s it, you can now call your framework or library from another module. I hope that after reading this tutorial, you have acquired a better understanding of why you should consider using XCFramework and how to build them.