DEV Community


How to migrate your project with Carthage to Xcode 12

noahkuwae profile image noah.k ・2 min read

According to Apple's announcement, you need to build your app with Xcode 12 from April 2021 to submit to the App Store. I really got stuck migrating my project which uses Carthage, so let's see how I managed to do that in this article.

Use XCFramework

XCFramework is necessary to fit to Xcode 12.
This article doesn't refer to the detail of XCFramework, so please check other sources for more information.

Update Carthage to 0.37.0

Carthage 0.37.0 added support for XCFramework.

Add Carthage --use-xcframeworks option

E.g. carthage bootstrap --use-xcframeworks --platform iOS --no-use-binaries

Link to XCFrameworks

In TARGETS -> General tab -> Frameworks, Libraries, and Embedded Content,
replace *.framework with *.xcframework.
*.xcframework files are located in Carthage/Build.

Update Framework Search Paths

In TARGETS -> Build Settings tab -> Search Paths -> Framework Search Paths,
Replace *.framework's parent folder path with *.xcframework's.
E.g. $(PROJECT_DIR)/Carthage/Build/iOS -> $(PROJECT_DIR)/Carthage/Build

Update Not to Run Script copy-frameworks

In TARGETS -> Build Phases tab,
you no longer need to copy frameworks.

Workaround for Test Target

In my project, steps above enabled main target to work with Xcode 12, but not test target.
I use some libraries only for test target, but building test target failed saying No such module (library name).
Let's see how to fix that.

Update Framework Search Paths

In TARGETS -> Build Settings tab -> Search Paths -> Framework Search Paths,
add architectures where you run.
E.g. Any iOS SDK and Any iOS Simulator SDK

Then add *.framework's parent folder path for each architecture.
*.framework files are located in *.xcframework/(architecture).
E.g. $(PROJECT_DIR)/Carthage/Build/Foo.xcframework/ios-arm64_armv7 for Any iOS SDK,
$(PROJECT_DIR)/Carthage/Build/Foo.xcframework/ios-arm64_i386_x86_64-simulator for Any iOS Simulator SDK

Remove Links to Frameworks, XCFrameworks

I succeeded to build the target without setting links to Frameworks or XCFrameworks.
Remove them from TARGETS -> Build Phases tab -> Link Binary With Libraries.

Copy Frameworks

Copying frameworks is still necessary for this target, otherwise you'll encounter Library not loaded when running the test.
In TARGETS -> Build Phases tab, create (or update if exists) Copy Files Phase specifying *.xcframework, not *.framework.


Carthage / Building platform-independent XCFrameworks (Xcode 12 and above)

Discussion (0)

Editor guide