Skip to content

Reduce application size with SPM dynamic libraries

Swift Package Manager offers great instruments to create static/dynamic libraries and organise modular project structure. At a first sight, SPM is easy to use out-of-box. But it could be really hard to understand, when to use static or dynamic libraries, how to setup project with combination of SPM, frameworks, widgets, plugins and how to use SPM effectively with application size in mind.

Static vs Dynamic Library

By default, all SPM libraries are static. This could be changed by xcodebuild during resolving dependencies in your target, if you don't specify type explicitly. But in most cases static library is used, when concrete type is missing.

To gain more control, developers have to specify library type in Package.swift declaration. Available options are:

  • static
  • dynamic
.library(
    name: "DesignKit-dynamic",
    type: .dynamic,
    targets: ["DesignKit"]
),
.library(
    name: "DesignKit",
    type: .static,
    targets: ["DesignKit"]
)

Static library is statically linked at build-time, which means that code is included in the compiled binary. Static libraries usage helps to reduce application size and improve performance metrics, such as application launch time.

Static libraries can have resources. They are copied as a separate bundle to the product, which use static library.

Dynamic framework is loaded at runtime, which means that code is not included into your app binary. The main advatage here is that dynamic framework can be shared between app, extensions and other bundles.

Dynamic Framework Specific

Dynamic Library usage in Swift Package is similar to Dynamic Framework in Xcode. When you add library as dependency to your target, three options available:

  1. Embed & Sign - embed framework inside your target in directory <Target>/Contents/Frameworks and sign it with the specified in configuration signature.
  2. Embed without signing - embed framework without signing.
  3. Do not embed - mark framework as a dependency, but do not embed in bundle. Useful option for bundle size optimisation and system libraries usage, which are distribvuted with operation system.

This article is focused on bundle size optimisation and how to use SPM for this purpose. So we will work with Do not embed, Embed & Sign and Xcode build setting LD_RUNPATH_SEARCH_PATHS - to specify searching paths for dylb, responsible for loading and linking dynamic libraries at runtime.

Static library with resources

Swift Package supports resources, such as assets, XIB, Interface builder and other files. To add files as resources, you have to explicitly specify it in a target declaration.

.target(
    name: "DesignKit",
    resources: [
        .copy("Resources")
    ]
)

After adding package as dependency into your application or framework, during compilation Xcode creates a ProductName_ProductName.bundle and copies it to a destination target.

Static library resources bundle

Static library usage as app and widget dependencies

When we create an application and add a standard widget, we want to use shared resources and codebase in both bundles. For this purpose, both app and widget are linked with static library DesignKit.

Widget with static library dependency

As a result, both parent application and widget contains DesignKit and DesignKit_DeskignKit.bundle in resources. The larger our design system and files, the bigger compiled bundle is. In our case, application has only one widget, but in reality - it could have dozens on sub-applications, extensions and plugins. Which could lead to exponential bundle size grows.

Static library in app with dynamic framework

Let's say we want to use our DesignKit library as a dependency in our second framework, linked to the main application.

Static library resources bundle

First of all, it could potentially lead to symbols and resources duplication. But in reality, building the project fails with error:

Swift package product 'DesignKit' is linked as a static library by 'AppWith2DesignKit' and 'FrameworkWithDesignKit'. This will result in duplication of library code.

To fix the issue, you can use two strategies:

  • pass resources via dependency injection techniques;
  • switch DesignKit to dynamic library type.

SPM Dynamic library dependency

The easiest way to setup everything properly is to use dynamic library and search pathes for dyld. Let's say, we have the following structure of our app:

  • App
    • DesignKit (Embed & sign)
    • Framework1
      • DesignKit (Embed & sign)
    • Framework2
      • DesignKit (Embed & sign)
    • Widget
      • DesignKit (Embed & sign)

Xcode is smart enought and even in this case convert all resources into DesignKit_DesignKit.bundle instead of copying in directly into every DesignKit.framework resouces.

But the problem still exists - every framework and bundle still copies DesignKit.framework. So in case of large frameworks size, it will be a real problem for compiled application size.

Dynamic library with dynamic DesignKit

Do not embed dynamic library

To avoid copying dynamic library into all framework, we can specify option Do not embed. Project will compile and run, because our root application still have signed version DesignKit. After the changes, bundle will have next structure:

  • App
    • DesignKit (Embed & sign)
    • Framework1
      • DesignKit (Do not embed)
    • Framework2
      • DesignKit (Do not embed)
    • Widget
      • DesignKit (Embed & sign)

Looks good, but there is still a place for optimisation. Widget is always a part of our application bundle. Bundle codesigning guarantee that structrure won't change (except some unsigned resources), so we can be sure that widget is always stored in our app. This allows us to make changes:

  • App
    • DesignKit (Do not embed)
    • Framework1
      • DesignKit (Do not embed)
    • Framework2
      • DesignKit (Do not embed)
    • Widget
      • DesignKit (Embed & sign)

But our application will crash on launch due to dyld error Versions/A/Frameworks/DesignKit-dynamic.framework/Versions/A/DesignKit-dynamic' (no such file). Loader can't find framework at expected paths. To fix it, we must specify LD_RUNPATH_SEARCH_PATHS for our application target and set value @executable_path/../PlugIns/WidgetDesignKitExtension-dynamic.appex/Contents/Frameworks.

Specifying frameworks search path

If you need to find frameworks in nested frameworks container, you have to add another search path item. Since dyld search doesn't work recursively, it is necessary to specify a concrete directory. For example, @executable_path/../Frameworks/CustomFramework.franework/Version/A/Frameworks.

I recommend to embed framework into the deepest project and setup correct search path. It guarantee that extensions and plugins will work even if they are copied by OS in external directories.

Static library with dynamic library dependency

In some cases yuo can use static SPM targets with dynamic dependencies. Xcode resolves it automatically and during build, embeds your code into application binary and copies dynamic framework into Frameworks directory.

  • App
    • DesignKitOwner (static library)
      • DesignKit (dynamic library)
    • Widget
      • DesignKit (dynamic library)

Both app and widther will have DesignKit as dependency. To avoid embedding transitive dependency, you can explicilty select it's usage in project configuration. And don't forget to change LD_RUNPATH_SEARCH_PATHS to help dyld with loading symbols.

Static with dynamic library settings

Static linking instead of dynamic for same module target

Creating static library with dynamic library dependency works as expected in SPM. I have demostrated it with DesignKitOwner package, which use dynamic DesignKit. But it's not true in cases, when both dynamic and static product are the part of one package. In example below, you the the output of the next setup:

  • App
    • DesignKitWrapper (static library)
      • DesignKit (dynamic library)

Static vs dynamic library in same package

But I've found unexpected output in products directory. Our application contains both DesignKit and DesignKitWrapper bundles for resources, but there is no Frameworks directory at all.

Bonus - Invalid signing for dynamic framework

I've found an issue related to dynamic library usage. if you add a dynamic library from SPM as a dependency to a framework, it will not work at all. If you will embed & sign framework or select and option Embed without signing, application can be built, but won't work. As a result, application will crash on start. Because dylb fails to load the library with invalid signature (mismatch of team ID). It is related to facr, that framework doesn't use signing and Xcode will sign the product with ad-hoc certificate.

Ad-hoc signing for framework dependency

By default (as Xcode recommends), frameworks are used without signing in target settings. And the consumer of the framework (in our case root application) will sign it. But it doesn't work. To fix the issue, you can use several options:

  1. Select signing (teamID and certificate) for project.
  2. Use Do not embed for framework, and instead embed and sign it in the application target.

Useful links