Skip to content

Migration guides

Jump to bottom
Samuel Défago edited this page Oct 21, 2020 · 3 revisions

This page provides instructions for migration between major versions of Letterbox.

Migration to version 6

Version 6 of SRG Letterbox (and associated libraries) introduces Swift Package Manager (SPM) as dependency management tool. Swift Package Manager is the de-facto standard for dependency management, as it is maintained by Apple and integrated directly within Xcode.

If you were using an older version of Letterbox integrated with Carthage some work is required for migration to SPM. This work needs to be made once and it is very unlikely we will ever trade SPM for something else in the future, as it is now mature and well-integrated within Xcode.

Your project needs to be compiled with Xcode 12, though, as SPM 5.3 features are used by our libraries, most notably binary dependencies and embedded resources.

Why SPM?

Carthage was a reasonably acceptable solution but recently had a rough time coping with newest Xcode capabilities (e.g. XCFramework or Catalyst support). The Carthage team did a great job but now is the time to move on.

Since SPM is updated with Xcode it is guaranteed that the tool stays on par with Xcode capabilities. Moreover, issues usually related to Carthage integration disappear:

  • Xcode automatically manages dependencies when a project is opened. No more external tool has to be run.
  • Compilation times are smaller, as there is no need to build all binaries beforehand (especially if you target several platforms).
  • You can step into library code to understand how a library works, should you encounter an issue or be curious.
  • Startup performance is better as libraries are linked and not dynamically loaded (this could be achieved with Carthage but required static framework integration).
  • Compatibility with Catalyst x86_64 is possible (we'll add it once compatible 3rd party binaries are available, mostly comScore and TagCommander).

If you were running a version of Letterbox older than version 6 and want to migrate to version 6 or above, you first need to remove Carthage integration, then add the dependencies again with SPM.

Removing Carthage dependencies

We first need to remove all Carthage build products and their references for SRG libraries:

  1. Remove SRG library dependencies from your Cartfile. If the Cartfile does not reference other dependencies you can just delete it.
  2. Delete the Carthage folder.
  3. If you still have a Cartfile run Carthage again to build the dependencies your app still needs. This ensures the Carthage folder closely matches what your project requires.
  4. Open your project with Xcode.
  5. In the Project Navigator open the Frameworks folder and delete all .frameworks displayed in red. If you performed a static framework integration also delete all associated .bundles displayed in red.
  6. Open the Build Phases tab for each of the targets which were using SRG dependencies and locate the script phase calling copy-frameworks (if you had any, of course). If you were using Carthage only for SRG dependencies just delete this script phase entirely, otherwise go through the list of input files and only keep the ones still visible in the Frameworks folder.
  7. If your project was using Carthage only for SRG dependencies, open the Build Settings tab and remove all paths containing Carthage for the Framework Search Paths setting (or clear the setting entirely if more appropriate). If you still use Carthage for other dependencies leave this setting as is.

Adding dependencies with SPM

We now can integrate SRG libraries with SPM:

  1. Go under File > Swift Packages > Add Package Dependency and paste the URL of the git repository for the library you need to integrate (e.g. https://github.com/SRGSSR/srgletterbox-apple.git for Letterbox) in the search field.
  2. Press Enter or click on Next.
  3. Select the version you want to integrate. We apply strict semantic versioning, you can therefore choose automatic adoption of patch or minor releases.
  4. Press Enter or click on Next and wait. SPM checks out all involved repositories, which might take a few minutes the first time depending on your Internet connection.
  5. When initial checkout ends choose a target to link the library with. Xcode only offers the possibility to link one target during this step, but if needed you can link other targets manually afterwards under their General tab (click the + sign in the Frameworks, Libraries, and Embedded Content section).
  6. If you were importing frameworks in Objective-C using the #import <LibraryName/LibraryName.h> syntax, replace such legacy imports with modern @import LibraryName;. If you were already using the modern syntax or if your project was written in Swift no changes are required.
  7. If you were using SRGDataProvider you must know that the framework has been split in several smaller frameworks for better SPM integration. Check where it is imported and update your code accordingly:
    • If your code only references model objects, import SRGDataProviderModel.
    • If your code references SRGNetwork-based requests, import SRGDataProviderNetwork.
    • If your code only references an SRGDataProvider instance, import SRGDataProvider.
  8. Now build your project. Everything should compile, except maybe code that requires an update due to breaking API changes. Please read our library release notes to know what changed and how you should adjust.

Once this is done your code should compile and link correctly. You should be able to run it within the simulator as well.

SPM 5.3 code signing workaround (Xcode 12.0 and 12.1 only)

SPM 5.3 has a known issue with code signing of binary dependencies. As a result, attempting to run your app on a physical device might fail if SRG Analytics has been imported (because it references 3rd party binaries). This is most notably the case if you are using SRG Letterbox.

This issue is due to the fact that binaries transitively imported in a project are copied last and not signed, preventing the application from being correctly run.

Fortunately a workaround exists until this issue has been resolved:

  1. Select the target you need to run, go under Build Phases and add an Extract Signing Identity build phase last, with the following content (replace target-name with a proper unique name):

    echo "${EXPANDED_CODE_SIGN_IDENTITY}" > /tmp/target-name-signing-identity

  2. Edit your application scheme, open the Build section and add a Post-action run script phase, with the following content (use the same target-name as above):

    CODE_SIGN_IDENTITY=`cat /tmp/target-name-signing-identity`
find "${TARGET_BUILD_DIR}/${FRAMEWORKS_FOLDER_PATH}" -mindepth 1 -maxdepth 1 -type d -exec /usr/bin/codesign --force --sign ${CODE_SIGN_IDENTITY} --preserve-metadata=

  3. Manage your schemes and check that the scheme you just edited is shared.

This workaround needs to be applied to all runnable targets. The first script extracts the signing identity to use (not known to post-actions) and the post-action directly uses it to sign the frameworks embedded in the final products.

Once SPM fixes this issue both scripts can be removed. We will then update these instructions accordingly.

SPM 5.3 plugin embedded binary fix (Xcode 12.0 and above)

SPM 5.3 has a known issue if your project contains extensions. In this case binary framework dependencies are incorrectly copied in the Plugins folder as well, even if the extension does not actually requires any of these frameworks. This makes App Store Connect submission fail.

Fortunately a workaround exists until this issue has been resolved:

  1. Edit your application scheme, open the Build section and add a Post-action run script phase, with the following content:

    find "${TARGET_BUILD_DIR}/${PLUGINS_FOLDER_PATH}" -mindepth 1 -maxdepth 1 -type d -name "*.framework" -exec rm -Rf {} \;

  2. Manage your schemes and check that the scheme you just edited is shared.

If your project already includes the code signing post-action fix (see above), you can also choose to add this line to the same existing script.

Once SPM fixes this issue the script can be removed. We will then update these instructions accordingly.

Using companion library products

If you are using SRG Letterbox, SPM makes all libraries required by Letterbox readily available to your project and linked with it. Some Letterbox dependencies, namely SRG Data Provider, provide additional companion libraries like SRGDataProviderCombine. These are not referenced by Letterbox and therefore not implicitly made available to your project.

If you want to use such companion libraries you need to add their project as additional explicit dependency to your project first:

  1. Add the library repository URL (in this example https://github.com/SRGSSR/srgdataprovider-apple.git) to your project SPM dependencies.
  2. Select the master branch to ensure no dependency resolution issue arises.
  3. Link the product you need with your project.

You can now use the companion library within your project.

Clone this wiki locally