In a previous post, we talked about building Swift and Objective-C frameworks. Now we’ll tackle troubleshooting your framework integrations, specifically, manually managed dependencies. One thing to note is that if you are using a package manager for your integrations, then these techniques may not be helpful for you.
There are normally only a few integration points when you want to use a new packaged framework in XCode. If you get these things right, then everything should work fine.
- Include the framework in your project
- Require the framework in your code
- Verify the framework and Runpath Search Paths in Build Settings
- Clean and rebuild without errors
a. Build for both simulator and actual device
b. Verify that you can submit your build to iTunes Connect
We’ll talk about what each of these steps includes and the sorts of symptoms you’ll see when there are problems related to your framework integration.
1. Include the Framework in Your Project
Whether you are working with a cloned open source repository or a compiled framework, you will need to copy the files to a directory in your project structure so that Xcode can access the resources. If you do not include the library that you are referencing in your project, you will probably see a compiler error when you build, such as “No such module…”
A “No such module error” appears when building without including the framework.
2. Require the Framework in Your Code
Your SDK should come with instructions to get you up and running with your integration basics. Ideally you only want the smallest amount of code to initialize the SDK, and not cause any other errors that might confuse your debugging techniques. We are using a sample app that has code for our SDK already included.
3. Verify the Run Path and Framework Search Paths in Build Settings
In your Target Build Settings, search for “search” and make sure that you have a reference to where your framework resources are located.
If you try to build without setting the Framework Search Paths, you will see the same error as before: “No such module…”
A “No such module” error appears when the Framework Search Path has not been provided with a path to your local framework file.
After setting the Framework Search Path to point to the framework resources, Xcode will build the project successfully.
After providing the Framework Search Path, Simulator builds will succeed without errors.
However, when you run the app in the Simulator, there is a crash for reason: “Image not found”. The error “Library not loaded” with @rpath indicates that Xcode cannot find the framework. You also need to update the Runpath Search Paths in Build Settings.
Before providing the Runpath Search Path, Simulator builds will crash because of a “library not loaded” error.
After you update the Runpath Search Path to your framework resources, Xcode should be able to build and run your application on the Simulator.
After providing the Runpath Search Path, builds should succeed and you should be able to run your app without crashes on the Simulator.
4. Clean and rebuild without errors
If you try to build for “Generic iOS Device,” you will see an error that your SDK integrations are not available by class name(s).
Before adding your framework to Embedded Binaries, Generic iOS Device builds will fail with “$(CLASS NAME) unavailable” errors.
This is not a major problem, you just need to drag a release version of your framework to the Embedded Library section of your target’s General tab.
Drag the release version of your framework into the Embedded Binaries section.
Afterwards, you should be able to build for Simulator and for real devices, as well as submit your application to iTunes Connect without any issues.
After adding your framework to Embedded Binaries you should be able to build for all architectures and submit your builds to iTunes Connect without errors.
Remember that until you have built for devices, simulators, and successfully submitted your application to iTunes Connect, there is still the potential for an integration problem. Using the techniques in this post, you can diagnose many other framework integration issues that you may encounter.
Kirk is on twitter at @dmvjs.