Search code examples
iosframeworksrenamedyldxcframework

Renaming an iOS Framework after it's been built

I've built a framework from modified open source C++ code for use in another development sdk. Apps are not able to use this sdk if they have another sdk that also depends on this framework. How can I re-namespace this framework after its already been built (changing MyFramework.xcframework -> MyNewFramework.xcframework).

After renaming all of the references I could find, I was still getting a linker error on install: dyld: Library not loaded: @rpath/MyFramework.framework/MyFramework Referenced from: /private/var/containers/Bundle/Application/[app] Reason: image not found

Solution

  • This requires updating the name of the framework everywhere:

    1. Open MyFramework.framework directory (if using an XCFramework, this will require opening the .xcframework directory and repeating these steps for the .frameworks for both the x86_64 and arm64 architectures.)

    2. Open the Info.plist and change the Bundle name and Executable file to MyNewFramework. You will also want to update the bundle id

    3. Open Modules/module.modulemap. Change the uses of MyFramework to MyNewFramework:

    framework module MyNewFramework {
  umbrella header "MyNewFramework.h"

  export *
  module * { export * }
}

    1. Open the Headers directory and for each and every header file in there, you'll need to change all of the imports of other local header files: #import <MyFramework/Something.h> -> #import <MyNewFramework/Something.h> (I would suggest a global find and replace for #import <MyFramework/).

    2. Change the file in the Headers directory MyFramework.h to MyNewFramework.h

    3. Change the name of the executable found in the framework directory from MyFramework to MyNewFramework

    4. Once navigated to the MyFramework.framework directory, run the command: otool -l MyNewFramework | grep rpath. It should echo something like this: name @rpath/MyFramework.framework/MyFramework as one of the options. Copy this path.

    5. Using the command copied from step 6, Replace the instances of MyFramework with MyNewFramework run this command: (changing @rpath/MyNewFramework.framework/MyNewFramework if different from what you'd copied)

    install_name_tool -id @rpath/MyNewFramework.framework/MyNewFramework MyNewFramework

    1. Confirm that renaming the rpath was successful by running otool -l MyNewFramework again and checking that the path has been updated to MyNewFramework.

    2. Rename the name of the entire framework from MyFramework.framework to MyNewFramework.framework

    3. If using an XCFramework, navigate outside of the architectures to the Info.plist found directly in the .xcframework directory. Under AvailableLibraries in both Item 0 and Item 1 change LibraryPath from MyFramework.framework to MyNewFramework.framework.

    4. If using an XCFramework, don't forget to rename the name of the outermost directory from MyFramework.xcframework to MyNewFramework.xcframework.

    5. To ensure there aren't any hanging references, delete derived data (rm -rf ~/Library/Developer/Xcode/DerivedData/). Make sure to tear down your dependencies and re-integrate them with the renamed one. (For cocoapods, this involves updating your Podfile or podspec with the new framework name, then running pod deintegrate && pod install.)

    Whew! What a job! Go fix yourself a nice cup of something.

    Note: verify that this doesn't cause any issues while building and exporting your app. If so, consider disabling Bitcode if that's a viable option for you.