Introducing the “Welcome to Xojo” Bundle!

New to Xojo and looking for guidance? We've put together a terrific bundle to welcome you! Xojo Bundle

This bundle includes six back issues of the magazine -- all of year 21 in printed book and digital formats -- plus a one-year subscription (beginning with 22.1) so you'll be learning all about Xojo for the next year. It's the perfect way to get started programming with Xojo. And you save as much as $35 over the non-bundle price!

This offer is only available for a limited time as supplies are limited, so hurry today and order this special bundle before the offer goes away!

Article Preview

Buy Now

Issue 19.3 ('Black Hole')
Instant purchase and download via GumRoad!


App Wrapper

Issue: 19.3 (May/June 2021)
Author: Marc Zeedar
Article Description: No description available.
Article Length (in bytes): 9,443
Starting Page Number: 12
Article Number: 19302
Related Link(s): None

Full text of article...

The other day I sent a little Xojo app I'd written to my uncle—and he informed me he couldn't run it, because Apple blocked it since it wasn't code signed (tech to ensure it's a valid app from me, a registered Apple developer). I was so used to running my own apps on my own machines I'd forgotten all about such restrictions. (When you create a standalone app with Xojo, it will run fine for you, but if you send it to others, the app will be blocked if it isn't signed.)

More recently, I needed to actually release a "real" app that I wanted to run on the latest Mac operating system. That requires not just that it be code signed, but also notarized (where Apple scans the app on their servers to make sure it complies with certain technical rules and doesn't contain malware). I'd never done that before, so I had to read up on the whole process.

Since I was doing this on my new M1 Mac, I first had to install Apple developer certificates (basically these are private-public encryption key pairs used to guarantee that only the registered developer modified the software). Getting my certificates involved logging into my Apple Developer account and choosing the correct certificate to download—tedious and confusing as there are many options. For instance, there are different certificates for the App Store versus ad hoc distribution (i.e. via your own website).

I initially installed the wrong certificate and didn't realize that until I went to notarize that I had the wrong one (notarization is extremely picky). It took me a few hours of trial and error to get code signing working via Terminal commands.

Notarization, however, proved to be a bridge too far. Nothing I did worked and the errors I got were obscure and the internet wasn't helpful. And this was just basic notarization—I wasn't doing anything special. After wasting an entire day on this cumbersome process, I finally did what I should have done in the first place—I installed Ohanaware's awesome App Wrapper.

App Wrapper, if you're not familiar with it, is a developer's tool that helps automate the process of code signing, notarizing, and packaging your Mac apps for distribution. In the past, I thought of it as primarily only useful for those who want to put their apps on the App Store, which is really complicated, but now that Apple has been adding restrictions to regular non-Store apps, you can't just Zip an app and put it on your website for customers. (Thanks, malware creators, for ruining the internet for everyone!)

Having not used App Wrapper in several versions, I was impressed—and a bit daunted—by the gazillion options presented (see Figure 1). While the interface could probably use a bit more hand-holding for newbies, I poked around and (thankfully) didn't break anything and eventually managed to get my app signed and notarized.

The first thing I realized was that I need to tell App Wrapper to use my developer certificates. When I chose my name in the upper left corner, they all popped up—though because I didn't set up an App Store certificate, that option is in red (not installed).

The term "website" for a certificate confused me for a moment, since that's not what Apple calls it, and I thought it was some sort of web developer certificate. But apparently this refers to an app you'll be distributing on your own, not via the App Store.

My next confusion was that I didn't realize that selecting certificates in that list is significant—it changes all the options available for the rest of the app (which makes sense). Certain items I wanted were grayed out (disabled) because I was working with the "not installed" App Store selection. Once I selected the "Website" certificate option, everything I needed became available.

The lower left pane of App Wrapper shows a list of settings you'll need to go through in order to prepare your app for distribution. Each selection there brings up a ton of options on the right-hand pane. For example, the first page "General," lets you set the OS version and architectures of your app, its copyright and version info, etc.

Fortunately, most of these are filled with the default options and you don't need to change much. Also, many of these pages are for advanced features and aren't crucial for routine scenarios.

One really cool page is "Capabilities" (see Figure 2). Here you can check off the entitlements your app needs. Basically, this is your way of telling Apple and the OS that your app will need to access certain parts of the user's file system, data, network and hardware access, etc., sort of a pre-authorizing so you don't have to nag the user to give you permission. This is intimidating and overwhelming to do by hand, so App Wrapper makes this frightfully easy!

My little app only needed to read and write files (it's a document converter), so that wasn't hard to add.

While I didn't use the "Contents" section, it lets you add icons, files, builds a help system from HTML files, and lets you specify which languages your app supports.

For me, the main section I had to modify was the "Package" settings. Here I was able to choose a Zip file as my installer (App Wrapper can create Apple Installer packages or use a disk image, but my app is so simple, a compressed Zip archive was fine).

Once I'd done all this I wasn't sure what to do next. There seemed to be no "next" or "go" button. I finally noticed the gear widget at the top of the screen and saw it contains commands to make App Wrapper do its thing (see Figure 3).

The "check" was nice as it alerted me to any early problems. The warnings it gave were both useful and confusing. For instance, it saw I had Arm code in my app bundle (it's a Universal app) and wanted me to make my minimum OS version 11.0 (Big Sur). But that would restrict my distribution too much—and the whole point of Universal is that it supports older systems. Initially I followed App Wrapper's recommendation, but then I couldn't run my app on an old computer running MacOS Sierra. I had to repackage it with 10.10 as the minimum, and then it worked.

The really cool thing is that App Wrapper was not only able to code sign my app, but it also notarized and zipped it—all in one step. It did take a bit of time (five minutes), mainly because the app had to be uploaded to Apple's servers for the notarization process (and I have satellite internet with glacier uploads).

Another error I received was that my app didn't have an icon. This is a requirement for notarization. Since I was just at the testing phase, I didn't have an icon ready, so it was a pain to have to take time to create one in the middle of all this. But once I had the icon added in my Xojo project, everything worked perfectly.

I can't tell what a relief that was! After two days of hassling with certificates, code signing, and failed notarization attempts, everything worked in minutes with App Wrapper. I'm never going to attempt any app distribution again without App Wrapper, that's for sure! The pain and hassle it saves is worth its weight in bitcoin.

While I didn't test its App Store submission and many other features, I have no reason to suspect they won't work as promised. The bottom line is, this is an essential app for every Xojo developer, even if you aren't submitting apps to the App Store.

Note: App Wrapper is an xDev advertiser and I did receive a complimentary review copy of the program.

End of article.