Code Signing and the Sparkle Framework

Sparkle is a framework that simplifies updating Mac apps. With Sparkle people can check for updates inside your app. If there is a new version of your app, they can download and install it from your app.

I recently added Sparkle support to an app I’m developing. Sparkle has good setup instructions, but I ran into one issue not covered by their instructions. This article tells the story of me discovering and fixing this issue.

Background Information

Sparkle currently has two branches: a stable version 1 and a beta version 2, which adds support for sandboxed apps. Version 1 has a binary framework and related files that you can download and add to your project. You can also download the Xcode project from GitHub and build the framework yourself. Version 2 must be built from source by downloading the Xcode project.

Sparkle supports CocoaPods, but I chose to download the version 1 binary framework and add it to my project. My app isn’t sandboxed so I didn’t need version 2, and version 1 has much more documentation.

The Problem

I followed the installation instructions on the Sparkle site. I built and run the app, but it kept crashing at launch. The following error message appeared in Xcode’s debug console for the Sparkle framework:

not valid for use in process using Library Validation: mapped file has no Team ID and is not a platform binary

The Team ID is the code signing development team.

Initial Search to Find the Problem

I started my search for a solution by browsing the GitHub issues for the Sparkle project. I did not find any issues similar to the one I found.

The next step was to paste the console error message into a search engine. I found a thread in Apple’s paid developer forums where an Apple engineer said you have to code sign the framework with your code signing identity.

Yes! Code sign Sparkle with my code signing identity, and the problem will go away.

Code Sign Sparkle

I knew I wouldn’t be able to code sign the Sparkle binary framework. I would have to clone the project in Xcode, change the code signing build settings to use my code signing identity, build the framework, and add it to my project.

I wasn’t able to build version 1 from source (compiler errors) but was able to build version 2 so I went with that. I changed the code signing build settings, built the framework, and added it to the project.

The app continued to crash at launch with the same error message in the debug console. What was going on?

The Solution

Some more Internet searching for the error message took me to an article on testing a Swift Package Manager package. A sentence in the article, “To avoid signing issue, we need to select a Team for all frameworks”, led me to the solution.

I did not need to modify any code signing build settings to fix the issue. I had to change the Signing Certificate value for my app target in the Signing & Capabilities section.

The original Signing Certificate value was Sign to Run Locally. I had to change it to Development.

After changing the Signing Certificate value, I was able to use Sparkle in my app. I was able to use both the binary version 1 framework and the version 2 framework I built from the Xcode project. I ended up using the binary version 1 framework.

It took me several hours to solve the code signing issue. I hope this article keeps someone else from making the same mistakes I made.