Jesse Squires

Mariposa: a lightweight Swift CLI to automate sharing blog posts to social media

2025-11-07T07:58:20-08:00

After writing and publishing a new post, I always share to social media because that is how a lot of folks receive updates (also, POSSE). Because I hate using social media, I have automated this process with a lightweight CLI written in Swift called Mariposa.

The goal of Mariposa is to replace services like IFTTT or Zapier to automatically post to Bluesky and Mastodon whenever I publish a new blog post. Currently, IFTTT has integrations for posting RSS feeds to Twitter and (with some extra work) Mastodon, but it does not provide an option for automating RSS to Bluesky. Zapier offers equivalent functionality, and maybe supports Bluesky, but I’m not sure. But enough about third-party services — we don’t need them anymore!

Motivation

I wanted to stop using IFTTT, in general. I also wanted a solution for Bluesky automation which IFTTT does not support. And Twitter is dead. But more importantly, using IFTTT was always an awkward, roundabout solution anyway. I only used it because I was being lazy.

My blog is built with Jekyll (which I’ve written about before), and I publish using git. Thus, it was always a bit strange to git push and publish a new post, visit my website to verify it updated, and then wait for a random service to listen for changes to my RSS feed so it could post to social media for me. If I’m running git push to publish, I might as well run another command right then that will post to social media. So that’s what I did!

How it works

The only prerequisite is that you have a JSON feed for your blog. As mentioned, I use Jekyll for my blog, which easily accommodates generating a JSON feed. But it does not matter how you generate your site, as long as you have a feed.

If you are only generating a traditional XML RSS feed, you can borrow and adapt my JSON feed template for your needs. (And if you do not publish a feed at all, well… you should!) While I publish both RSS and JSON feeds, Mariposa only supports JSON, which comes free with Swift. And I would rather not ruin something fun by dealing with XML.

Mariposa reads a JSON feed locally from disk, and then posts the most recent entry to Bluesky and Mastodon. The content of the social media posts includes the blog post title and url. For credentials for Bluesky and Mastodon, you pass in a yaml config file. (I chose yaml for this config because it’s nicer to read and write for this type of data.)

The great thing about Jekyll (or any static site generator) is its simplicity. The generated site is output to _site/, which I can preview easily locally. The output includes my full generated JSON feed. That is all the information I need to send out a post to Bluesky or Mastodon — there is no need for services like IFTTT to listen for changes. Much simpler!

You can find more details and documentation on GitHub.

Workflow

This tool is very much something I built for myself. It is centered around my workflow and my needs. But, I think other folks with similar setups could find it useful. After finishing a blog post, here’s my workflow:

Publish via git
Make sure the locally generated site is up-to-date (jekyll build)
Run mariposa to share it via Bluesky and Mastodon

Because I use a Makefile with phony targets as shortcuts for scripts and commands, the above simplifies to:

make build (build the site locally)
make pub (publish changes to web server)
make social (share post on social media)

Example usage

In this example, I’ve cloned the repo to ~/Developer/mariposa/. The config file with my credentials is stored in my home directory at ~/.mariposa_config.yml. The command is run from the root directory of my website and my generated feed is stored in _site/feed.json.

Below is the output for sharing this very blog post!

swift run --package-path ~/Developer/mariposa/ mariposa -c ~/.mariposa_config.yml -f _site/feed.json

👀 Preview:
    Mariposa: a lightweight Swift CLI to automate sharing blog posts to social media
    https://www.jessesquires.com/blog/2025/11/07/mariposa/

➡️  Continue? (y/N): y

Posting to Bluesky... success ✅
https://bsky.app/profile/jessesquires.com

Posting to Mastodon... success ✅
https://mastodon.social/@jsq/115509326819194206

🎉 Finished

Developer notes

I had a lot of fun building this over the course of an afternoon. The Mastodon API and Bluesky API were both pretty easy to work with. Many thanks to Manton Reece for writing this blog post, which helped me get started even more quickly with the Bluesky API, which was a bit trickier.

Mariposa is published as a Swift Package. It depends on JP’s Yams library for parsing the yaml config, and the swift-argument-parser for the CLI. This was my first time using swift-argument-parser — and wow, that library is fucking awesome. I barely had to write any code and everything just worked. Other than these two libraries, it’s just Foundation and the Standard Library.

Again, this is very much a tool I wrote for myself. It supports a very small subset of the Mastodon API and Bluesky API — only the parts I needed. I wrote my own lightweight clients because using a third-party API client library felt like overkill. I made the package very modular, so it should be easy to add features or modify it however you like.

You probably noticed this is actually partially automated. I have to manually run mariposa after publishing a post. I could have run this on the web server via a git hook, tracked what entries have already been shared, etc. — but that would have required a lot of additional complexity that was not worth the time or effort to me. You could surely automate fully if desired.

All the code is on GitHub. Check it out, and feel free to send me a pull request!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Workaround: how to silence individual deprecation warnings in Swift

2025-10-28T11:12:34-07:00

The Swift compiler has fine-grained controls for compiler warnings. As of Swift 6.2, you can even configure these warnings in Swift Packages. Unfortunately, this is an all-or-nothing approach with no flexibility, unlike the piecemeal control provided by the Clang compiler via #pragma directives.

Like Objective-C, in Swift you can treat all warnings as errors, suppress all warnings, or treat only specific diagnostic groups as warnings or errors. However, in Objective-C — that is, with the Clang compiler — rather than only configure these settings for the entire project, you can control diagnostics via pragmas. This allows you to piecemeal disable warnings for specific sections of source code. Despite being over a decade old, Swift still has no equivalent.

Treating warnings as errors

In nearly every team I have ever worked on — honestly, probably every team — we treat all warnings as errors. The motivation is to avoid accumulating an excessive amount of (maybe mundane and minor) warnings that everyone ignores, which later risks not noticing a warning of serious importance. If all warnings are errors, they must be addressed immediately. A project with zero warnings and zero errors is a wonderful thing.

There is one exception to this rule — deprecations. Sometimes, we have no choice but to continue using deprecated APIs. This could be due to legacy code that is too difficult to refactor, a lack of adequate replacement APIs, project priorities, etc.

What we do not want to do is treat all deprecation warnings as errors. That would prevent us from building. We also do not want to suppress all deprecation warnings via global compiler settings. This would allow new violations to go unnoticed. What we want to do is silence individual deprecated API usage at the call site on a case-by-case basis. This gives us the best of both worlds: all warnings are treated as errors, and in specific scenarios we allow using deprecated APIs.

Using Clang `#pragma` directives

Let’s look at an example using everyone’s favorite APIs for dealing with everyone’s favorite iOS UI element: the status bar.

With Clang and Objective-C, we can use #pragma clang diagnostic to modify warning flags.

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdeprecated-declarations"
[[UIApplication sharedApplication] setStatusBarHidden:true withAnimation:UIStatusBarAnimationFade];
#pragma clang diagnostic pop

In this example, we are using the deprecated API setStatusBarHidden:withAnimation:. Prior to the call, we save the diagnostic state using clang diagnostic push, then ignore the warning for deprecated declarations (which would actually be treated as an error). After the call, we restore the previous diagnostic state using clang diagnostic pop.

Swift workaround

Disappointingly, Swift has no equivalent to Clang #pragma directives. Fortunately, we can do some hacky things with protocols to achieve the same results. (Credit is due to the StackOverflow user who offered this workaround. This blog post serves to elaborate more on what, why, and how.)

Alternatively, instead of using this Swift workaround, you can simply use Objective-C and Clang #pragma and take advantage of the interoperability between the two languages. This hack is for folks that do not want to introduce Objective-C into their Swift-only codebase.

First, we define a new protocol that offers the same APIs as the deprecated ones. You need to name the protocol members slightly differently than the original APIs. I recommend using a traditional Objective-C three-letter prefix. (In this example, I’m using “deprecated_”.)

protocol DeprecatedStatusBarMethods {
    func deprecated_setStatusBarHidden(_ hidden: Bool, with animation: UIStatusBarAnimation)
}

Next, have the type that owns the deprecated APIs conform to this protocol. The implementation will simply call the deprecated method. In this case, setStatusBarHidden:withAnimation:.

extension UIApplication: DeprecatedStatusBarMethods {

    // tell compiler this is deprecated, too.
    // this would otherwise produce a warning.
    @available(*, deprecated)
    func deprecated_setStatusBarHidden(_ hidden: Bool, with animation: UIStatusBarAnimation) {
        // call the original deprecated method
        self.setStatusBarHidden(hidden, with: animation)
    }
}

Note that you must mark the protocol implementation in the extension as @available(*, deprecated) to silence the compiler deprecation warning. Without this annotation, you would see a warning when calling the original deprecated API.

With those pieces in place, we can call the deprecated API by first casting the type to the protocol type we just defined. This successfully calls the deprecated API and produces no warnings or errors, despite using the Swift compiler flag -warnings-as-errors to treat all warnings as errors.

// no warnings!
(UIApplication.shared as DeprecatedStatusBarMethods).deprecated_setStatusBarHidden(isHidden, with: .fade)

This is obviously very verbose. To mitigate this, you could wrap this in a helper method.

extension UIApplication {
    func myApp_setStatusBarHidden() {
        (self as DeprecatedStatusBarMethods).deprecated_setStatusBarHidden(true, with: .fade)
    }
}

// usage:
UIApplication.shared.myApp_setStatusBarHidden()

Importantly, you cannot directly call the implementation method — the one we annotated with @available(*, deprecated). Doing this results in the compiler producing a warning, as you would expect.

// warning: deprecated API usage
UIApplication.shared.deprecated_setStatusBarHidden(isHidden, with: .fade)

How does this even work?

I am not a Swift compiler expert, but here is my best attempt at an explanation. Hopefully everything up until the call site makes sense, but I will cover that too.

In the implementation of the protocol, we annotate the API using @available(*, deprecated). Without this annotation, the compiler produces a warning at the call site of the original deprecated API. Explicitly annotating the outer declaration func deprecated_setStatusBarHidden(_:with:) as deprecated silences the deprecation warning inside the method implementation. Because this is explicit, the compiler does not need to warn us.
Calling a deprecated method produces a deprecation warning. As noted above, when we call the newly added deprecated method directly on UIApplication.shared, we see warning. This is expected, the method is annotated with @available(*, deprecated).
When we write (UIApplication.shared as DeprecatedStatusBarMethods), we are hiding the concrete type. Then, we are allowed to call the method on the protocol type without any warnings because that method has no annotations. The compiler will lookup the method in the protocol witness table rather than directly in the concrete type. Essentially, we have performed a kind of “type erasure” and are hiding our deprecated code behind the protocol witness table.

Is this practical?

This workaround is rather verbose and somewhat obscure (and kind of obtuse) — but it works. If your project already has a mix of Objective-C and Swift, you are probably better off silencing deprecation warnings using Clang pragmas. If you want to avoid adding Objective-C, this is a viable alternative. However, if your project is using a lot of deprecated APIs, I can see this workaround being quite cumbersome. Of course, the best solution is to stop using deprecated APIs altogether — but, like many aspects of software development, we do not always have that luxury.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

How to automate perfect screenshots for the Mac App Store

2025-03-24T08:21:37-07:00

Meeting the requirements for screenshots is a frustrating experience. On iOS, tooling like SimulatorStatusMagic, Nine41, and fastlane snapshot help make the process easier. However, on macOS there is much less support (and, sadly, demand) for automated tooling — so you are kind of on your own to figure it out. I spent some time recently solving this process for myself. I want to share how I have managed to automate perfect screenshots for the Mac App Store.

Screenshot composition

In a previous post, I discussed how you have two basic “formats” or compositions for Mac app screenshots. The first is taking a screenshot of your app in fullscreen mode, capturing only the app window. The second is capturing your app running on a full Mac desktop where the app is not in fullscreen — that is, capturing the entire desktop with your app window(s), the menu bar, dock, and desktop background photo.

Fullscreen Mac app screenshots are much simpler and easier. All you have to do is screenshot your app window and you’re finished. My focus for this post (and my goal for my screenshots) is to capture full Mac desktop screenshots. Similar to iOS, I want a “perfect” menu bar with no extra icons and a clock showing 9:41 AM, and a nice desktop background photo.

Current options for Mac app screenshots

Unfortunately, fastlane snapshot simply does not work for macOS. (See #11092, #11092-comment-349012721, #11092-comment-349273411, #19864) You could probably get it working on your own, but the maintainers seem uninterested in dedicated long-term support for macOS. So I decided to look for alternatives.

Another possibility is to manually take screenshots of your Mac app and optionally bring those into Photoshop, Acorn, Gimp, or any other image editor for additional editing. This was my approach before, but I found it to be too tedious — even when using some Photoshop templates to make it easier. I need something that can be fully (or mostly) automated.

Automatic screenshots via Xcode

As of Xcode 9, Xcode UITest allows you to capture screenshots during tests. This is the API that fastlane uses under-the-hood for iOS. Again, because fastlane is not an option for macOS, you can implement this yourself. Xcode makes this process rather simple and easy. Here’s a helper method that saves a screenshot.

func saveScreenshot(name: String) {
    let app = XCUIApplication()
    let screenshot = app.windows["main-window"].screenshot()
    let attachment = XCTAttachment(
        uniformTypeIdentifier: "public.png",
        name: name,
        payload: screenshot.pngRepresentation,
        userInfo: nil
    )
    attachment.lifetime = .keepAlways
    self.add(attachment)
}

// usage
saveScreenshot(name: "screenshot-01")

You can write normal UI tests and take screenshots when desired. When the test suite completes, you can navigate to the test results window in Xcode, find the screenshots, and save them.

This solves the problem of automating generating the raw screenshots. Unfortunately, once you have these raw screenshots, you will need to do some post-processing. The screenshots from XCUITest have ugly artifacts in the window corners. They are not correctly cropped and clipped with a transparent background, like when you take a screenshot via the built-in functionality in macOS. See the image below for an example.

From left to right: raw output from Xcode UI Test, the same image after processing, the output from taking a screenshot in macOS.

The first image is what screenshotting via Xcode produces — ugly corners that will display whatever is in the background when your app runs via the UI test suite. The second image is the result after manually processing the image to remove the artifacts. The final image is the output of taking a standard screenshot on macOS. As you can see, my processing is not quite exact, but it is close enough.

Post-processing Xcode screenshots

You could use an image editor like Photoshop, Acorn, or Gimp to round off these corners, but that is quite tedious. I used to use Photoshop with a smart object that would do this. However, that’s still quite manual. The best tool for this is Retrobatch from Gus Mueller — and it is incredible. I love this app.

Using Retrobatch, I created a workflow to round the corners. Through trial and error, I arrived at a corner radius of 24 points. Again, not quite exact (see screenshot above), but close enough for our purposes here. Windows in macOS also have a subtle 1-point border that have a hex color value of #D9D9D9 in light mode and #636363 in dark mode. Retrobatch can also take care of this.

This gives us screenshots of our app windows that are (mostly) equivalent to taking screenshots manually via macOS. First, we use Xcode UITests to get the raw screenshots, then we drop them into Retrobatch for this clean up task. Now we need to get our desktop background.

To get a perfect Mac desktop background, I created a new account on my Mac to avoid having to change any of my own preferences. In the fresh account, I set the wallpaper, configured the menu bar, and set the time manually to 9:41 AM, and then took a screenshot. Here’s an example using Finder as the active app. However, for each of my apps I will install them and make them active so their name displays in the menu bar.

Blank Mac desktop screenshot background

I use the amazing Aqueux wallpapers by Hector Simpson — a wonderful throwback to Mac OS X Tiger. (Back when macOS was actually good.) Note you’ll need to create these backgrounds in both light mode and dark mode if you provide screenshots in both modes for your app.

The final product

Now we have all the pieces we need: the app window screenshots and the desktop background. Before, I was using a Photoshop template to assemble these. Again, that’s too tedious. This is where Retrobatch really shines. Below is a screenshot of my entire Retrobatch workflow.

Retrobatch workflow

Here is what’s happening:

The raw screenshots from Xcode are read from the specified input folder.
The corners get rounded correctly.
It checks if the filename contains “dark”. This is part of my file naming scheme. For screenshots in dark mode, I append “-dark”. The workflow branches based on if the screenshots are in light mode or dark mode, but the steps are equivalent.
The 1-point border is added using the correct color based on light mode or dark mode.
A subtle drop shadow gets added, roughly equivalent to how macOS renders. Again through trial and error, I arrived at a (0,-50) offset, a 70-point blur radius, and 60% opacity.
Next is the overlay step. This overlays the app window screenshot over the desktop background and centers it. The light mode and dark mode branches of the workflow have their respective light and dark desktop backgrounds.
The metadata is deleted, to reduce file size and unnecessary data.
The final images get written to the specified output folder. These images are the full resolution of my 14-inch M3 MacBook Pro desktop. (I use these screenshots to embed in device frames for promotional images on my website.)
There is one final branch that resizes and crops all screenshots to 2880x1800 px because of the archaic requirements of App Store Connect. The Mac App Store does not accept screenshots using the default resolutions of modern M-series MacBooks.

And that’s everything. There was some upfront effort to put all of this together, but now my workflow for generating Mac app screenshots is incredibly simple with minimal manual steps.

Run my Xcode UI test suite to generate the screenshots.
Extract the screenshots from the test results and save them to my Retrobatch input folder.
Run the Retrobatch workflow, which saves everything to the output folder.

Here’s an example of the final product using my app, Taxatio.

Finished screenshot for Taxatio

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

How to remove unwanted Swift Package schemes in Xcode

2025-03-10T10:16:17-07:00

Xcode automatically creates schemes for your app and other targets included in your project, which allow you to build and run those targets. I recently ran into an issue where Xcode was including schemes from third-party Swift Package dependencies in its auto-populated list. This automatic behavior does not cause any problems, but it can be quite annoying and distracting to have unwanted schemes from packages pollute your list of schemes.

This issue has been reported in the developer forums. Apparently, if a Swift package includes a .swiftpm/ directory with .xcscheme files for its own project development, then Xcode will automatically detect and display these schemes in the dropdown list of schemes for your project. This is rather undesirable. It’s an especially frustrating experience because even if you delete them from the list in Xcode, they will eventually reappear when packages get updated or refreshed. For example, you’ll experience this issue with the popular library, CocoaLumberjack, which includes schemes using a .swiftpm/ directory here.

The solution to preventing these package schemes from appearing in Xcode automatically is for package authors to switch to using an .xcworkspace file for their schemes, rather than a .swiftpm/ directory. Here’s an example from the sideeffect.io/AsyncExtensions package.

Curiously, I have also seen schemes appear from packages that use neither .xcworkspace nor .swiftpm, but just a normal .xcodeproj. Why those schemes appear automatically in Xcode is a mystery to me.

* * *

You may not always be able to get package authors to make this change. While you wait for library maintainers to implement changes or accept a pull request (if they ever do), you can use my workaround to delete them from your projects.

Unfortunately, working with Swift packages in Xcode remains a cumbersome experience. Unlike CocoaPods — which adopted the prior art developed by established package managers in other ecosystems by using a specification file and storing package sources in a directory relative to your project — Xcode forces you use an opaque UI to add package dependencies. Even worse, rather than store packages relative to your project, when you add Swift packages to your Xcode project they get stored in ~/Library/Developer/Xcode/DerivedData/<YOUR_APP_NAME-SOME_UUID>/SourcePackages/checkouts/. These implementation details along with the lack of the equivalent of CocoaPods post-install hooks make workarounds more challenging. SwiftPM integration in Xcode was designed by people who think very different. But it’s ok — we can workaround this annoyance, too.

Here’s a script that will delete all .xcscheme files for packages added to your Xcode project. These schemes will then no longer appear in your scheme list.

#!/bin/bash

# Deletes unwanted schemes from SwiftPM packages
# to prevent them from being listed in Xcode.
#
# If a Swift Package includes `.swiftpm/xcode/xcshareddata/xcschemes/`,
# then the schemes will show up in Xcode automatically.

set -eu

SCHEME_DIRS=~/Library/Developer/Xcode/DerivedData/YOUR_APP_NAME*/SourcePackages/checkouts/*/.swiftpm/xcode/xcshareddata/xcschemes
all_dirs=($SCHEME_DIRS)

for each in "${all_dirs[@]}"; do
  if [ -d "$each" ]; then
    rm -rf "$each"/* && rmdir "$each"
  fi
done

You’ll need to either run this script somewhere as part of your build process, or manually invoke it as needed. For example, if your team uses a XcodeGen or a similar tool, you’ll want to run this script after rebuilding your Xcode project. Alternatively, you could add a Build Script Phase to your project that executes the script.

This is not a perfect solution, but it should save you some time.

A few notes:

You’ll need to replace YOUR_APP_NAME with the name of your Xcode project.
If you have multiple projects with the exact same name, this script will match both paths (because YOUR_APP_NAME*/).
Similarly, if you have multiple git checkouts of the same project, this script will match all of them.
All packages are captured by /SourcePackages/checkouts/*/, so there’s no need to enumerate the specific packages causing the problem. This is also convenient because it will catch any future packages that exhibit the same problem.
I tried to use Xcode environment variables to grab the project’s specific DerivedData/ directory, but none of those work. I tried BUILD_DIR, BUILD_ROOT, PROJECT_TEMP_DIR, TARGET_TEMP_DIR, and DERIVED_FILE_DIR. None of them return the correct directory in ~/Library/, but instead return directories relative to your Xcode project that do not exist.
After the script runs for the first time, the schemes may still appear in the list. Restarting Xcode should remove them, or you can manually remove them.
As mentioned above, when packages are updated or redownloaded, the schemes will reappear, so you’ll need to re-run the script after packages are refreshed.

If you’ve been annoyed by random package schemes being listed in your Xcode project, I hope this helps!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

AI Code review is always wrong

2025-03-04T12:44:26-08:00

I work on a team that has enabled an AI code review tool. And so far, I am unimpressed. Every single time, the code review comments the AI bot leaves on my pull requests are not just wrong, but laughably wrong. When its suggestions are not completely fucking incorrect, they make no sense at all.

For example, in Swift you can use optional-chaining or you can unwrap optionals.

struct Job {
    let title: String
}

struct Person {
    let name: String
    let job: Job?
}

let john = Person(name: "John", job: Job(title: "Programmer"))

// Non-optional: access directly
let name = john.name

// Optional-chaining: maybe nil
let jobTitle = john.job?.title

// Unwrapped optional
if let job = john.job {
    print(job.title)
} else {
    print("job is nil")
}

On one of my pull requests, the AI bot recently suggested: “Consider using optional chaining to safely handle nil values. This prevents potential crashes if the value is nil while maintaining the same logical flow.” This would be a good suggestion if you wrote code that force-unwrapped an optional.

// Force-unwrapped: will crash if nil
let jobTitle = john.job!.title

Not only were no values force-unwrapped in the code, but the property the bot mentioned was not optional. The code in question contained two similarly named properties. One of them was optional, one of them was not. The optional property was being unwrapped correctly. The non-optional property was being accessed directly and thus — by definition — did not need to be unwrapped. The bot fundamentally misunderstood this entire concept.

But this is worse than being wrong, because the bot writes with so much conviction and assurance. If I were early in my career, perhaps an intern or a student still learning, I might be persuaded by its imitation intelligence and counterfeit confidence. LLMs are not “intelligent” — they are statistical regurgitation machines whose core features are plagiarism and hallucinations, at best.

These contextless, pretend code reviews are wasting my time. What are we even doing in this industry? Isn’t every corporation in Silicon Valley jam-packed with “the smartest people in the world”? Doesn’t every corporation in Silicon Valley have “job offer rates more competitive than Stanford acceptance rates”? Why can’t one of those people give me a goddamn code review?

Fad-driven development and anti-thought is our new gospel.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Xcode Tip: spell checking

2025-02-24T07:59:46-08:00

Did you know that Xcode can spell check your code and comments? Based on my experience working on large teams and large Xcode projects, this is a little-known feature. I routinely find spelling errors, not only in code comments but in symbol names. For the latter, this is particularly frustrating when a misspelled symbol is widely used because correcting that error — a rename that affects a substantial portion of the codebase — produces a large diff. Once you notice that your entire team has been passing around a “databaesQuery” for six months, it will drive you insane until fixed.

On large teams, large diffs are difficult to get reviewed. But more importantly, the probability for merge conflicts is high. Nothing is worse than having to resolve conflicts dozens of times before you are able to merge. A large rename to correct a spelling error can end up being the same experience has trying to merge a significant refactor — a multi-day effort. That’s not ideal.

Lucky for us, it’s possible to (help) prevent typos from ever getting merged in the first place. In Xcode, you can enable spelling from the Edit menu, Edit > Format > Spelling and Grammar > Check Spelling While Typing. Just like a typical word processor, Xcode will helpfully underline misspelled words and offer to apply corrections.

Even better, Xcode understands variable names and will correctly identify errors in camelCase, snake_case, and other common identifier formats. Xcode also understands programming language keywords and syntax, so func, for example, will not be identified as a spelling error. You can right-click to apply corrections. You can also add words to the dictionary via Right Click > Learn Spelling, which can be useful for domain-specific abbreviations or other non-dictionary terms that are not actual spelling errors.

The only caveat here is that everyone on your team must manually apply spelling corrections. However, perhaps this could be solved with a linter rule or Xcode extension.

Xcode spell checking

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Reading Notes: From misery to boredom to anxiety

2025-02-20T11:28:05-08:00

The zine, We Are All Very Anxious: Six Theses on Anxiety and Why It is Effectively Preventing Militancy, and One Possible Strategy for Overcoming It, was published by The Institute for Precarious Consciousness and CrimethInc in 2014. (Anarchist Library, Zine PDF). I decided to read it again recently because it felt relevant to the current political moment in the US. It is as prescient as ever.

The current fascist takeover of the US government and public institutions is marked primarily by the overwhelming feeling of anxiety — that is, precarity. The ruling class manufactures and perpetuates anxiety and precarity through chaos, misinformation, disinformation, the surreptitious dismantling of the public safety net, and disorderly reversals of established precedents and norms. We can observe this happening each week.

Unfortunately, a large contingent of the working class has been hoodwinked into thinking that the source of their anxiety and precarity is from within their own cohort, rather than deliberately imposed and maintained by the counterfeit populists of the fascist ruling class. As long as we remain anxious, under the oppressive thumb of unelected, extractive billionaires and seedy politicians, resistance against state repression will remain difficult, if not impossible.

I wish I had answers. Until we’re able to effectively counteract our precariousness, let’s hope our peers in the working class wake up soon and realize that immigrants and trans kids are not the problem — and never were.

I highly recommend reading the full zine, it is not very long. Here are my highlights.

“Each phase of capitalism has a particular affect which holds it together. This is not a static situation. The prevalence of a particular dominant affect is sustainable only until strategies of resistance able to break down this particular affect and/or its social sources are formulated. Hence, capitalism constantly comes into crisis and recomposes around newly dominant affects.”

[…]

“Each phase blames the system’s victims for the suffering that the system causes.”

* * *

“In the modern era (until the post-war settlement), the dominant affect was misery. In the nineteenth century, the dominant narrative was that capitalism leads to general enrichment. The public secret of this narrative was the misery of the working class.”

* * *

“When misery stopped working as a control strategy, capitalism switched to boredom. In the mid twentieth century, the dominant public narrative was that the standard of living — which widened access to consumption, healthcare and education — was rising. Everyone in the rich countries was happy, and the poor countries were on their way to development. The public secret was that everyone was bored. This was an effect of the Fordist system which was prevalent until the 1980s — a system based on full-time jobs for life, guaranteed welfare, mass consumerism, mass culture, and the co-optation of the labour movement which had been built to fight misery.”

* * *

“Today’s public secret is that everyone is anxious. Anxiety has spread from its previous localised locations (such as sexuality) to the whole of the social field. All forms of intensity, self-expression, emotional connection, immediacy, and enjoyment are now laced with anxiety. It has become the linchpin of subordination.”

* * *

“The present dominant affect of anxiety is also known as precarity. Precarity is a type of insecurity which treats people as disposable so as to impose control. Precarity differs from misery in that the necessities of life are not simply absent. They are available, but withheld conditionally.”

“Precarity leads to generalised hopelessness; a constant bodily excitation without release. Growing proportions of young people are living at home. Substantial portions of the population — over 10% in the UK — are taking antidepressants. The birth rate is declining, as insecurity makes people reluctant to start families.”

* * *

“Anxiety is personalised in a number of ways — from New Right discourses blaming the poor for poverty, to contemporary therapies which treat anxiety as a neurological imbalance or a dysfunctional thinking style. A hundred varieties of “management” discourse — time management, anger management, parental management, self-branding, gamification — offer anxious subjects an illusion of control in return for ever-greater conformity to the capitalist model of subjectivity.”

* * *

“Then there’s the self-esteem industry, the massive outpouring of media telling people how to achieve success through positive thinking — as if the sources of anxiety and frustration are simply illusory. These are indicative of the tendency to privatise problems, both those relating to work, and those relating to psychology.”

“Earlier we argued that people have to be socially isolated in order for a public secret to work. This is true of the current situation, in which authentic communication is increasingly rare. Communication is more pervasive than ever, but increasingly, communication happens only through paths mediated by the system. Hence, in many ways, people are prevented from actually communicating, even while the system demands that everyone be connected and communicable. People both conform to the demand to communicate rather than expressing themselves, and self-censor within mediated spaces.”

* * *

“If the first wave provided a machine for fighting misery, and the second wave a machine for fighting boredom, what we now need is a machine for fighting anxiety — and this is something we do not yet have.”

* * *

“Structurally, the system is vulnerable. The reliance on anxiety is a desperate measure, used in the absence of stronger forms of conformity. The system’s attempt to keep running by keeping people feeling powerless leaves it open to sudden ruptures, outbreaks of revolt. So how do we get to the point where we stop feeling powerless?”

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Type erasure for Equatable and Hashable types in Swift: Lessons from ReactiveCollectionsKit

2025-02-19T19:29:42-08:00

Type erasure is a method to abstract and encapsulate heterogenous generic types inside a single non-generic concrete type. In programming languages with generic types, this is a mechanism for runtime polymorphism which allows you circumvent the constraints of generics at compile time. In the early days of Swift, generics were more challenging to work with — in particular, protocols with associated types. As of Swift 5.7 (and SE-0309: Unlock existentials for all protocols), type erasure is now a feature of the Swift compiler. However, there are still situations where you may need to manually write your own type-erased wrappers.

In this post, I’m going to use ReactiveCollectionsKit as a case study for some of the challenges you may face with generic programming in Swift and how we can use type erasure to solve them. I’d recommend reading the other posts in my series on ReactiveCollectionsKit.

The idea behind type erasure is that you need to “erase” the type information for multiple heterogenous types in order to refer to them as a single homogenous type. In other words, type erasure allows you to hide differing underlying types behind a single type.

A brief overview and history of type erasure in Swift

This is a brief and incomplete overview of type erasure in Swift. I will be glossing over many details in order to establish a rudimentary understanding of core concepts for the purposes of this post.

Before SE-0309 (see also: SE-0353 and SE-0346), the only option was to write your own type-erased wrapper types. Even if you have never manually implemented type erasure in your own projects, you have used it. The Swift Standard Library has a number of type-erased types. One of the most common is probably AnyHashable because of its use with Dictionary. There’s also AnyCollection, AnySequence, AnyIndex, and many more. If you’re curious how these are implemented, you can view the Standard Library source code.

The convention is to prefix these wrapper types with “Any”. The strategy for implementing them is essentially copying all properties and functions from the generic type into the “Any” type, or simply storing an Any property and forwarding all members of the wrapper type to the underlying type.

Let’s use AnyHashable as a quick example. Below is a simplified implementation to demonstrate core concepts. Note that the actual implementation is significantly more complex.

struct AnyHashable: Hashable {
    var base: Any

    init<H: Hashable>(_ base: H) {
        self.base = base
    }
}

Notice that the initializer is generic. It receives a concrete type, H, that conforms to Hashable. However, it stores the base property as Any, thus erasing the concrete type. Importantly, AnyHashable also conforms to Hashable. The purpose of this is to forward the Hashable implementation to the underlying property stored in base.

But how do we forward the Hashable implementation to base if it is declared as Any? If type erasure can be described as “boxing” up a type, then we need to “unbox” the type to transform it back to its concrete type. This process of opening an Any or any type is known as reification. In Swift, we do this using the as? operator.

Below is a simplified example of implementing Hashable, which includes the hash(into:) and == functions. These calls are forwarded to the underlying base property.

struct AnyHashable: Hashable {
    var base: Any

    init<H: Hashable>(_ base: H) {
        self.base = base
    }

    // Implement Hashable

    func hash(into hasher: inout Hasher) {
        guard let base = self.base as? (any Hashable) else {
            fatalError("base should be hashable")
        }

        hasher.combine(base)
    }

    static func == (left: Self, right: Self) -> Bool {
        guard let leftBase = left.base as? (any Equatable),
              let rightBase = right.base as? (any Equatable) else {
            return false
        }

        return _isEqual(lhs: leftBase, rhs: rightBase)
    }

    private static func _isEqual<T: Equatable, U: Equatable>(lhs: T, rhs: U) -> Bool {
        if let rhsAsT = rhs as? T {
            return lhs == rhsAsT
        }

        if let lhsAsU = lhs as? U {
            return lhsAsU == rhs
        }

        return false
    }
}

Equality is especially tricky. Notice that we have to attempt to cast each side to the same concrete type before continuing with the comparison. This is because the == operator operates on two values of the same type. Otherwise, == would not make any sense — for example, attempting to compare an Int and a String is invalid.

Using AnyHashable allows us to store heterogenous types in a homogenous way. For example, Array can only store a collection of values of a single type. The following produces a compiler error:

let array = ["string", 42, 3.14, false]

However, we could instead store these values as AnyHashable, which works:

let array = [AnyHashable("string"), AnyHashable(42), AnyHashable(3.14), AnyHashable(false)]

Since Swift 5.7 and SE-0309: Unlock existentials for all protocols, type erasure is now a feature of the Swift compiler. This proposal introduced the any keyword, allowing you to write any MyProtocol to erase the generic constraints of MyProtocol. You no longer need to manually write these type-erased wrappers in most scenarios. Continuing with the AnyHashable example, you could instead write any Hashable and eliminate the need for the custom wrapper type.

However, while using any Hashable versus AnyHashable may seem equivalent, there are some important distinctions. Using any Hashable gives you an existential type, an abstract representation, while AnyHashable is a concrete type. We can observe the difference in behavior by trying to compare values of each type.

let one: any Hashable = 1
let two: any Hashable = 2

one == two // Error: Binary operator '==' cannot be applied to two 'any Hashable' operands

Attempting to compare any two values of type any <Some Protocol> will always produce an error. As mentioned above, this is because the == operator compares two values of the same (concrete) type. At compile time, it is not known what is the actual type of any <Some Protocol>, which is abstract — multiple concrete types could implement the protocol and different types cannot be Equatable, for example comparing a String and an Int does not make sense.

On the other hand, comparison of AnyHashable values works because it is a concrete type. That is, the == operator works given two AnyHashable values.

let one: AnyHashable = 1
let two: AnyHashable = 2

one == two // this works, returns false

Doug Gregor wrote an excellent post on type erasure in Swift as part of his “Swift for C++ Practitioners” series. While it is aimed at explaining Swift to C++ developers, it covers Swift in detail and I highly recommend reading it for a deeper dive. I also recommend reading this post on type erasure from Bruno Rocha.

Generics and type erasure in ReactiveCollectionsKit

Now let’s dive into the details of ReactiveCollectionsKit to see a real world example of the challenges presented by generic programming and how we can use type erasure to solve them. If you need a refresher on ReactiveCollectionsKit, you review the other posts in this series.

The core component in ReactiveCollectionsKit is the CellViewModel, which represents a cell in a collection view. Clients can provide any type they want to the library, as long as it conforms to the CellViewModel protocol. Here’s a simplified definition of CellViewModel for the purposes of this post. (You can find the full source on GitHub.) For folks familiar with the library, SupplementaryViewModel follows a similar design.

protocol CellViewModel: DiffableViewModel {
    associatedtype CellType: UICollectionViewCell

    var shouldHighlight: Bool { get }

    func configure(cell: CellType)

    func didSelect()
}

protocol DiffableViewModel: Identifiable, Hashable {
    var id: AnyHashable { get }
}

Note that CellViewModel inherits from DiffableViewModel, which powers how diffing works in the library. Also notice that CellViewModel is generic on the type of cell this view model configures. This is important — it allows clients to mix-and-match the types of cells they display in a collection and provides an ergonomic, type-safe API rather than having to cast from UICollectionViewCell to their specific cell subclass.

Here’s an example concrete implementation of a CellViewModel.

struct PersonCellViewModel: CellViewModel {
    let person: PersonModel

    // MARK: CellViewModel

    var id: UniqueIdentifier { self.person.id }

    var shouldHighlight = true

    func configure(cell: PersonCell) {
        cell.title = self.person.name
        // additional configuration
    }

    func didSelect() {
        // handle selection
    }
}

All cells in a collection view belong to a section. In ReactiveCollectionsKit, sections are modeled by SectionViewModel. This is where the challenges arise from the associatedtype in CellViewModel.

The interface we want for SectionViewModel would look something like the following. Again, this definition is simplified for the purposes of this post. Note that sections are also diffable, thus SectionViewModel also inherits from DiffableViewModel.

struct SectionViewModel: DiffableViewModel {
    let cells: [CellViewModel] // Error due to generic constraints via associatedtype
}

This does not work, because of the generic constraints in CellViewModel. To solve this, we could make SectionViewModel generic on the type of cell:

struct SectionViewModel<Cell: CellViewModel>: DiffableViewModel {
    let cells: [Cell]
}

However, this defeats the entire purpose as it restricts a section to displaying a single type of cell. The solution offered by the compiler is to use any.

struct SectionViewModel: DiffableViewModel {
    let cells: [any CellViewModel]
}

This almost works. In many contexts, you could stop here. However, this presents a new problem for ReactiveCollectionsKit. Sections and cells are diffable via DiffableViewModel, which inherits from Equatable and Hashable. Without being equatable and hashable, we have no mechanism to perform diffs on cells or sections.

As mentioned above, values with the type any <Some Protocol> are not Equatable — and thus, not Hashable, which inherits from Equatable. The problem here is that any CellViewModel is not Equatable. This is why we need to introduce a new type-erased wrapper for CellViewModel. We’ll call it AnyCellViewModel. This results in the following interface for SectionViewModel:

struct SectionViewModel: DiffableViewModel {
    let cells: [AnyCellViewModel]
}

Let’s write an initial implementation of AnyCellViewModel.

struct AnyCellViewModel: CellViewModel {
    // MARK: DiffableViewModel

    var id: AnyHashable { self._id }

    // MARK: CellViewModel

    typealias CellType = UICollectionViewCell

    var shouldHighlight: Bool { self._shouldHighlight }

    func configure(cell: UICollectionViewCell) {
        self._configure(cell)
    }

    func didSelect() {
        self._didSelect(coordinator)
    }

    // MARK: Private

    private let _id: AnyHashable
    private let _shouldHighlight: Bool
    private let _configure: (CellType) -> Void
    private let _didSelect: () -> Void

    // MARK: Init

    init<T: CellViewModel>(_ viewModel: T) {
        self._id = viewModel.id
        self._shouldHighlight = viewModel.shouldHighlight
        self._configure = {
            viewModel.configure(cell: $0 as! T.CellType)
        }
        self._didSelect = {
            viewModel.didSelect()
        }
    }
}

The strategy here is to copy all properties and methods from the CellViewModel protocol. Properties are copied directly and methods are copied as closure properties. Next, AnyCellViewModel implements the CellViewModel protocol and forwards all implementations to the copied properties. Notice we have to force-cast the cell type in the _configure() closure from the generic UICollectionViewCell from AnyCellViewModel to the specific cell subclass provided by the concrete CellViewModel we receive in the initializer. This might seem dangerous, but we know this is a safe operation.

This works as far as it satisfies the type system. However, there is more to do. The above definition of AnyCellViewModel will not work for diffing. We need to implement Equatable and Hashable, and we need more information from the original viewModel instance to do it. So far, AnyCellViewModel only knows about the members of CellViewModel. Yet, clients can provide any type that conforms to CellViewModel to the library. Consider the example above using PersonCellViewModel:

struct PersonCellViewModel: CellViewModel {
    let person: PersonModel

    // ... implementation continues ...
}

In this situation, being Equatable and Hashable involves comparing the value stored in let person: PersonModel. We cannot store a PersonModel property on AnyCellViewModel — that does not generalize. We also cannot make AnyCellViewModel generic, which defeats the entire purpose of type erasure. What we need to do is store the entire PersonCellViewModel inside AnyCellViewModel in a way that is generalized (though not using generics), but also allows us access Equatable and Hashable. That is, we cannot simply use Any.

What we can do is store the concrete view model as an AnyHashable value:

struct AnyCellViewModel: CellViewModel {
    // ... implementation continues ...

    private let _viewModel: AnyHashable

    init<T: CellViewModel>(_ viewModel: T) {
        self._viewModel = viewModel

        // ... implementation continues ...
    }
}

This erases the generic constraints of viewModel imposed by CellViewModel while preserving access to Equatable and Hashable. Now, we can simply forward the implementations from these two protocols:

extension AnyCellViewModel: Equatable {
    static func == (left: AnyCellViewModel, right: AnyCellViewModel) -> Bool {
        left._viewModel == right._viewModel
    }
}

extension AnyCellViewModel: Hashable {
    func hash(into hasher: inout Hasher) {
        self._viewModel.hash(into: &hasher)
    }
}

This resolves all of our issues. Clients receive an ergonomic, type-safe, generic API for CellViewModel. The library can successfully type erase all the values provided as AnyCellViewModel. And diffing just works in any and every scenario using Equatable and Hashable.

We can provide a convenience method to facilitate type erasure:

extension CellViewModel {
    func eraseToAnyViewModel() -> AnyCellViewModel {
        // prevent "double erasure"
        if let erasedViewModel = self as? AnyCellViewModel {
            return erasedViewModel
        }
        return AnyCellViewModel(self)
    }
}

Additionally, you’ll notice that SectionViewModel provides a number of convenience initializers using generics. In scenarios where you do not have mixed data types, the generic initializers allow you ignore this implementation detail and the library handles the type erasure for you. Below is a simplified example of one convenience initializer for SectionViewModel.

extension SectionViewModel {
    init<Cell: CellViewModel>(cells: [Cell]) {
        self.cells = cells.map { $0.eraseToAnyViewModel() }
    }
}

This initializer receives a single concrete type, Cell, that conforms to CellViewModel. It performs the type erasure internally. This greatly improves the usability of the API and helps reduce the burden on clients of having to always convert to AnyCellViewModel.

Conclusion

While generic programming is a powerful tool, there are often times where you may find yourself fighting with the type system. If your solution requires the use of generics but you are struggling to reconcile heterogenous types with generic constraints, a great tool to reach for is type erasure via any. If that does not work, like in the case of ReactiveCollectionsKit, you can write your own type-erased wrapper type. Importantly, if you need to preserve conformance to Equatable and Hashable, you can utilize AnyHashable as demonstrated above.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

UIKit DiffableDataSource API inconsistencies with Swift Concurrency annotations explained

2024-12-19T11:54:07-08:00

UIKit provides two diffable data source APIs, one for collections and one for tables. Recently, while working on ReactiveCollectionKit, I noticed that the APIs were updated for Swift Concurrency in the iOS 18 SDK, but the annotations were inconsistent with the documentation.

The main entry point into working with snapshots is the apply(_:animatingDifferences:completion:) method. There’s one for UICollectionViewDiffableDataSource and one for UITableViewDiffableDataSource. The method signatures and docs are identical for both. They were both updated with @MainActor and @preconcurrency annotations for iOS 18.

@MainActor @preconcurrency
func apply(
    _ snapshot: NSDiffableDataSourceSnapshot<SectionIdentifierType, ItemIdentifierType>,
    animatingDifferences: Bool = true,
    completion: (() -> Void)? = nil
)

However, the documentation states:

You can safely call this method from a background queue, but you must do so consistently in your app. Always call this method exclusively from the main queue or from a background queue.

This is a problem if you were calling these methods from a background queue and attempted to upgrade to Swift 6. This is because Swift 6 Concurrency makes calling this method from a background queue impossible. The compiler will not let you do it because it is @MainActor rather than nonisolated. So… what’s the deal?

I reached out to Tyler Fox from the UIKit team on Mastodon to ask if this was a mistake. As it turns out, it is not a mistake and his reply was incredibly helpful and insightful. For posterity and documentation purposes (and because social media is ephemeral and unreliable), I’m going to reproduce his entire response here:

The main actor annotation is intentional, see the full explanation attached. There isn’t a perfect solution here though, unfortunately.

Also be sure to refer to this documentation for additional best practices around diffable data source, especially around using proper identifiers (instead of lightweight data structures) as this is key to efficient performance with large data sets.

This was an intentional change made to the diffable data source API in the iOS 18 SDK. The existing diffable data source API and implementation has strict concurrency requirements that do not translate into Swift Concurrency (specifically, it must be used from a single dispatch queue, which nonisolated cannot express).

We have seen a number of issues stemming from usage of diffable data source on background queues/threads, and the performance benefits of doing this are generally minimal due to the fact that only the diffing of identifiers in the old & new snapshots happens on the background queue/thread; the work to set up and execute the Ul updates and animations for cells always happens on the main thread. Therefore, we made the decision to restrict diffable data source to the main actor when using Swift Concurrency, as this ensures correctness in all cases and is nearly always the best approach anyways. If you were previously applying snapshots from a background queue, we recommend you update your implementation to do so on the main queue instead.

If you are concerned about performance, you should measure and profile your app with large data sets using Instruments (e.g. Time Profiler). You will almost certainly find that the diffing portion of the work (which was the only portion eligible to occur off the main thread) is negligible compared to the work involved in creating cells, measuring their sizes, performing layout, etc as part of Ul updates. If you do see any significant work happening during the diffing process, make sure you are using proper identifiers, and revisit the hashing and equality implementations of your identifiers. If your snapshots contain tens or hundreds of thousands of items (or more), you may wish to use techniques such as pagination to reduce the total number of items populated in the Ul at once.

Finally, if you do discover a use case where you believe background queue diffing is essential, please do submit feedback so we can understand the use case and make recommendations or consider potential enhancements to the AP to better support it.

If you were running into issues with these APIs or were confused by the discrepancy in the docs, I hope this helps! The inconsistency remains in the written documentation, which is not ideal. But, I’m very grateful that Tyler took the time to reply and clear up the confusion. Thanks Tyler!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Diffing in ReactiveCollectionsKit: Understanding Identity and Equality

2024-10-23T12:43:45-07:00

Welcome to the next post in my series about ReactiveCollectionsKit. Today I want to discuss diffing. Understanding diffing requires understanding two core concepts: identity and equality. These are two ideas that are also relevant and applicable to programming in general, and can often be confusing for newcomers.

In ReactiveCollectionsKit, diffing is modeled by the DiffableViewModel protocol, which encapsulates the definitions of both identity and equality.

typealias UniqueIdentifier = AnyHashable

protocol DiffableViewModel: Identifiable, Hashable, Sendable {
    var id: UniqueIdentifier { get }
}

All view model types in the library inherit from DiffableViewModel — this includes CellViewModel, SupplementaryViewModel, SectionViewModel, and CollectionViewModel. As you can see, diffability is composable. Cells and supplementary views make up a section, while sections make up a collection. Each level of your model can be diffed.

This protocol builds upon the Swift Standard Library. It requires you to provide a single id property, which can be anything that is hashable. This property is inherited from the Identifiable protocol, which is generic. Thus, ReactiveCollectionsKit refines the definition to enforce that id is an instance of AnyHashable. Most commonly, the identifier is a String, but it could be an Int or any custom type. In fact, you could return self for this property in your CellViewModel definition.

The protocol also inherits from Hashable, which inherits from Equatable. This enforces that user-defined view model instances are both hashable and equatable. In Swift, the compiler can synthesize these protocol requirements for you if all properties of a type are Hashable as well. This helps remove a lot of boilerplate in ReactiveCollectionsKit when defining your CellViewModel types.

Altogether, this means diffing requires three pieces of information in order to work correctly, id, ==, and hash(into:).

// Identifiable
var id: UniqueIdentifier { get }

// Hashable
func hash(into hasher: inout Hasher)

// Equatable
static func == (left: Self, right: Self) -> Bool

Identity

Identity concerns itself with permanently and uniquely identifying a single instance of an object. An identity never changes. Identity answers the question “who is this?” For example, a passport encapsulates the concept of identity for a person. A passport permanently and uniquely identifies and corresponds to a single person. (For the sake of this example, let’s pretend that people cannot have multiple passports.) Identity is captured by the Identifiable protocol and the corresponding id property.

Equality

Equality concerns itself with ephemeral traits or properties of a single unique object that change over time. Equality answers the question “which of these objects with this specific id is the most up-to-date?” For example, a person is a unique entity, but they can change their hairstyle, they can wear different clothes, and can generally change any aspect of their physical appearance. While we can uniquely identify a person using their passport on any day, their physical appearance changes day-to-day or year-to-year. Equality is captured by the Hashable (and Equatable) protocol and the corresponding == and hash(into:) functions.

Becoming diffable

Using this example, consider constructing a list of people to display in a collection. We can uniquely identify each person (using id) in the collection. This allows us to determine (1) if they are present, (2) their precise position, (3) if they have been inserted, deleted, or moved. Next, we can determine if they have changed (using ==) since we last saw them. This allows us to determine when a unique person in the collection needs to be reloaded or reconfigured.

In other words, identity concerns itself with the structure of the collection — where is each item located (or not)? On the other hand, equality concerns itself with the individual state of each item — is that item up-to-date?

Both IGListKit and ReactiveLists got this correct, but their implementations are more cumbersome and manual. ReactiveCollectionsKit improves upon both of these implementations with the DiffableViewModel protocol above, and by harnessing Swift’s type system. Identifiers can be anything that is hashable and because Swift can automatically synthesize conformances to Hashable and Equatable, clients can get all of that functionality for free.

If you need to optimize your Hashable and Equatable implementations, you can manually implement the protocols in your view models. The primary motivation for overriding your Hashable and Equatable implementations is performance. You want your equality comparisons for diffing to be fast. This also includes your id property from DiffableViewModel. These three definitions — id, ==, and hash(into:) — will be the main bottleneck for performance when it comes to diffing. Make sure they are fast.

Shortcomings in UIKit

Most importantly, this brings me to why a library like ReactiveCollectionsKit is necessary.

The collection view diffing APIs in UIKit do not handle equality. UICollectionViewDiffableDataSource only concerns itself with identity. That is, it handles the structure (inserts/deletes/moves) for you, but you must handle reload (or reconfigure) for item property changes. (See: Tyler Fox.) In my opinion, UIKit got this wrong. The diffing APIs should have also handled equality, like IGListKit and ReactiveLists.

If you use UICollectionViewDiffableDataSource out-of-the-box and do not check for item equality and reconfigure those items, then the data in your collection or list will not update. The structure of your collection will update — that is, items will be correctly inserted, deleted, or moved, but an item will not refresh if it has been updated in-place.

Correctly checking equality for cells, supplementary views, and sections in order to reload or reconfigure them accordingly is not a trivial task. You can find the source code here. I’ve annotated it heavily with comments to explain what is happening and why.

This is one of the primary motivations for this library. It does not merely wrap the underlying diffing APIs and reduce boilerplate, it provides critical functionality for making lists and collections work fully and correctly. When using UICollectionViewDiffableDataSource, you must track property changes for all items in the collection on your own, and then reload or reconfigure those items accordingly. When using ReactiveCollectionsKit, all of this work is handled automatically for you.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Introducing ReactiveCollectionsKit: A Swift replacement for IGListKit

2024-10-18T12:30:18-07:00

I recently released a new open source project called ReactiveCollectionsKit. It is a modern, fast, and flexible library for building data-driven, declarative, reactive, and diffable collections and lists for iOS. This library is the culmination of everything I learned from building and maintaining IGListKit, ReactiveLists, and JSQDataSourcesKit. The 4th time’s a charm! 😅 🍀 I truly hope this is the last UICollectionView library I ever write and maintain. I think it will be. You can find the documentation here.

A very brief history

I started doing early prototyping for this library a few years ago, but then other projects (and life in general) took priority. I stopped working on it for a while. I finally came back to the project earlier this year and did a “soft” initial release a few months ago. Since then, I’ve been steadily working on improvements and new features. I’ve also started to get some interest in the project and there have been a few contributors helping out and making significant contributions. Notably, this library is now being used in Duolingo, which I helped initiate and integrate.

ReactiveCollectionsKit contains a number of improvements, optimizations, and refinements over the aforementioned libraries — IGListKit, ReactiveLists, and JSQDataSourcesKit. I have incorporated what I think are the best ideas and architecture design elements from each of these libraries, while eliminating or improving upon the shortcomings. Importantly, this library uses modern UICollectionView APIs (like UICollectionViewDiffableDataSource), which were unavailable when the previous libraries were written.

ReactiveCollectionsKit has no third-party dependencies and is written in Swift.

What about SwiftUI?

Of course, the obvious question is: isn’t SwiftUI the future? It probably will be — eventually. But the difficult truth is that it simply isn’t right now. Why build another UIKit-based library? SwiftUI performance is still a significant issue, not to mention all the bugs, missing APIs, and lack of back-porting new APIs to older OS versions. SwiftUI works best when you only use the latest SDKs and target the latest operating systems. Yet, most of us must support older versions of iOS. Even then, for any sufficiently advanced app SwiftUI alone will not suffice.

SwiftUI still does not provide a proper UICollectionView replacement. Yes, Grid exists but it is nowhere close to a replacement for UICollectionView and the power of UICollectionViewLayout. While SwiftUI’s List is pretty good much of the time, performance can still suffer. Also, both LazyVStack and LazyHStack suffer from severe performance issues when you have large amounts of data.

Luckily, SwiftUI provides solid APIs for integration with UIKit so you can easily use ReactiveCollectionsKit in a SwiftUI-based view or app.

ReactiveCollectionsKit overview

The general idea behind ReactiveCollectionsKit is about declaratively defining your collection or list using an MVVM-style separation of concerns. (This was largely inspired by ReactiveLists.) The library does not care what your data models are, you are only responsible for mapping your model objects to the view models that you then provide to the library.

Here’s a brief example of building a list from an array of data models.

// array of some data models
let models = [MyModel(), MyModel(), MyModel()]

// create cell view models from the data
let cells = models.map { MyCellViewModel($0) }

// create the sections with cells
let section = SectionViewModel(id: "my_section", cells: cells)

// create the collection with sections
let collection = CollectionViewModel(sections: [section])

// initialize the driver with the view model and view
let listLayout = UICollectionViewCompositionalLayout.list(using: .init(appearance: .grouped))
let collectionView = UICollectionView(frame: frame, collectionViewLayout: listLayout)

let driver = CollectionViewDriver(view: collectionView, viewModel: collection)

The collection view is updated and animated automatically. When your data changes, simply regenerate your CollectionViewModel (like above) and send this to the CollectionViewDriver instance.

// when the models change, generate a new view model (like above)
let updated = CollectionViewModel(sections: [section1, section2])

driver.update(viewModel: updated)

There is also an extensive example project included in the repo on GitHub.

Architecture and design

I want to share some high-level notes on the architecture and core concepts in ReactiveCollectionsKit, along with comparisons to the other libraries I have worked on — IGListKit, ReactiveLists, and JSQDataSourcesKit. This section assumes some familiarity with all four libraries. However, even if you have never used them, it is still possible to follow along.

The CellViewModel is the fundamental or “atomic” component in the library. It encapsulates all data, configuration, interaction, and view registration for a single cell. This is similar to ReactiveLists. In IGListKit, this component corresponds to IGListSectionController.

For brevity and clarity, here’s a simplified definition of CellViewModel:

protocol CellViewModel {
    associatedtype CellType: UICollectionViewCell

    var id: UniqueIdentifier { get }

    var registration: ViewRegistration { get }

    func configure(cell: CellType)

    func didSelect(with coordinator: CellEventCoordinator?)
}

The CollectionViewModel defines the entire structure of the collection. It is an immutable representation of your collection of models, which can be anything. It is composed of SectionViewModel objects that define sections, which are composed of the aforementioned CellViewModel objects. A section also defines headers, footers, and supplementary views.

The CollectionViewDriver is the primary entry point into the library. This component owns the CollectionViewModel, is responsible for diffing and applying updates, and manages the UICollectionView. The “driver” terminology is borrowed from ReactiveLists. This component is more or less equivalent to the IGListAdapter found in IGListKit.

Together, these core components allow for uni-directional data flow. The general workflow is:

Fetch or update your data models
From those models, generate your CellViewModel objects
Construct your SectionViewModel objects and the final CollectionViewModel
Send the CollectionViewModel to the CollectionViewDriver, which will then perform a diff and update the view

Review of prior art

Here I want to address some of the main the pros and cons of IGListKit, ReactiveLists, and JSQDataSourcesKit. Again, this section assumes some familiarity with all four libraries. But, it should still be possible to follow along.

IGListKit

The main shortcomings of IGListKit are the lack of expressivity in Objective-C’s type system, some undesirable boilerplate set up, mutability, and using sections as the base or fundamental component of a list or collection. The library has added annotations to make interoperability with Swift significantly better, but it is not quite the same as a native Swift API. The extra boilerplate involved is also largely because of the nature of Objective-C, which is simply more verbose.

While IGListKit is general-purpose, much of the design is informed by what we needed specifically at Instagram. It is centered around the concept of lists (like a News Feed) rather than grids or collections, for obvious reasons. A shortcoming of IGListKit is that the “atomic” component is an entire section of multiple items. The section-based design was informed by how lists were architected in the Instagram feed, where each post was its own section. A section in IGListKit could have a single item and in this scenario it more closely resembles a CellViewModel in ReactiveCollectionsKit.

What IGListKit got right was diffing — in fact, we pioneered that entire idea. (H/T Ryan Nystrom). The diffing APIs in UIKit came after we released IGListKit and were heavily influenced by what we accomplished. IGListKit also manually implemented and supported many advanced layout features that are now provided out-of-the-box by UICollectionViewCompositionalLayout. IGListKit’s section-based design was also largely a product of the limitations of the existing layout APIs. All we had back then was UICollectionViewFlowLayout.

IGListKit is very imperative and mutable. After you hook-up your IGListAdapter and IGListSectionController objects, you update sections in-place. IGListKit encourages immutable data models but this is not enforceable in Objective-C, nor is it enforced in the API. IGListKit does have uni-directional data flow in some sense, but you provide your data imperatively via IGListAdapterDataSource which also requires you to manually manage a mapping of your data model objects to their corresponding IGListSectionController objects. With this section-based approach, clients are also responsible for manually reporting the number of items in the section.

ReactiveCollectionsKit removes all the boilerplate required by IGListKit. For example, determining the number of items in a section is derived automatically from the structure of the data itself.

ReactiveLists

The main shortcomings of ReactiveLists are that it uses older UIKit APIs and a custom, third-party diffing library. It maintains entirely separate infrastructure for tables and collections, which duplicates a lot of functionality. There’s a TableViewModel for constructing table views and a CollectionViewModel for constructing collection views, which use UITableView and UICollectionView under-the-hood, respectively. This is because ReactiveLists pre-dates the modern collection view APIs for diffing and making list layouts using collection view. ReactiveLists is also a bit incomplete as we only implemented the APIs we needed at PlanGrid.

What ReactiveLists got right was a declarative API, defining an immutable model of your list or collection, using an individual cell as the base or fundamental component, and uni-directional data flow. With ReactiveLists, you declaratively define your entire collection view model and regenerate it whenever your underlying data model changes. ReactiveCollectionsKit borrowed this directly and improved upon it. Namely, ReactiveCollectionsKit uses generics to allow you to specify the exact type of UICollectionViewCell that your view model configures instead of having to cast (using as!) to your specific cell subclass.

JSQDataSourcesKit

JSQDataSourcesKit in some sense was always kind of experimental and academic. It doesn’t do any diffing and also has separate infrastructure for tables and collections like ReactiveLists, as it similarly pre-dated those modern collection view APIs for making list layouts. It was primarily concerned with constructing type-safe data sources that eliminated the boilerplate associated with UITableViewDataSource and UICollectionViewDataSource. Ultimately, the generics were too unwieldy — especially at the time, given the state of generics in Swift. See my post, Deprecating JSQDataSourcesKit, for more details. What JSQDataSourcesKit got right was the idea of using generics to provide type-safety, though it was not executed very well.

Goals

The primary goals of ReactiveCollectionsKit are to remove all of the boilerplate associated with building lists and collections, and making your views effortless to update. See the example code above.

UIKit has advanced a lot over the years, but correctly setting up a UICollectionViewDiffableDataSource is quite a bit of work. It is tedious and still requires a lot of boilerplate. It is also error prone when it comes to getting diffing to work correctly. (More on that in a future post.)

More specifically, when using this library, you no longer need to interact with any of these collection view APIs:

reloadData()
reconfigureItems(at:)
reloadSections(_:)
reloadItems(at:)
performBatchUpdates(_:completion:)
All UICollectionViewDataSource methods
All UICollectionViewDelegate methods

The benefit and delight in using ReactiveCollectionsKit is that you simply define the structure of your data. You create your collection of items, organize them into sections, and pass this to the library to handle everything else.

Future Work

All of this experience and knowledge has culminated in me writing this new library. ReactiveCollectionsKit aims to keep all the good ideas and designs from these other libraries, while also addressing their shortcomings. I wrote or maintained all of them, so hopefully I got it right this time!

While this library is in a great state and ready for production, it is not yet finished. There is plenty to do! The most commonly used collection view APIs have been implemented, but there are some missing features — like supporting expanding/collapsing sections, for example. Another big feature on my list is to implement a more SwiftUI-like API using Swift result builders.

If you are interested in getting involved, please open an issue or send me a pull request!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Kintsugi

2024-10-16T11:51:41-07:00

Kintsugi — no, not that Kintsugi — is the the Japanese art of repairing broken pottery. The process involves mending the breaks in the ceramics with urushi lacquer, essentially gluing the pieces together and filling in any gaps to smooth it out. At the end, you finish off the cracks with a gold powder, which highlights and emphasizes the flaws in the piece rather than attempting to conceal them. The result is a restored piece of pottery or teaware that can now be put back to use.

However, Kintsugi is not merely a practice centered around mending shattered ceramics. It is also a philosophy about embracing imperfections and the history that produced them. Kintsugi reorients us into treating flaws and breakage as things that are inherent to an object — and to ourselves. Imperfections are part of us and our history, and so is their repair. Kintsugi deliberately accentuates and celebrates the cracks of a formerly broken piece of pottery with gold, rather than trying to hide or disguise them. It is a beautiful thing.

* * *

About a year ago, I dropped the lid of my favorite teapot, shattering it into multiple pieces. It was a Yixing clay pot that I had seasoned and used for exclusively brewing pu-erhs. With high-end clay teaware, you typically choose only one kind of tea to brew. This is because the unglazed surfaces of the pot absorb traces of the tea. Think of it like seasoning a cast iron skillet. Yixing clay teaware is not cheap, but the burden of this accident was not merely a monetary loss. This pot also represented an investment in brewing pu-erhs — for years.

I was so sad. My favorite pot for my favorite style of tea was now unusable. I adore this pot. This pot is one of a kind — handmade, not mass produced. I had to figure out how to fix it. I found a kintsugi repair kit online and did my best. The process involves 6 distinct steps. Each step takes a couples hours and you need to wait about a week after each step for things to dry. The entire process from start to finish should last about 2 months — if you are diligent. If you are like me, this 2-month project will be spread out over an entire year. I can’t say I’m proud of that, but that’s simply how most of my side projects go — because life keeps happening. We’re embracing imperfections, right? 😅

If you are interested in the complete process, you can watch this tutorial video that accompanies the repair kit.

I’m certainly no expert in kintsugi. And I’m not sure if kintsugi is even the recommended approach for repairing Yixing clay. I’m willing to bet this is not the best option. However, it was the only option accessible to me. So, here we are. Luckily, it worked! I recently finished up the last steps, my teapot is repaired, and I can finally start using it again.

This was my first attempt at kintsugi and there are certainly some flaws in the repair itself. My lines are not super straight and thin and elegant. But done is better than perfect, right? I suppose you really have to appreciate the irony of the imperfections in the repair itself.

It was satisfying and rewarding to mend something that was damaged, but in a way that does not try to hide what was broken. The gold finish is like the beautiful scar tissue that patches our deepest wounds, a reminder of where we’ve been what we’re capable of moving through. Sometimes, things are more beautiful after they’ve been broken and put back together.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

SwiftUI's Observable macro is not a drop-in replacement for ObservableObject

2024-09-09T07:32:37-07:00

SwiftUI’s new @Observable macro is not a drop-in replacement for ObservableObject. I learned of a subtle difference in behavior the hard way. Hopefully, I can save you from the same headache I experienced and save you some time.

Background

The new @Observable macro was introduced last year with iOS 17 and macOS 14. It was advertised as (mostly) a drop-in replacement for ObservableObject, but there is a significant behavior difference regarding initialization. You need to use the @StateObject property wrapper with ObservableObject and use the @State property wrapper with @Observable. This is the key difference and the underlying cause for the difference in initialization behavior. In other words, the issue is not really with ObservableObject and @Observable, but with their associated property wrappers.

The @StateObject property wrapper initializer has the definition:

init(wrappedValue thunk: @autoclosure @escaping () -> ObjectType)

The @State property wrapper initializer has the definition:

init(wrappedValue value: Value)

I think the official migration guide should have a loud warning about this, but unfortunately it does not.

This is a significant difference. @StateObject receives an @autoclosure for the wrappedValue parameter while @State simply receives the value. The result is that @StateObject can not only defer initialization of the received value, but it will only ever initialize the value once. When using @State, the initializer for Value will be called every single time SwiftUI destroys and rebuilds the view hierarchy. Depending on how you’ve constructed your views and types, this is either a non-issue or results in incredibly confusing and buggy behavior that is not obvious unless you are aware of this subtle difference.

Example

Let’s look at a brief example of the differences. First, we’ll consider the “old” way of doing things using ObservableObject and @StateObject.

class MyModel: ObservableObject {
    @Published var value = MyValue()
    // ...
}

@main
struct MyApp: App {
    @StateObject private var model = MyModel()

    var body: some Scene {
        WindowGroup {
            MainView()
                .environmentObject(model)
        }
    }
}

Next, let’s convert this example to use @Observable and @State by following the migration guide.

@Observable
class MyModel {
    var value = MyValue()
    // ...
}

@main
struct MyApp: App {
    @State private var model = MyModel()

    var body: some Scene {
        WindowGroup {
            MainView()
                .environment(model)
        }
    }
}

The bug

Unfortunately, switching to @Observable caused a significant and difficult to debug problem in my app. There were three issues with how I had architected my app using ObservableObject.

First, unlike the example code above, I was declaring my @StateObject from within my main root View object — not at the App level.
Next, in the initializer of my ObservableObject, I was loading cached data from UserDefaults and storing these values in my @Published properties.
Finally, my ObservableObject was registered to listen for the NS/UIApplication.willTerminateNotification notification and saved its data back to UserDefaults when quitting the app.

Here’s a simplified version of what the code looked like after migrating to @Observable.

@Observable
class MyModel {
    var value = MyValue()

    // ...

    init() {
        // read cached values from UserDefaults
        value = UserDefaults.standard.object(forKey: "my_value")

        NotificationCenter.default
            .publisher(for: .willTerminateNotification)
            .sink {
                // save values to UserDefaults
                UserDefaults.standard.set(value, forKey: "my_value")
            }
            .store(in: &cancellables)
    }
}

struct MainView: View {
    @State private var model = MyModel()

    var body: some View {
        // ...
    }
}

When using ObservableObject before the migration, the code above behaved as you would expect. My data would load and save correctly. I was using UserDefaults because I only needed to store a few lightweight values and I wanted to keep everything simple. I was using app lifecycle notifications because SwiftUI scene phase does not work.

The result of migrating to @Observable (using the code above) was unpredictable behavior because of the changes in initialization that I described above. Previously, my ObservableObject (remember, using @StateObject) was only ever initialized once, because the initializer for @StateObject receives an @autoclosure. This meant that reading from UserDefaults only occurred once and registering for the notifications only occurred once for the lifetime of the app.

However, with @Observable (and thus, @State), the initializer for MyModel is called every single time SwiftUI decides to rebuild the view. Under-the-hood, when state changes occur, SwiftUI will destroy and rebuild the view. This means your view struct (in this case, MainView) will get re-initialized often. This implicitly re-initializes all @State variables, too. However, SwiftUI preserves the original @State property value and applies that value before initialization completes. The flow looks like this:

Initialize the @State variables (these are new objects)
Call the View initializer
Reset the @State variables back to the previously initialized and stored objects (discarding objects initialized in step 1)
Initialization is complete
Execute the view’s body (using the correct values from step 3)

What I observed is that all those new, initial instances of MyModel (from step 1 above) linger around in memory indefinitely. I verified this via logging and Xcode’s memory graph debugger. Occasionally and non-deterministically, some of those MyModel instances will get deallocated. This seems like a bug in SwiftUI.

Note that the View still displays the correct data because the original object is reset to the @State property (step 3 above).

The reason this became a problem in my particular situation was because my model object was listening for the notification, NS/UIApplication.willTerminateNotification. All those extra instances of MyModel lingering around in memory were still observing this notification. When triggered, each instance would save whatever data it had to UserDefaults, resulting in a non-deterministic “last write wins” scenario. Upon relaunching the app, who knows was random data would load from UserDefaults. Yikes. This was admittedly not the best design, but it worked well for my purposes.

The fix

I suppose the moral of this story is, “I was holding it wrong.” But honestly, if you cannot design your API such that a user is unable to hold it wrong in the first place, then it is not entirely the user’s fault when things go wrong. However, I do think the fact that random @State objects linger around somewhere in memory in the opaque abyss of SwiftUI’s state management mechanism is a real problem.

The correct way to architect your app is to store all (app-level or global) @State properties in your top-level App struct, which does not get repeatedly destroyed and rebuilt like SwiftUI View objects. (And really, your @StateObject properties should also be declared in your App struct too.) There were some technical reason why I did not initially do this, but the details are not important. I was able to rework my design to make it work. If you cannot do that, then you need to ensure whatever object you store in @State does nothing in init() and does not manage any state in response to app lifecycle notifications or something similar. Because scene phase is broken in a number of ways, I recommend using NS/UIApplicationDelegateAdaptor instead. Only scene-level or view-specific state properties should be declared at the view-level.

An aside: when using @State you will also want to ensure that your object’s initializer does not perform any expensive operations either. That will also result in a very bad time for you.

Additional reading

These posts on other initialization quirks of @State and @StateObject are also worth reading.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

UI testing improvements in Xcode 16

2024-07-09T12:45:08-07:00

While the new Swift Testing framework announced this year at WWDC24 is getting a lot of attention, there are some notable improvements coming to UI testing in XCTest in Xcode 16.

Xcode 16 introduces two new APIs in XCTest for UI testing.

The first is waitForNonExistence(withTimeout:), which provides the inverse of the existing waitForExistence(timeout:) API. Finally! This is such a welcome change. Often in UI testing it is more semantic to wait for an element to disappear rather than appear — for example, waiting for a loading indicator or waiting for a UIContentUnavailableView to disappear. Previously, you would have to roll your own implementation or awkwardly use waitForExistence(timeout:) and negate the result — both options are cumbersome and inefficient.

Here’s an example. Suppose your view displays an initial loading state while fetching data, which then disappears once loading completes.

func testLoadingView() throws {
    let app = XCUIApplication()
    app.launch()

    let contentView = app.otherElements["content_view"]
    XCTAssertTrue(contentView.waitForExistence(timeout: 1), "Content view should appear")

    let loadingView = app.staticTexts["loading_view"]
    XCTAssertTrue(loadingView.exists, "Content should be loading initially")

    XCTAssertTrue(loadingView.waitForNonExistence(withTimeout: 2), "Loading should complete")
    XCTAssertFalse(loadingView.exists)
}

Side note: the inconsistency in the naming of the timeout: parameter label for these two functions is a bit odd. The new method uses withTimeout instead of timeout. I would prefer if they were both consistently named timeout.

func waitForExistence(timeout: TimeInterval) -> Bool

func waitForNonExistence(withTimeout timeout: TimeInterval) -> Bool

The second new API is wait(for:toEqual:timeout:), which waits for a property value of an element to equal a new value. This is useful for when the contents of an existing view should be updated and you want to verify the update happened. The most common use case here is likely for checking the contents of labels, text fields, or text views that change based on state updates or user interaction. Previously, there was not a great way to achieve this without introducing artificial timeouts in your test, or changing the UI element’s .accessibilityIdentifier in your app when its contents updated and then checking for the existence of the new identifier.

Continuing with the example above, suppose your loading view does not disappear but instead updates with a new message. Initially, the view displays “Loading…“ and then displays “Loading Complete!” when data is finished loading.

func testLoadingView() throws {
    let app = XCUIApplication()
    app.launch()

    let contentView = app.otherElements["content_view"]
    XCTAssertTrue(contentView.waitForExistence(timeout: 1), "Content view should appear")

    let loadingView = app.staticTexts["loading_view"]
    XCTAssertTrue(loadingView.exists, "Content should be loading initially")
    XCTAssertEqual(loadingView.label, "Loading...", "Label should initially display 'Loading...'")

    XCTAssertTrue(
        loadingView.wait(for: \.label, toEqual: "Loading Complete!", timeout: 3),
        "Label should update when loading is done to say 'Loading Complete!'"
    )
}

Additionally, you could test for failure states as well. In this scenario, perhaps when data fails to load, you could display “Oops, there was an error!” in the label. You could write a similar UI test for this situation.

Unfortunately, in my testing wait(for:toEqual:timeout:) did not work as expected. In fact, the sample test above will fail. In order to get this test to pass, I had to introduce an artificial timeout before calling and checking wait(for:toEqual:timeout:).

_ = loadingView.waitForExistence(timeout: 1)

XCTAssertTrue(
    loadingView.wait(for: \.label, toEqual: "Loading Complete!", timeout: 3),
    "Label should update when loading is done to say 'Loading Complete!'"
)

Hopefully this bug gets fixed before the final release of Xcode 16.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Our App Store screenshot nightmare is (almost) over

2024-07-04T11:55:25-07:00

I previously wrote about how the requirements for screenshots on the App Store have become increasingly burdensome over the years. It is truly a nightmare. But today I have good news to share! Our nightmare is coming to an end, as changes to screenshot requirements were announced at WWDC24 this year.

App Store Connect is getting an update and only one set of screenshots will be required for iPhone and iPad! This news was somewhat buried toward the end of the session, What’s new in App Store Connect. Unfortunately, it was only a brief bullet point with no extra details — but I’ll take it. It’s not clear which devices will be allowed for a single set of screenshots, but it will likely be one of the larger device sizes for both iPhone and iPad from the latest models.

It also is not clear when these changes will take effect in App Store Connect. Currently, the old requirements remain. I suspect that App Store Connect updates will coincide with the final releases of iOS 18 and macOS 15 later this year. So, we’ve got a few months to wait.

What about macOS screenshots? There are problems there, too — specifically the allowed sizes and aspect ratios. Unfortunately, it looks like the existing requirements for macOS screenshots will remain. At least we made progress on iOS.

* * *

There were some other welcome changes announced in What’s new in App Store Connect.

More opportunities to get your app discovered via “Featuring Nominations”
TestFlight is getting an updated invitation experience and criteria for public links that allow you to restrict invites to things like specific devices and operating systems
Deep links to custom product pages
A new “Promote Your App” feature to help you generate marketing assets
Notifications when your app gets featured on the App Store (another “finally!”)

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

SwiftUI app lifecycle: issues with ScenePhase and using AppDelegate adaptors

2024-06-29T14:25:23-07:00

SwiftUI introduced the ScenePhase API in iOS 14 and macOS 11. This was SwiftUI’s answer to handling application lifecycle events. At the same time, SwiftUI introduced UIApplicationDelegateAdaptor for iOS and NSApplicationDelegateAdaptor for macOS, which allow you to provide an AppDelegate on both platforms to receive additional application lifecycle events and other events that were missing from SwiftUI at the time. Unfortunately, many of those application event APIs are still missing and ScenePhase has a number of bugs (or at least, unexpected behavior).

Limitations of `ScenePhase` events (and view lifecycle events)

The issue with ScenePhase is that it is too limited, having only 3 states: active, inactive, and background. In a perfect world, an application should not necessarily need to know whether it is launching for the first time or being terminated. In practice, however, these are extremely relevant and important application events. There are many scenarios in which knowing the distinction between a first (or “cold”) launch and merely returning to the active state is helpful. Similarly, there are good reasons to treat a background state and termination differently.

I think ScenePhase should expand to include both didLaunch and willTerminate events, because attempting to infer these states is cumbersome and error prone, if not impossible. Or even better, what I would really like is a separate AppPhase API that allows you to handle application-level lifecycle events separately from window scenes.

The concept of “scenes” really centers around windows, not the entire application, and that is part of the problem with the API. The scene phases correlate to and model the lifecycle of application windows. It just so happens that on iOS your app only ever has a single window, so the ScenePhase API is a better fit on that platform — and, in fact, it does work better on iOS. (Yes, iPadOS can now have multiple windows, but let’s not get into that mess.) The differences between all the various platforms make working with ScenePhase even more difficult because it feels like SwiftUI is trying to force a uniform model across all platforms, despite key differences in their paradigms.

The ScenePhase documentation states that you should “expect an app that enters the background phase to terminate.” This is unfortunate because it is possible (and probably common) for users to switch between apps and quickly return to your app. If there is no distinction between temporarily being in the background and a complete termination, then your app could end up doing a lot of unnecessary tear down and set up work. As you’ll see below, this is actually terrible advice for a macOS app.

UIKit and AppKit both provide additional granularity on top of these 5 main events, with “will” and “did” APIs. For example, applicationWillResignActive() and applicationDidResignActive(). I can see the motivation for simplifying the SwiftUI APIs, but there are scenarios where SwiftUI is too limiting and it is valuable to know that an event is about to happen versus knowing an event has already happened.

The same limitations exist with SwiftUI’s view lifecycle methods, onAppear() and onDisappear() — which, according to the docs these should be more accurately named willAppear() and didDisappear(). The fact that onAppear() is called before a view appears, but onDisappear() is called after a view disappears is inconsistent and confusing.

Bugs and quirks with `ScenePhase`

Aside from being too limited, there are also a number of bugs with ScenePhase in SwiftUI. Perhaps some of this behavior is intended, but if so, it is certainly unexpected.

Here is a minimal implementation of ScenePhase to demonstrate. Note that this snippet is printing the results of all changes to scenePhase so that you can observe what is happening.

@main
struct MyApp: App {
    @Environment(\.scenePhase) var scenePhase

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .onChange(of: scenePhase, initial: true) { oldValue, newValue in
            print("ScenePhase: \(oldValue) -> \(newValue)")
        }
    }
}

Behavior on iOS

On iOS, onChange(of:) works mostly as expected. Here are some common scenarios and the associated scene phase transitions:

Initial app launch: inactive > active.
Move to background: active > inactive > background.
Return to foreground: background > inactive > active.
Temporary background (like toggling Control Center): toggles between active and inactive.
App termination: if currently active, then inactive > background. Notably, if the app is already in the background and you force quit it, then no scene phase transitions occur. This means you must treat all background events as if the app is being terminated. As mentioned above, this is not optimal in all scenarios.

One quirk in behavior depends on whether you opt to receive the initial value, or not by passing true or false to the initial: parameter. If you pass true, then the first onChange(of:) event for ScenePhase is from inactive to inactive, then you receive the update to transition to active.

Unexpectedly, the main view receives onAppear() before your app receives the scene phase change. In the sample above, that would be ContentView. That’s like receiving viewWillAppear() on your root view controller before application(_:didFinishLaunchingWithOptions:) gets called. That sequence of events does not make sense to me and raises concerns about how you should accurately architect your app startup flow in SwiftUI.

The sparse ScenePhase transitions above stand in stark contrast to the rich and granular events provided by UIApplicationDelegate.

Behavior on macOS

On macOS, the behavior of onChange(of:) is very different and very unexpected. Here are a similar set of scenarios as above and the associated scene phase transitions:

Initial app launch: active > active. (what? lol)
Move to background (making a different application front most and active): no events.
- Return to foreground: no events.
Move to background (by hiding the application, cmd-H): active > background.
- Return to foreground: background > active.
Closing the main window (but keep application running): no scene phase events. But you do receive onDisappear() for the main view.
App termination (via cmd-Q): no events.

As mentioned above, the ScenePhase documentation states that you should “expect an app that enters the background phase to terminate.” That is a terrible assumption for a Mac app, based on the transitions listed above. Hiding the application (cmd-H) is the only way I have found to trigger a background scene phase on macOS. Preparing for termination when the user simply hides your app does not make sense. What a terrible user experience that would be!

If you pass false to the initial: parameter on macOS, you receive no initial scene phase change.

In my testing, I have never been able to get a macOS app to transition to the inactive scene phase. It is not clear if this is by design, or if this is a bug. It seems like a bug.

Unlike on iOS, macOS receives onAppear() for the main view in the correct order. That is, the scene phase becomes active and then the app receives onAppear() for the main view. But unexpectedly, when hiding the application on macOS, you do not receive the onDisappear() event. You only receive onDisappear() when closing a window, and notably, no scene phase events occur.

If it isn’t obvious, it is actually impossible to rely solely on ScenePhase in a macOS application where you need access to application lifecycle events, or even reliable app window lifecycle events. On macOS ScenePhase events are outright insufficient and stand in even starker contrast to the rich and granular events provided by NSApplicationDelegate and, of course, NSWindowDelegate.

App delegate adaptors are discouraged

Despite all of the shortcomings and unreliable behavior in the APIs I have listed above, the documentation for both UIApplicationDelegateAdaptor on iOS and NSApplicationDelegateAdaptor on macOS, both discourage their use with a big scary warning:

Important

Manage an app’s life cycle events without using an app delegate whenever possible. For example, prefer to handle changes in ScenePhase instead of relying on delegate callbacks […]

This is interesting, especially on macOS, where ScenePhase literally just does not work and cannot replace delegate callbacks at all. In my experience, on both platforms but mostly on macOS, you must use an app delegate if you need reliable and granular app lifecycle events.

Using app delegate adaptors (and their issues)

If you instead want to respond to application lifecycle events outside of SwiftUI, you can provide an app delegate. First, you need to create the properties in your SwiftUI app.

#if canImport(AppKit)
@NSApplicationDelegateAdaptor var appDelegate: NSAppDelegate
#endif

#if canImport(UIKit)
@UIApplicationDelegateAdaptor var appDelegate: UIAppDelegate
#endif

Then you can implement an AppDelegate for iOS:

import UIKit

final class UIAppDelegate: NSObject, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        print(#function)
        return true
    }

    func applicationDidBecomeActive(_ application: UIApplication) {
        print(#function)
    }

    func applicationWillResignActive(_ application: UIApplication) {
        print(#function)
    }

    func applicationDidEnterBackground(_ application: UIApplication) {
        print(#function)
    }

    func applicationWillEnterForeground(_ application: UIApplication) {
        print(#function)
    }

    func applicationWillTerminate(_ application: UIApplication) {
        print(#function)
    }
}

And you can implement an AppDelegate for macOS:

import AppKit

final class NSAppDelegate: NSObject, NSApplicationDelegate {

    func applicationWillFinishLaunching(_ notification: Notification) {
        print(#function)
    }

    func applicationDidFinishLaunching(_ notification: Notification) {
        print(#function)
    }

    func applicationWillHide(_ notification: Notification) {
        print(#function)
    }

    func applicationDidHide(_ notification: Notification) {
        print(#function)
    }

    func applicationDidBecomeActive(_ notification: Notification) {
        print(#function)
    }

    func applicationWillResignActive(_ notification: Notification) {
        print(#function)
    }

    func applicationDidResignActive(_ notification: Notification) {
        print(#function)
    }

    func applicationWillTerminate(_ notification: Notification) {
        print(#function)
    }
}

Pro tip: because app delegates are defined as protocols, you could instead create a single class that conforms to both protocols. This can be a good strategy for sharing code between platforms.

On macOS, you receive all the NSApplicationDelegate callbacks as expected. Everything works. Contrary to the documentation, I would avoid attempting to use ScenePhase at all on macOS.

On iOS, app delegate adapters are a different story. They don’t work as I would expect. Of all the callbacks defined in the UIApplicationDelegate above, only application(_:didFinishLaunchingWithOptions:) and applicationWillTerminate(_:) are called in a SwiftUI app. This behavior occurs even if you have opted out of multiple window support on iOS by providing the correct plist values for UIApplicationSceneManifest.

If you want more granular scene events on iOS, you must provide a SceneDelegate class that conforms to UIWindowSceneDelegate. You can still turn off multiple windows, but you must provide a scene configuration and UISceneDelegateClassName in your plist. Only then will you receive the corresponding callbacks.

Here’s an example plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>UIApplicationSceneManifest</key>
    <dict>
        <key>UIApplicationSupportsMultipleScenes</key>
        <false/>
        <key>UISceneConfigurations</key>
        <dict>
            <key>UIWindowSceneSessionRoleApplication</key>
            <array>
                <dict>
                    <key>UISceneConfigurationName</key>
                    <string>Default Configuration</string>
                    <key>UISceneDelegateClassName</key>
                    <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
                </dict>
            </array>
        </dict>
    </dict>
</dict>
</plist>

And an updated app delegate, along with a default scene delegate:

final class UIAppDelegate: NSObject, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        print(#function)
        return true
    }

    func applicationWillTerminate(_ application: UIApplication) {
        print(#function)
    }

    // MARK: UISceneSession Lifecycle

    func application(_ application: UIApplication,
                     configurationForConnecting connectingSceneSession: UISceneSession,
                     options: UIScene.ConnectionOptions) -> UISceneConfiguration {
        print(#function)
        return UISceneConfiguration(name: "Default Configuration", sessionRole: connectingSceneSession.role)
    }

    func application(_ application: UIApplication, didDiscardSceneSessions sceneSessions: Set<UISceneSession>) {
        print(#function)
    }
}

final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene,
               willConnectTo session: UISceneSession,
               options connectionOptions: UIScene.ConnectionOptions) {
        print(#function)
        guard let _ = (scene as? UIWindowScene) else { return }
    }

    func sceneDidDisconnect(_ scene: UIScene) {
        print(#function)
    }

    func sceneDidBecomeActive(_ scene: UIScene) {
        print(#function)
    }

    func sceneWillResignActive(_ scene: UIScene) {
        print(#function)
    }

    func sceneWillEnterForeground(_ scene: UIScene) {
        print(#function)
    }

    func sceneDidEnterBackground(_ scene: UIScene) {
        print(#function)
    }
}

Note that for SwiftUI, all you need to do is declare the same @UIApplicationDelegateAdaptor above for this all to work. The scene delegate is determined from your app plist and everything seems to “just work” in terms of setting up the delegates.

Conclusion

In the code above, I have used print(#function) to print all the events to the console as they happen. This was very instructive for discerning how all of these APIs work together — or, sometimes, don’t. I encourage you to put it all together in a sample app if you are curious to experiment with and visualize the sequence of callbacks as they happen.

On one hand, the ScenePhase APIs can get you somewhat far on iOS. But if you need more granular control, you need to define an app delegate, a scene delegate, and provide the corresponding scene manifest in your app’s plist. If you are going through all that trouble, you might as well structure your app to have a UIKit shell instead of trying to rely entirely on SwiftUI. On the other hand, the ScenePhase APIs are essentially useless on macOS and you must use an app delegate — although this is much easier to set up. For complex Mac apps, an AppKit shell is probably the best approach.

There are probably some simple utility apps on both platforms that will never need to worry about all the issues I have described here, but for serious applications, you will run into these issues. Furthermore, there are even more roles and responsibilities that app delegates have that I have not discussed here — if you need any of that functionality for your app, then you really must have an app delegate no matter what.

After all these years, it is disappointing that SwiftUI still does not offer these necessary and fundamental APIs for building applications on both platforms. SwiftUI needs more robust and reliable APIs for managing the app lifecycle, window lifecycles, and view lifecycles.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Swift concurrency hack for passing non-sendable closures: Uncheck yourself before you wreck yourself

2024-06-05T10:30:35-07:00

If you have attempted to adopt Swift Concurrency in your codebase, you have certainly needed to address dozens — likely, hundreds — of warnings and errors. Sometimes the issues can be resolved by addressing them directly. That is, your code was incorrect and you simply have to fix it to make it correct. In other scenarios, the resolution is not so straightforward. In particular, it is difficult to satisfy the compiler when working with APIs that you do not own that have not been updated for concurrency. Or, you may have found yourself in a situation where you know your code is correct, but the compiler is unable to verify its correctness — either because of a few remaining bugs in Swift Concurrency, or because you are using @preconcurrency APIs.

One of the warnings you have probably seen multiple times is “Capture of ‘variable’ with non-sendable type in a @Sendable closure.” I was confronted with this warning in a project recently and I want to share the hack for how I worked around it. The issue was the result of a combination of factors I mentioned above. I was interacting with @preconcurrency APIs and I knew my code was concurrency-safe, but I was unable to accurately express that to the compiler.

Background

First, let’s discuss the context in which I was dealing with this concurrency warning. I have been working on a project that uses UICollectionViewDiffableDataSource and I am wrapping the UIKit APIs with something more user-friendly. For the purposes of this post, I have omitted much of the complexity to provide a clear, simple example.

I have a custom diffable data source that performs the diffing on a background thread:

@MainActor
final class DiffableDataSource: UICollectionViewDiffableDataSource<String, String> {
    typealias Snapshot = NSDiffableDataSourceSnapshot<String, String>

    typealias SnapshotCompletion = @MainActor () -> Void

    let diffingQueue = DispatchQueue(label: "diffingQueue")

    func applyDiff(snapshot: Snapshot, animated: Bool = true, completion: SnapshotCompletion? = nil) {
        self.diffingQueue.async {
            self.apply(snapshot, animatingDifferences: animated, completion: completion)
        }
    }
}

Per the documentation, the completion closure is always called on the main queue and you can call apply(_:animatingDifferences:completion:) from a background queue:

[…]

completion
A closure to execute when the animations are complete. This closure has no return value and takes no parameters. The system calls this closure from the main queue.

[…]

You can safely call this method from a background queue, but you must do so consistently in your app. Always call this method exclusively from the main queue or from a background queue.

Also note that UICollectionViewDiffableDataSource is annotated with @MainActor @preconcurrency.

With the strictest concurrency checking enabled, the code above produces 2 warnings:

func applyDiff(snapshot: Snapshot, animated: Bool = true, completion: SnapshotCompletion? = nil) {
    self.diffingQueue.async {
        self.apply(snapshot, animatingDifferences: animated, completion: completion)
        //                                                               ^
        // Capture of 'completion' with non-sendable type 'DiffableDataSource.SnapshotCompletion?' (aka 'Optional<@MainActor () -> ()>') in a `@Sendable` closure
        // Converting function value of type '@MainActor () -> Void' to '() -> Void' loses global actor 'MainActor'; this is an error in Swift 6
    }
}

One solution would be to make the completion closure @Sendable:

func applyDiff(snapshot: Snapshot, animated: Bool = true, completion: @escaping @Sendable () -> Void) {
    self.diffingQueue.async {
        self.apply(snapshot, animatingDifferences: animated, completion: completion)
    }
}

(Note that we cannot use the defined typealias SnapshotCompletion in this case, and it must not be optional.)

However, this will not work. This API updates the collection view to reflect the state of the data in the snapshot and, as mentioned, completion is called on the main thread. Callers of applyDiff(snapshot:) do additional UI updates and animations, or otherwise deal with @MainActor members and types in this completion closure. Those members and types cannot be marked as @Sendable. For example, the owner of the DiffableDataSource instance could be a view controller. Furthermore, I do not want to impose a @Sendable restriction upon callers.

Thus, making the closure @Sendable produces the following kinds of errors at the call site:

self.dataSource.applyDiff(snapshot: snapshot) {

    // Call to main actor-isolated instance method 'someMethod()' in a synchronous nonisolated context

    // Main actor-isolated property 'someProperty' can not be referenced from a Sendable closure; this is an error in Swift 6
}

Callers could wrap the offending lines in Task { @MainActor in } or MainActor.assumeIsolated { } to silence these issues. But, that’s a burden for callers. Not to mention, the wrapper API does not accurately communicate what is happening here. We do not want a @Sendable () -> Void closure. We want a @MainActor () -> Void closure.

So, we have situation where the Swift compiler is telling us that the closure being captured needs to be @Sendable but we cannot make it @Sendable. It is also telling us that the closure loses its @MainActor but we know that the closure will always be called from the main queue. Because of these two problems, we need to find a way to work around the warnings and coerce the compiler into doing what we want.

Solution (It’s a hack)

We can wrap the completion closure in another type that is @unchecked Sendable.

struct UncheckedCompletion: @unchecked Sendable {
    typealias Block = () -> Void

    let block: Block?

    init(_ block: Block?) {
        if let block {
            self.block = {
                dispatchPrecondition(condition: .onQueue(.main))
                block()
            }
        } else {
            self.block = nil
        }
    }
}

This will silence the warning about “capturing a non-sendable type in a @Sendable closure.” Again, UIKit guarantees that this completion closure will always be called on the main thread, and we can use a dispatchPrecondition() to verify this is happening.

We can update our API to use this new UncheckedCompletion wrapper.

func applyDiff(snapshot: Snapshot, animated: Bool = true, completion: UncheckedCompletion) {
    self.diffingQueue.async {
        self.apply(snapshot, animatingDifferences: animated, completion: completion.block)
    }
}

However, exposing UncheckedCompletion to callers is also not a great API. We should hide this detail. We can wrap this applyDiff() method with another that uses the original SnapshotCompletion typealias.

func applyDiff(_ snapshot: Snapshot, animated: Bool = true, completion: SnapshotCompletion? = nil) {
    self.applyDiff(snapshot: snapshot, animated: animated, completion: UncheckedCompletion(completion))
    //                                                                 ^ wrapped in UncheckedCompletion
}

private func applyDiff(snapshot: Snapshot, animated: Bool, completion: UncheckedCompletion) {
    self.diffingQueue.async {
        self.apply(snapshot, animatingDifferences: animated, completion: completion.block)
        //                                                               ^ access underlying closure
    }
}

And now, the public API looks exactly the same as before to callers, but they can safely use @MainActor members and types in the completion closure without any warnings or errors.

self.dataSource.applyDiff(snapshot: snapshot) {
    // do anything here safely with @MainActor with no warnings or errors
}

Is this good?

Is this a good idea? I am actually not sure! But, it seems like the best thing to do in this scenario. If you are facing a similar situation — namely, you know a captured closure is always called on the main thread and you cannot make it @Sendable — this might be a good solution for you too! However, this is probably a bad idea to attempt to generalize. Use wisely!

Update 05 June 2024

As anticipated, Matt Massicotte has come to the rescue, offering a simpler solution here. While my clever hack works, we can instead make the closure both @Sendable and @MainActor. After that, we can simply wrap calling the completion closure in MainActor.assumeIsolated { }. Here are the changes needed:

// The addition of @Sendable is bizarre, but Swift 5.10 needs it.
// Swift 6 (via SE-0434) will make it unnecessary.
typealias SnapshotCompletion = @Sendable @MainActor () -> Void

func applyDiff(snapshot: Snapshot, animated: Bool = true, completion: SnapshotCompletion? = nil) {
    self.diffingQueue.async {
        // UIKit guarantees `completion` is called on the main queue.
        self.apply(snapshot, animatingDifferences: animated, completion: {
            // when you know its on the main actor, perhaps from documentation, but it isn't
            // encoded in the API, you can use dynamic isolation to make it work
            MainActor.assumeIsolated {
                completion?()
            }
        })
    }
}

This is great. It is much less code. I’m not sure why I didn’t try using @Sendable @MainActor for the closure. It’s probably because I assumed that @MainActor implied @Sendable — which apparently it should and it will after SE-0434 in Swift 6.

Anyway, the general idea of this hack might still be useful in other contexts or scenarios — especially if you cannot adopt Swift 6 and need to stay on Swift 5.10.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Workaround: Xcode deletes Package.resolved file and produces 'missing package product' errors

2024-05-29T19:06:41-07:00

More and more Apple Platform developers are migrating away from CocoaPods in favor the Swift Package Manager, which is Apple’s first-party tool for managing and integrating dependencies. While it is still not quite a complete replacement for CocoaPods, it is getting closer. Unfortunately, SwiftPM’s integration with Xcode still has a number of shortcomings, even though it was introduced with Xcode 11 — 4 years ago. The worst bug is that Xcode frequently and randomly deletes the Package.resolved, which in turn produces dozens or hundreds of 'missing package product' errors. Here’s how I’ve worked around this bug on a team I work on.

The bug

Xcode seems to specifically delete Package.resolved when changing branches in git. Then, depending on how large your project is and how many Swift packages are included, you’ll see dozens or hundreds or thousands of 'Missing package product <product_name>' errors.

However, I have also experienced Xcode deleting the file for seemingly no reason at all. In fact, I’ve had moments where Xcode deletes the file immediately after I restore it via git restore — and I can just do that infinitely. I put the file back, then Xcode deletes it. In that beautiful scenario, the Xcode project must be closed and re-opened.

Searching the Apple Developer Forums returns dozens of results for this bug. Here is a recent one that correctly describes the problem. Here is another post from 2021 that has new replies from 2 weeks ago. There is also this post from the Swift.org forums — from June 2020 — describing the issue. If you read through that thread, you will see the problem was briefly fixed around Xcode 12, but regressed in either the 12.5 or 13.0 release. This forum thread also has new comments from the past 2 weeks (including from yours truly). Unfortunately, the Swift forums are not the right place to report bugs in Xcode.

Most “solutions” on the forums revolve around some magical combination of cleaning your project (cmd-shift-K), deleting Xcode’s DerivedData/, running File > Packages > Reset Package Caches, running File > Packages > Resolve Package Versions, and closing and re-opening Xcode. All of this is very heavy-handed and there’s a much lighter weight approach you can take to work around it.

This bug is happening in the latest release, Xcode 15.4 (15F31d). It is a widespread problem reported across the various forums, as well as on Mastodon and other platforms. Any developer on a team that is using SwiftPM with Xcode is experiencing this bug daily. Furthermore, running xcodebuild -resolvePackageDependencies seems to have no effect and it does not regenerate Package.resolved.

The `Package.resolved` file and git

First, what is Package.resolved and why is it important? This file is equivalent to Podfile.lock in CocoaPods — similar to Gemfile.lock in Ruby/Bundler, or package-lock.json in Node.js/npm. This file is a manifest that describes the exact versions used for every package dependency. It allows SwiftPM to always install the exact same packages on multiple machines, for example the machines of each member on a team and CI machines.

It turns out, it’s just a JSON file. Here’s an example of Package.resolved for an app that imports one library called Foil.

{
  "pins" : [
    {
      "identity" : "foil",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/jessesquires/Foil",
      "state" : {
        "revision" : "bc08a46268cb3bb22fee2c8465d97e6d7bf981e1",
        "version" : "5.0.1"
      }
    }
  ],
  "version" : 2
}

Because Package.resolved is necessary to resolve the exact packages at their exact specified versions, it should be checked-in to source control.

If you are working with an Xcode project, Package.resolved is located at:

MyApp.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved

If you are working with an Xcode workspace, the file is located at:

MyApp.xcworkspace/xcshareddata/swiftpm/Package.resolved

When working with only Swift packages, your Package.swift file defines all of your package dependencies. This plays a similar role to the Podfile in CocoaPods. With SwiftPM’s Xcode integration, the project file project.pbxproj — everyone’s favorite file — maintains the list of Swift package dependencies and their pinned versions. Again, this fulfills the same role as the Podfile.

The project file is located at MyApp.xcodeproj/project.pbxproj. If you search the project.pbxproj file for XCRemoteSwiftPackageReference and XCSwiftPackageProductDependency, you will find all the Swift package references for your project. For the example Package.resolved file above, here is the project.pbxproj representation:

/* Begin XCRemoteSwiftPackageReference section */
0B3E8A0A28AD7D9C006FB785 /* XCRemoteSwiftPackageReference "Foil" */ = {
    isa = XCRemoteSwiftPackageReference;
    repositoryURL = "https://github.com/jessesquires/Foil";
    requirement = {
        kind = upToNextMajorVersion;
        minimumVersion = 5.0.0;
    };
};
/* End XCRemoteSwiftPackageReference section */

For small teams or individuals that already include their entire .xcodeproj or .xcworkspace bundles in git, there is nothing else you need to do. However, most teams explicitly ignore .xcodeproj and .xcworkspace — ironically, because of project.pbxproj, which is a nightmare to resolve when you have conflicts in git. These teams typically use Xcodegen or a similar tool to generate their project files, thus entirely avoiding merge conflicts on project.pbxproj. In this scenario, including the Package.resolved file but ignoring everything else requires a bit of work. Here are the git ignore rules needed:

# .gitignore file

MyApp.xcworkspace/*
!MyApp.xcworkspace/xcshareddata/
MyApp.xcworkspace/xcshareddata/*
!MyApp.xcworkspace/xcshareddata/swiftpm/
MyApp.xcworkspace/xcshareddata/swiftpm/*
!MyApp.xcworkspace/xcshareddata/swiftpm/Package.resolved

Note that with tools like Xcodegen, you define your packages in your project.yml file, which essentially is a replacement for project.pbxproj.

Update 30 May 2024

Thanks to Kyle Bashour for pointing out a couple of details I got wrong about project.pbxproj. This section has been corrected.

Handling `Package.resolved` deletions

Now that the Package.resolved file is saved in git, we can easily handle when Xcode deletes it by simply restoring it via git. For teams that ignore their project and workspace files and use Xcodegen (or similar), you also have the issue where Xcodegen deletes Package.resolved when it regenerates your project file. If you are also still using CocoaPods in conjunction with SwiftPM, then you have the issue where CocoaPods will delete Package.resolved when it regenerates your workspace file.

When you notice the file gets deleted, you can restore it using git restore. And then all the 'Missing package product' errors will go away when you build your project.

It is common for iOS and macOS projects to use a Makefile in order to bootstrap project setup, which often includes: generating the project file via Xcodegen, installing CocoaPods via Bundler, running pod install, etc. In addition, makefiles are also a great place to write “shortcut” commands that are relevant to your project, for example, linting files or running tests.

Here’s a target you can add to your Makefile to make restoring a deleted Package.resolved file easier.

PACKAGE_FILE := "MyApp.xcworkspace/xcshareddata/swiftpm/Package.resolved"

.PHONY: swiftpm
swiftpm:
    @# Restore Package.resolved, which gets deleted when re-generating the project/workspace.
    @# Or, it gets deleted by Xcode.
    @# Only do this if the file was completely deleted.
    @# Otherwise, the user could be modifying packages which updates Package.resolved, so do not git restore it.
    @if [ ! -f "$(PACKAGE_FILE)" ]; then \
        echo "Restoring Package.resolved..."; \
        git restore "$(PACKAGE_FILE)"; \
        xcodebuild -resolvePackageDependencies; \
    fi

With this target in your Makefile, you can simply run make swiftpm as needed.

Note that this only calls git restore if the file is deleted, in case it has been (correctly) modified after updating packages. At the end, it calls xcodebuild -resolvePackageDependencies, which should regenerate the Package.resolved on its own, but that’s also broken. It will, however, download packages to the package cache if they are missing, which is what Xcode does when opening a project.

To make this even better, you can include running this target as part of your bootstrapping process if you are using CocoaPods, Xcodegen, etc. Include this target part of your primary setup flow, and you should rarely have to run it manually.

If you do not use a Makefile, then you can write a simple bash script instead with the contents above.

Danger: accidental deletions

Unfortunately (again), what we discovered on one of my teams is that the above is not foolproof. Because Xcode can (and literally does) randomly delete Package.resolved at any time, someone on your team might not notice and commit the file deletion. Oops! If you use a tool like Danger to automate code reviews (which, you should), then you can add a rule to catch this mistake.

# Dangerfile

if git.deleted_files.include?("MyApp.xcworkspace/xcshareddata/swiftpm/Package.resolved")
    fail("It looks like you deleted `Package.resolved`. Please don't do that.")
end

This will fail a pull request if Package.resolved was deleted.

Summary

To recap: make sure Package.resolved is saved in git, use a Makefile to quickly and easily restore it, and add a Danger rule to catch mistakes, if needed. This should eliminate all 'Missing package product' errors. As a last resort, if you are still having trouble, you can run File > Packages > Resolve Package Versions. If you search for solutions on StackOverflow or elsewhere, you will find some really elaborate bash scripts that use fswatch to monitor the file system to workaround this problem. I think this is a bit overkill and prefer the simpler solutions I’ve offered here.

This is all a bit ridiculous, and I would say it’s shocking that this bug still hasn’t been fixed after 4 years, but this kind of thing is not all that surprising for Apple. It is rather routine that many bugs remain unfixed and tools remain broken for years.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

The curious case of Apple's third-party SDK list for privacy manifests

2024-04-29T13:37:26-07:00

At last year’s WWDC, Apple introduced privacy manifests. They recently sent out a reminder that the deadline for complying with these new requirements is May 1. Privacy manifests expand on the previously introduced privacy “nutrition labels” that are self-reported by developers and displayed on the App Store. Developers must start including a privacy manifest in their apps by the aforementioned deadline, but what’s more interesting is that Apple is, for the first time, imposing these new privacy rules on third-party SDKs as well. Even more interesting is the list of SDKs that Apple has published, which, upon inspection is quite bizarre.

Historically, Apple has rarely, if ever, explicitly acknowledged any third-party SDK or library. It took years for them to even acknowledge community tools like CocoaPods in Xcode’s release notes (usually when they made a change that broke it). Thus, it is interesting to see which SDKs they have deemed important or concerning enough to explicitly mandate a privacy manifest. And, in typical Apple fashion, I’m pretty sure SDKs authors were not notified about this in advance. We all learned which SDKs need privacy manifests at the same time — when the list was published.

The first few entries in the list make sense:

Abseil, a low-level C++ library.
AppAuth, an SDK for communicating with OAuth 2.0 and OpenID Connect providers.
AFNetworking and it’s successor Alamofire, networking libraries that wrap Apple’s APIs, which almost every iOS developer has encountered.
BoringSSL, a fork of OpenSSL maintained by Google.

I can see how these libraries could be concerning with regard to user privacy, they are all dealing with networking, authentication, and security (except for Abseil) — these are common vectors for privacy-related issues. Abseil is the exception, but I could see an argument for why a low-level C++ library might be a concern. There are also a lot of SDKs from Google and Facebook on the list — neither of those companies have a particularly good reputation when it comes to user privacy. It makes sense for those to be included.

But then… you see that the list contains UI libraries that haven’t seen significant updates or any activity for multiple years, like SVProgressHUD. Why does a library that provides a single UI component need a privacy manifest? Is it as concerning and as potentially privacy invasive as the Facebook SDK? Some of the UI-only SDKs on the list haven’t seen significant updates (or any updates at all) within the last 4-5 years. Furthermore, even AFNetworking hasn’t had an update in 4 years because it was deprecated long ago after being supplanted by Alamofire. The AFNetworking repo on GitHub has been archived and read-only for over a year! Who’s going to bother adding a privacy manifest to that?

And then… there are some entries that are simply obscure and absurd: connectivity_plus, image_picker_ios, video_player_avfoundation, file_picker. What the hell are those?! They don’t even sound like SDK or library names. I have never heard of any of these, and I’ve been involved in the iOS open source community for a decade.

And then… you know what’s even more bizarre about this list? There are no links! There are no links to the SDK project homepages or GitHub repos. It is a plain text list of names, and in some cases, seemingly random names like “file_picker”. Ok LOL. SDK and library names are not necessarily unique. How are you supposed to know exactly which SDKs they are referencing with so little information? Searching for “file_picker” or “image_picker_ios” or any of the other obscure names on both CocoaPods and the Swift Package Index returns no results!

Finally, wouldn’t you expect some sort of reason or justification for each of these SDKs being on the list? We don’t need a 10-page essay but a brief explanation of a few sentences explaining why each of these SDKs is on the list would be helpful in understanding the logic and reasoning behind it.

Nothing about this list makes any sense.

Update 30 April 2024

As many readers have pointed out, there are also a number of popular SDKs that really should be on this list if Apple is concerned about privacy. For example, the TikTok SDK, GoogleAds, and the Unity Ads SDK are all missing from the list, just to name a few. How strange!

And apparently, all of the obscure SDK names like “file_picker” are actually Flutter packages. Again, what an odd list!

* * *

For a company that has positioned itself as a staunch privacy advocate, this list of SDKs is slapdash at best. The lack of attention to detail, like simply including links to SDK homepages, makes the list appear like it was assembled hastily and carelessly. It makes you wonder, how was this list compiled? What was the criteria for including or excluding an SDK from this list?

I was venting about the list on Mastodon, and the general consensus is that it was most likely just a script dump from a static analysis of app binaries on the app store, with the sole criterion being “what are the most popular libraries” used across all apps, with some minimum threshold for inclusion. It is quite clear from the list that no one at Apple really put much thought into it. 🤡

If we operate under the hypothesis that this list is merely the output of a script that someone at Apple wrote to check off the line item “determine which third-party SDKs should be required to included privacy manifests”, then it all starts to make more sense. This list is ultimately the result of a popularity contest, not a thoughtful analysis of SDKs that have meaningful implications for user privacy. They couldn’t even bother to link to the projects or provide brief explanations. There’s literally an entry titled “file_picker” with no other explanation. Did anyone at Apple even look into any of these libraries? Did anyone at Apple even read through this list after some script vomited it out?

When Apple imposes new privacy regulations in such a slipshod manner, how are we, as developers and as users, supposed to take this seriously? This feels like more bureaucratic security and privacy theater. Let’s all take off our shoes and throw away sealed bottles of water we purchased at the airport before we proceed through the TSA security checkpoint — meanwhile doors and wheels are falling off the damn plane.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Workaround: Swift scripts importing Cocoa frameworks broken on macOS 14

2024-01-22T14:31:32-08:00

On macOS 14 Sonoma there is a regression in Swift 5.9 which causes Swift scripts that import Cocoa frameworks to fail. This issue was first reported by @rdj. I discovered it myself shortly after. There is a ticket open at #68785 on the main Swift repo on GitHub to track the issue.

Considering the following Swift script:

#!/usr/bin/swift

import AppKit
import Foundation

NSPasteboard.general.clearContents()
NSPasteboard.general.setString("Hello, Swift!", forType: .string)

print("Hello, Swift!")

You can run directly from the command line:

$ ./hello.swift
Hello, Swift!

On macOS 13 and earlier, this works. Unfortunately, on macOS 14 it now fails with an error: “JIT session error: Symbols not found”.

JIT session error: Symbols not found: [ _OBJC_CLASS_$_NSPasteboard, _NSPasteboardTypeString ]
Failed to materialize symbols:

[...]

The current workaround (also posted by @rdj) is to update the shebang, #!/usr/bin/swift, by replacing it with the following:

#!/usr/bin/env DYLD_FRAMEWORK_PATH=/System/Library/Frameworks /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swift

Note: you must also have Xcode installed for this to work.

I’ve verified that this does indeed fix the problem!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

A simple fastlane setup for solo indie developers

2024-01-22T10:57:55-08:00

I recently setup fastlane for one of my indie apps, Taxatio, to automate uploading builds and metadata to the App Store — by far, one of the most tedious tasks of app development. While I had used fastlane extensively before when working on teams at companies, I had never actually set it up from scratch. In this post, I want to share how to do that, as well as a lightweight configuration that I think works well for solo indie developers — folks on a team of one!

Philosophy

My general philosophy when it comes to software development is do the simplest thing first. (Thanks to Mike Krieger for that one.) The first step is to get something that works that is not complicated and not over-engineered. You can always make it complicated, incomprehensible, and over-engineer it later — so why start now? 😉

In this particular situation with fastlane, this meant that I avoided setting it up for the initial 1.0 release. I knew I would likely run into issues with setup and configuration (I did) and I did not want to waste a bunch of time figuring out (somewhat unfamiliar) tooling when I could instead spend that time simply logging on to App Store Connect to manually input my metadata and upload screenshots.

After the initial release, I set out to get fastlane configured so that I would never have to do that manually again. And that’s great, because App Store Connect is not a very good website.

No CI/CD service

Because I’m a team of one, I do not use any CI/CD service. If a team (of at least a few people) told me they did not use a CI/CD service, I would scream and implement one on my first day. The benefits of using a CI/CD service with a team are clear. But there are good reasons not to do this as a solo indie dev.

Initially, I was torn about this decision. After working on teams for years with robust CI/CD automation, I am convinced it is the right way™ to do things. However, it simply does not make sense for a solo indie developer.

CI/CD services may not be that expensive in terms of absolute value, depending on what you consider expensive. GitHub Actions and Bitrise both have free tiers, but they are pretty limited. You will likely out-grow these, especially if you are working on multiple projects. In the next tier, Bitrise charges $90/month, while GitHub charges $4/month for the first year (after which it is unclear what they charge). My experience with Bitrise in the past was great. They tend deploy timely updates for macOS and Xcode releases. GitHub on the other hand is an exercise in frustration — their current default runners are using macOS 12, machines with macOS 13 are still in beta, and there is no mention of macOS 14, the latest release since last fall.

In order to determine if the cost of these services is worth it, you have to ask yourself what value do they provide? They will run your tests every time you push new commits or open a pull request, build your app, and upload your app to App Store Connect (either via their own infrastructure, or by running fastlane). But… couldn’t I just do all of that myself? Running my unit tests locally is not a problem — my projects are not massive like at big companies, so my test suites finish in a few minutes or less. Invoking fastlane locally is also fast and easy. I don’t need some random machines on the internet to do this for me, especially not for $1,000 per year (with Bitrise).

More importantly, CI/CD services are a maintenance burden — a trade-off that does not make sense for a team of one. Even though I had a good experiences with Bitrise working on teams, it still broke occasionally. Updating a configuration would inadvertently break something, or communicating with App Store Connect would break (not Bitrise’s fault), or codesigning and provisioning profiles would break, or our tests would be reported as passing even though a minor configuration change actually prevented them from running at all. On GitHub actions, you’re dealing with constantly being multiple versions behind.

So, is a CI/CD service worth the financial cost as well as the maintenance cost? For me, the answer is a clear no. The cost-benefit ratio simply does not add up. I do not want to spend time maintaining a service that only I use, when I could be using that time to work on features and fix bugs. No longer do I have to suffer through “it works on my machine, but not on CI” scenarios.

Rather than complete automation, which is what CI/CD services offer, I have opted for human-initiated automation. I run my tests locally during development. When ready to submit to the App Store, I simply run fastlane. I find this to be the best way to maximize the benefits of automation, while minimizing maintenance costs and financial costs.

Initial setup for fastlane

While fastlane does seem to be actively maintained, my impression is that much of it feels like it is languishing in maintenance mode. The documentation feels quite dated, sometimes referencing Xcode 7 or 8. I also ran into a handful of tiny bugs and had to experiment with various parameters. But it does still work, so that’s great!

For initial setup, you can follow the docs and follow the prompts.

fastlane init

You’ll be prompted to authenticate to App Store Connect. For now, you can just authenticate with your Apple ID when prompted. You can switch to using an API Key after initial setup.

If you already have App Store Connect configured with your app metadata and screenshots, fastlane can download this for you. The initial setup will prompt to do this for you, but I ran into issues. I would suggest doing this manually, especially if your app runs on multiple platforms.

# download metadata for each platform
fastlane deliver download_metadata --platform osx --use_live_version true
fastlane deliver download_metadata --platform ios --use_live_version true

# download screenshots for each platform
fastlane deliver download_screenshots --platform osx --use_live_version true
fastlane deliver download_screenshots --platform ios --use_live_version true

You’ll only need to do this once to bootstrap your initial setup. Per the recommendations in the docs, I would git ignore the fastlane/screenshots/ directory. These image files will be large, and they can easily be regenerated at any time.

Notes on using bundler

The docs encourage you to use Bundler with fastlane. I agree that this is important for teams and CI/CD setups to ensure everyone (and everywhere) is using the exact same versions of everything. However, as a solo indie dev working on only my own machine, I find this to be overkill — especially for a single gem. I simply install fastlane and invoke it directly. Then I don’t need to check-in a Gemfile and Gemfile.lock into git.

Authentication

Setting up an API Key is the easiest method of authentication with App Store Connect, especially when working on multiple apps. You will not be constantly prompted for your Apple ID credentials and you won’t be bothered by 2-factor auth. I found that using a fastlane API Key JSON file was the simplest approach for me. I save this on my machine at ~/Developer/AppStoreConnect/api_key.json.

{
  "key_id": "XXXXXXXXXX",
  "issuer_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "key": "-----BEGIN PRIVATE KEY-----\nXXXXXXXXXX\n-----END PRIVATE KEY-----"
}

Again, not having to configure all of this on a CI machine is a joy. I don’t have to worry about accidentally leaking secrets because I misconfigured something. I also don’t have to worry about data breaches on a CI service.

Codesigning

When working on a team, using Xcode’s “automatic codesigning” feature is usually a nightmare. This is why fastlane has its own entire infrastructure for this. It is even more complicated and burdensome and tedious to get everything working on a CI/CD service, not to mention for everyone on a team. But, lucky for me, none of that applies to solo indie development!

When working alone, Xcode’s automatic codesigning works fine. You can configure fastlane accordingly. Even better, you do not have to waste your time trying to get all of this working on a CI/CD service!

I initially had some trouble getting fastlane to work with automatic codesigning. First, you need to configure your Xcode project to use automatic codesigning for all relevant targets. Second, when building via fastlane, you need to pass -allowProvisioningUpdates to the export_xcargs parameter. See the configuration files below.

Minimal configuration

Here’s the minimal configuration you’ll need for building and uploading your app.

Appfile:

app_identifier("com.example.MyApp")
apple_id("email@example.com")
itc_team_id("123456")
team_id("XXXXXXXXX")

# set other parameters as needed

Deliverfile:

api_key_path("/PATH/TO/YOUR/api_key.json")

# set other parameters as needed

Gymfile:

output_directory("./build") # relative to your project

# Enable automatic code signing and provisioning
export_xcargs("-allowProvisioningUpdates")

Screenshots

The App Store screenshot requirements are unpleasant to deal with. Luckily, fastlane snapshot can help with this for iOS. Unfortunately, it simply does not work for macOS. (See #11092, #11092-comment-349012721, #11092-comment-349273411, #19864) The good news though is that you can use fastlane to upload your macOS screenshots to App Store Connect.

For iOS, you can configure a Snapfile with all the parameters you need.

Here’s my lane for generating iOS screenshots. Because fastlane makes it trivial, I generate screenshots for all devices. Although, I really wish this weren’t necessary.

screenshots_path_ios = "./fastlane/screenshots/ios"

platform :ios do
  desc "Capture iOS screenshots"
  lane :screenshots do
    capture_screenshots(
      scheme: "SnapshotTests-iOS",
      output_directory: screenshots_path_ios,
      concurrent_simulators: true,
      devices: [
        "iPhone 15 Pro Max",
        "iPhone 14 Plus",
        "iPhone 15 Pro",
        "iPhone 14",
        "iPhone SE 3",
        "iPad Pro (12.9-inch) (6th generation)",
        "iPad Pro (12.9-inch) (2nd generation)",
        "iPad Pro (11-inch) (4th generation)",
        "iPad (9th generation)",
        "iPad mini (5th generation)"
      ]
    )
  end
end

Putting it all together

With all of this configuration complete, you can now write your Fastfile.

Below is my Fastfile for Taxatio, which runs on iOS and macOS. Like I mentioned, fastlane does not work for generating macOS screenshots, but it does work for uploading them. All you need to do is place your screenshots in fastlane/screenshots/ for fastlane to find them.

screenshots_path_ios = "./fastlane/screenshots/ios"
screenshots_path_macos = "./fastlane/screenshots/macos"

platform :ios do
  desc "Upload iOS app, metadata, and screenshots to the App Store"
  lane :appstore_upload do
    run_tests(scheme: "Taxatio-iOS")

    build_app(
      scheme: "Taxatio-iOS",
      output_name: "Taxatio-iOS"
    )

    upload_to_app_store(
      screenshots_path: screenshots_path_ios
    )
  end
end

platform :mac do
  desc "Upload macOS app, metadata, and screenshots to the App Store"
  lane :appstore_upload do
    run_tests(scheme: "Taxatio-macOS")

    build_app(
      scheme: "Taxatio-macOS",
      output_name: "Taxatio-macOS"
    )

    upload_to_app_store(
      screenshots_path: screenshots_path_macos
    )
  end
end

When ready to submit, I run the following commands:

fastlane ios appstore_upload
fastlane mac appstore_upload

Important Notes:

fastlane seems to get confused with screenshots for multiple platforms. If you provide explicit, distinct directories for each platform’s screenshots like I have above, then everything works. To me, this is also a nicer method of organization. The upload_to_app_store action uses the API Key defined in the Deliverfile, so all you need to do is provide the screenshots_path.
Even though I run tests frequently during development, I have fastlane run all unit tests first as a sanity check — just in case I forget to run them.
For building the app, I only need to provide the scheme because I’m using automatic codesigning and my Gymfile passes -allowProvisioningUpdates. I also provide unique names for the output binaries to differentiate between platforms.

Complete workflow

With all of this in place, my overall workflow is the following:

I keep all of my projects in private repos on GitHub.
I write code, build, run, and test locally via Xcode.
When ready to release, I’ll generate new screenshots if needed.
1. For iOS: fastlane ios screenshots
2. For macOS: there are a few options. I’ll write about this in another post. Once I have my Mac app screenshots ready, I put them in fastlane/screenshots/macos/.
When ready to upload to App Store Connect, I run fastlane [ios,macOS] appstore_upload.
I login to App Store Connect for a quick sanity check and submit manually.

I am very happy with this lightweight setup. I have automated the tedious and error-prone aspects of dealing with the App Store, without the hassle of maintaining a CI/CD service. Even better, now that I have found a solution that works, I can bring this over to other apps in the future beginning with the 1.0 release.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Mac menu bar apps for sale

2024-01-18T11:26:52-08:00

My Mac menu bar apps, Red Eye and Lucifer, are now for sale on my new Gumroad store.

Previously, these were free downloads on my apps website. If you currently have them installed, nothing will change for you. They will keep working. However, if you have ever been helped by one of my blog posts, enjoyed one of my conference talks, or used one of my open source libraries, then buying these apps is a great way to support my work!

I have listed them both for $2, but Gumroad allows you to pay more if you like — similar to artists selling albums on Bandcamp. I realize it’s a lot to ask you to pay for something that has been free until now, but your support is very much appreciated! And if you are able to leave a rating, that would also be great.

* * *

You might be wondering, why now? Well, I am trying to get more serious about monetization and experimenting with some different sales and distribution models outside of the Mac App Store. Since going independent, I have been financially supported primarily through freelance and contracting work. My goal is to start shifting more of my income towards my indie apps and away from freelance gigs. With these tiny menu bar apps on Gumroad, I’m dipping my toes in the water. Also, I find selling something to be a bit more compelling than simple donations like GitHub Sponsors as a way of supporting someone. (Although, if you would like to sponsor me on GitHub, that would be great too!)

More importantly, I have another Mac app that I’m planning to release this year — not on the Mac App Store. I likely will not be selling and distributing that via Gumroad. I’m currently looking into FastSpring and Paddle to determine which is a better fit. We’ll see how it all works out!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Swift protocol requirement quirks

2024-01-17T10:40:34-08:00

Perhaps “quirks” is not the correct description, but I recently encountered some unexpected behavior when modifying a protocol in Swift. While I was initially slightly confused, how Swift handles protocol requirements does make sense — conformances are more lenient than you might think!

I was updating one of my open source Swift packages, Foil, which provides a UserDefaults property wrapper. Prior to the latest release, it defined the following protocol:

protocol UserDefaultsSerializable {
    associatedtype StoredValue

    var storedValue: StoredValue { get }

    init(storedValue: StoredValue)
}

And I was changing the protocol to make the initializer failable.

- init(storedValue: StoredValue)
+ init?(storedValue: StoredValue)

I anticipated getting lots of compiler errors (or at least warnings) about conformers who declared init instead of init? — but that did not happen. It turns out, this is by design. In some situations, protocol witnesses (values or types that satisfy protocol requirements) do not have to exactly match a protocol requirement. Protocol witnesses can sometimes mismatch requirements with more “lenient” alternatives. You can see this in the example above: a non-failable init still satisfies the protocol requirements when a failable init? is specified. It might seem like a mistake at first, but this makes sense.

Consider another scenario in Swift: a non-optional value can be passed to an optional parameter in a function or set to an optional property, but not the other way around — that is, you cannot pass an optional value to a function parameter that accepts a non-optional value.

Many thanks to Olivier Halligon, Jordan Rose, and Ole Begemann for the help in understanding this in our discussion on Mastodon. You can find a thorough discussion on the Swift Forums in this post, Protocol Witness Matching Roadmap, started by Suyash Srijan.

A handful of protocol witness mismatches are currently allowed:

Non-failable initializers can satisfy failable initializer protocol requirements (as I encountered above)
Non-throwing functions can satisfy throwing function protocol requirements
Non-escaping closure parameters can satisfy @escaping protocol requirements
Generic functions can satisfy non-generic protocol requirements
Non-mutating functions can satisfy mutating protocol requirements
Enum cases can satisfy static function protocol requirements
Synchronous methods can satisfy async protocol requirements

Most other protocol witness mismatches are forbidden and will produce a compiler error.

An easy way to think about this is that the requirements above can be satisfied by more specific or more specialized declarations, but not less specific or less constrained declarations. A square is a rectangle, but a rectangle is not a square.

The forum discussion outlines further details and potential plans for the future. I recommend reading it!

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

App Store screenshot requirements need to change

2024-01-16T09:52:29-08:00

Providing screenshots for the App Store has always been a tedious and time-consuming process. But as the number of differently-sized iOS devices has grown and changed over the years, it has become more difficult to manage. (This is why the developer community built tools like fastlane snapshot.) The screenshot requirements for the App Store have increasingly become a burden for developers, especially indies. With the Mac App Store, there are fewer hurdles and less strict requirements. However, if you are now targeting only the latest OS releases and latest hardware, the screenshot requirements for both App Stores are not only burdensome but they no longer makes any sense!

A (brief) history of screen sizes

For the first ~8 years of the iPhone, screen sizes and resolutions did not change. (Yes, the iPhone 5 got a little bit taller, but it was not a dramatic change.) All devices had 3.5-inch or 4-inch displays. Similarly, iPad screen sizes and resolutions did not change for the first ~5 years. Each device has a history that can be broken up into distinct phases.

The first phase of iPhone was the original 320 x 480 display. The second phase and the first fundamental changes for iPhone came with iPhone 6 and iPhone 6 Plus (up to the 8 and 8 Plus), which had larger and higher resolution displays. These displays were 4.7-inch and 5.5-inch. The next fundamental shift occurred with iPhone X, which began the third (and current) phase. This includes the current lineup of iPhones 15, with the Plus, Pro, and Pro Max. Again, this phase brought larger screen sizes, higher resolution displays, and — importantly — different aspect ratios. The current generation of display sizes for iPhone include 5.8-inch, 6.1-inch, 6.5-inch, and 6.7-inch.

The first fundamental changes for iPad occurred with iPad Pro and then again with iPad Air. Overall, iPad screen size changes have been more subtle and resolutions have been much more consistent. The majority of iPad models have a 3:4 aspect ratio, the outliers are the recent generations of iPad Air and iPad Mini. The current generation of display sizes for iPad include 8.3-inch, 9.7-inch, 10.5-inch, 11-inch, and 12.9-inch.

If you want to browse through all the details, I highly recommend ScreenSizes.app and iOSRef.com.

* * *

On the Mac, the story is (expectedly) quite different. Obviously, the Mac is significantly older than iPhone and iPad and a significantly different machine. However, the Mac App Store is about 2.5 years younger than the iOS App Store. MacBooks have been pretty consistent in screen size and resolution. The first fundamental shift regarding resolution occurred with the Retina Displays. Over the years, there have been Mac laptops with displays ranging from 11-inches to 17-inches across the MacBook, MacBook Air, and MacBook Pro lineups. (Fun fact: with the introduction of the M-series MacBook Pro, there has been a MacBook display size for every 1-inch increment from 11 to 17.) Then there are the desktop Macs, some of which include a display like the iMac (ranging from 20-inch to 27-inch, which eventually shifted to Retina Displays) while the others require an external display. With external displays, there are too many possibilities to enumerate.

Unfortunately, I have been unable to find comprehensive resources about Mac Models and their specs like ScreenSizes.app for iOS devices. Apple does maintain a thorough Tech Specs page, but it is rather tedious to examine each product manually and individually.

* * *

I should also briefly mention that the discussion above is only considering screenshots for a single localization. If you need to provide screenshots in multiple languages, this is even more difficult to manage. Again, shoutout to fastlane for helping with this on iOS.

Aspect ratios

The most significant metric that affects screenshots is not device size, but aspect ratio. The aspect ratio of a display is what can produce the most notable differences in the content that is displayed on screen.

iPhones with a 5.8-inch screen and larger have a 19.5:9 aspect ratio, while all other modern iPhones (5.5-inch and smaller) have 16:9 aspect ratio. The now-obsolete iPhones with a 3.5-inch screen have a 3:2 aspect ratio.

Almost all iPads have a 4:3 aspect ratio. iPads with an 11-inch screen have a 10:7 aspect ratio and iPads with a 10.9-inch screen have a 23:16 aspect ratio. The single outlier is the 6th Gen iPad Mini, which is the only model with a 6.1:4 aspect ratio.

Most Macs and Apple Displays have either a 16:10 or 16:9 aspect ratio. However, the current generation of M-series MacBooks (Air and Pro) have an obscure 16:10.35 aspect ratio. So weird.

App Store screenshot requirements for iOS

You can currently upload screenshots for all device sizes, if you wish. There was a time, if I remember correctly, when Apple required screenshots for all device sizes. However, this was eventually relaxed to include only some of the larger devices, which can then be scaled down to display for smaller devices with the same aspect ratio. You can find the current screenshot specification reference here.

Screenshot requirements for iPhone:

Either 6.7-inch or 6.5-inch (the current generation of devices). Scaled versions of these will be used for 6.1-inch and 5.8-inch.
5.5-inch (iPhone 6s/7/8 Plus). Scaled versions of these will be used for 4.7-inch, 4-inch, and 3.5-inch.

However, if your app is targeting iOS 17 and later, generating 5.5-inch screenshots is impossible! There are no 5.5-inch devices that can run iOS 17! The iPhones 6s/7/8 Plus stopped at iOS 16. It doesn’t make any sense to provide these screenshots if your app only runs on iOS 17 and later.

Even more ridiculous, App Store Connect still allows you to submit 3.5-inch screenshots. Not only are those devices obsolete, it is impossible to release an app today that even runs on those devices. Xcode prevents you from setting a minimum deployment target lower than iOS 12, which does not run on any 3.5-inch device!

Luckily, for tvOS and watchOS (and now visionOS) you only need to choose a single size for all of your screenshots.

Screenshot requirements for iPad:

12.9-inch (iPad Pro 6th Gen, Face ID).
12.9-inch (iPad Pro 2nd Gen, Touch ID).

All other iPad sizes (9.7-inch, 10.5-inch, 11-inch) will use scaled versions of these. Notably, there is no option to upload screenshots for iPad Mini (not the old 7.9-inch display, nor the latest 8.3-inch display). Talk about consistency. This is certainly less cumbersome, at least there is a device of each size capable of running iOS 17.

But you might have noticed… these screenshots are exactly the same size, resolution, and aspect ratio — so why the duplication? The only difference is whether or not the device has a home button (with Touch ID) or a virtual home indicator (with Face ID). Thus, the only difference when generating these two sets of screenshots is whether or not the home indicator is present at the bottom of the screen. I understand these are fundamental differences in the hardware, but do we really need to provide both sets of screenshots just for a difference of a few pixels at the bottom of the screen?

Is a home button versus a home indicator truly a meaningful distinction for screenshots? I don’t think so, especially considering that Apple provides an API that allows your app to hide the home indicator! In this case, screenshots would be identical. I do not see a good justification for the extra work involved here to generate two sets of the same screenshots.

Suggested improvements for iOS screenshots

I suspect, similar to the iPad requirements, the primary reason that a 5.5-inch screenshots are required for iPhone — aside from the difference in aspect ratio — is that this is the largest device with a home button (Touch ID). All other sizes (5.8-inch and larger) are for devices with a home indicator (Face ID), that is, no home button.

Here are the changes I would like to see:

Remove all obsolete device sizes from App Store Connect.
Do not require screenshots for devices that cannot run your app, based on its minimum deployment target.
Do not require screenshots solely to distinguish between home button and home indicator devices.
(Maybe?) Only require screenshots for additional device sizes when there is a significant difference in size and aspect ratio, otherwise use scaled versions of the screenshots for other devices.

With these changes, developers would only need to provide the following screenshots:

iPhone 6.5-inch
iPhone 4.7-inch (optional)
iPad 12.9-inch

That’s 2 sets of screenshots instead of 4, with 1 optional set. I prefer that iPhone 4.7-inch screenshots be optional so that you only need one set per device, but I can see a valid argument against that because they have different aspect ratios. But hopefully, iPhones with 4.7-inch screens will be obsoleted with iOS 18, which then addresses this concern.

App Store screenshot requirements for macOS

As I mentioned above, the screen sizes for macOS are much more nebulous considering the numerous possibilities of externals displays. Thus, App Store Connect requires screenshots in any of the following sizes:

1280 x 800
1440 x 900
2560 x 1600
2880 x 1800

Luckily, you only have to choose one.

Notably, these all have a 16:10 aspect ratio — and that’s the problem. There is only one modern Mac that has a 16:10 aspect ratio and it’s the 13-inch MacBook Air M1. The other MacBook Air models and all MacBook Pro models have an obscure 16:10.35 aspect ratio — almost there, but just different enough to be unable to simply take a desktop screenshot and scale it down to 2880 x 1800. Instead, you’ll have to scale it down and crop it. Thanks notch! The current iMac models along with the Studio Display and Pro XDR Display all have 16:9 aspect ratios — though perhaps this is a moot point considering 4K+ images are obviously too massive.

You could simply take screenshots of your app windows at one of the specified sizes, and that will certainly work for some use cases. But what about menu bar apps? Or apps with multiple windows? Generally, I think screenshots look much nicer when your Mac app is shown within the context of a full desktop screenshot.

Looking at the apps that Apple ships via the Mac App Store, you’ll see both types of screenshots for all of them. For example, Pages for Mac only has screenshots of the app itself in fullscreen. On the other hand, the Developer App shows the app window on a full Mac desktop. Both are valid approaches and both should be easy for developers to generate.

Suggested improvements for macOS screenshots

Allowing 4K or larger desktop screenshots is obviously not feasible given their size. However, I think the App Store should allow additional aspect ratios and sizes.

Here are the changes I would like to see:

Allow 16:9 aspect ratios.
Allow the weird 16:10.35 aspect ratios for the latest MacBook lineup.
Allow at least one of the following new sizes:
1. 2560 x 1664 (MacBook Air 13” M2, at 16:10.35)
2. 3024 x 1964 (MacBook Pro 14”, at 16:10.35)

This would make it significantly easier in many scenarios to generate screenshots without having scale and/or crop everything.

Current solutions and workarounds

I’ve alluded to solutions above, but I’ll enumerate them here for clarity.

For iOS, you can automate generating all screenshots with fastlane snapshot, which alleviates the majority of these issues. The tool is somewhat clunky and definitely feels like it is aging, but it still works. It would be nice if third-party tools like this were not necessary.

To address having to provide 5.5-inch screenshots for an app that only runs on iOS 17 and later, there are a few steps and caveats. You need to satisfy the nonsensical requirement by uploading 5.5-inch screenshots, but you should also provide proper 4.7-inch screenshots, which display on devices that can run your app. Providing both is important, as Jeff Johnson has pointed out, if you only provide 5.5-inch screenshots they will be used for the 4.7-inch screen sizes. This is not ideal, because we have to manually resize them, which doesn’t look great. Here’s my process:

I generate 4.7-inch screenshots using fastlane.
I upscale these screenshots to the 5.5-inch resolution using Retrobatch. (You could also use Photoshop, Sketch, Gimp, Acorn, or any other image editor.)
Upload the (somewhat ugly) scaled 5.5-inch screenshots along with all the others (via fastlane).

Technically (again, Jeff notes) you only need to provide one 5.5-inch screenshot. Users will never see these because they’ll instead see the correct 4.7-inch screenshots. However, my automation with Retrobatch and fastlane make it trivial, so I do upload a full set for 5.5-inch screens.

For macOS screenshots, you can choose to only upload screenshots of your app windows. If you have an M-series MacBook and want to take full desktop screenshots, you’ll have to resize and crop them to 2880 x 1800. Retrobatch can streamline this process, too. Unfortunately, fastlane snapshot remains broken for macOS.

* * *

Finally, I should note that all of this only applies if you are taking proper screenshots. Unfortunately, the majority of listings in the App Store these days simply use various promotional images (sized appropriately) that were made in Photoshop, etc. But even if this is your strategy, generating screenshots in all the various sizes is still a burden. Being able to provide only a single set of screenshots per device would help.

Conclusions

I would love to see these changes (and fixes!) come to App Store Connect that make dealing with screenshots easier. Hopefully someone at Apple is listening!

References

Here are all the resources I used to find and confirm device and screenshot specifications:

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Workaround: Xcode simctl status_bar is still broken for iOS 17 simulators

2024-01-04T12:50:38-08:00

While working on updating iOS screenshots for the App Store recently, I discovered that simctl status_bar is still broken. And unfortunately, I do not expect it to be fixed any time soon.

I’ve written before about automating perfect status bar overrides for the iOS simulator using my utility, Nine41. The current bug in simctl status_bar not only prevents Nine41 from working, but also breaks every third-party tool like fastlane, SimGenie, etc. that offer a status bar override feature — because those all use simctl status_bar under-the-hood.

* * *

Previously, I realized you could still use the iOS 16.0 simulators and earlier. However, if your app is targeting iOS 17 and above — my current situation since dropping iOS 16 — then this workaround will no longer suffice because your app no longer runs on iOS 16.

The only workaround I have found is to use our good old friend, SimulatorStatusMagic — which Dave wrote years ago before simctl status_bar existed. (It is now maintained by other great folks.) In my earlier post, I tried to guess (incorrectly) what might have caused the breakage in simctl status_bar, but the project’s README explains the problem:

1) Injecting into Springboard (Required on iOS 17+)

tl;dr Running build_and_inject.sh booted will apply a default status bar to the running simulator. Replace “booted” with a simulator UDID to target a specific simulator.

As of iOS 17, the API used by SimulatorStatusMagic is not accessible to processes other than Springboard. So, in iOS 17+ we need to inject SimulatorStatusMagic into the Springboard process itself, which we do by building it as a dynamic library, and then updating Springboard’s launchd configuration to load our dynamic library.

Running build_and_inject.sh will do all of this for you. If you want to change anything about the values used in the status bar, you will need to update DynamicLibrary/main.m.

And there’s our answer: “As of iOS 17, the API used by SimulatorStatusMagic is not accessible to processes other than Springboard.” Presumably, this is why simctl status_bar no longer works. From the outside, it sometimes feels like teams within Apple have little to no communication with each other, resulting in bugs like this. Or, perhaps this is just the typical dysfunction that manifests with very large organizations.

* * *

Luckily, the status bar overrides applied using SimulatorStatusMagic will persist across simulator launches. Thus, you only need to run build_and_inject.sh booted once for each simulator. I decided to just do this for all of my simulators so that I never have to worry about this. (Honestly, there’s really no reason for them to ever show the current date and time.)

If you fully reset a simulator using Erase All Content and Settings..., then you will need to re-run the script for that simulator. Once you apply the overrides to the simulators, you can use whatever screenshot automation tools you prefer (Xcode UITests, fastlane snapshot, etc.) and the status bar overrides will remain. If you need this functionality on a CI service, you are in for a bit more work, but it is possible.

This is far from ideal, but at least we have a workaround that allows us to continue creating great screenshots.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Another frivolous and frustrating App Store rejection

2024-01-03T18:34:44-08:00

I’m happy to share that I released an update to Taxatio today, but unfortunately it was not without a lot of friction and hassle with the App Store approval process.

Taxatio is a universal app for iOS and macOS. I submitted the same update (version 1.3.0) for both platforms on December 30. The iOS app was accepted within a few hours, which was excellent. However, the macOS update was delayed for a ridiculous reason, after waiting to be reviewed for three entire days.

It is important to note — and I cannot stress this enough — the iOS app and macOS app are nearly identical. They are SwiftUI apps with the exact same functionality and they share 90 percent of their code. The metadata in the App Store for each is exactly the same, the only exception is the screenshots. So, it was curious to me how one could be approved within hours while the other was waiting to be reviewed for multiple days — ultimately, only to be rejected.

So what happened? On January 2, three days after submitting to App Review and three days after the iOS app was approved, I received this message from App Store Review (yes, with this formatting and typos):

Bug Fix Submissions

The issues we’ve identified below are eligible to be resolved on your next update. If this submission includes bug fixes and you’d like to have it approved at this time, reply to this message and let us know. You do not need to resubmit your app for us to proceed.

Alternatively, if you’d like to resolve these issues now, please review the details, make the appropriate changes, and resubmit.

Guideline 2.3 - Performance - Accurate Metadata

We noticed that your app’s metadata includes the following information, which is not relevant to the app’s content and functionality:

What’ new text showed iOS reference.

Next Steps

To resolve this issue, please revise or remove this content from your app’s metadata. For resources on metadata best practices, you may want to review the App Store Product Page information available on the Apple Developer website.

In my release notes for this update for both the iOS app and the macOS app, I wrote:

Dropped support for iOS 16 and macOS 13. Now requires minimum iOS 17 and macOS 14.

So acknowledging that my app is a universal app — a fact that users are aware of — is grounds for a rejection? That is beyond ridiculous, especially considering the iOS app contained the exact same release notes and got approved. I mean, seriously! What a fucking joke! Not to mention, Apple actively encourages developers to support universal purchases for apps available on their platforms since they started supporting this in 2020. I do not think that mentioning OS support changes for a universal app is “not relevant” and I certainly do not think it should result in a rejection. It’s harmless.

I replied asking to be approved anyway and “resolve” the “issues” on my next update — but surprise, my release notes for the next update will be completely different anyway. I replied shortly after receiving the rejection notice, hoping that the turn around would be quick — I had already waited three days! Of course, it took another entire day to finally be approved on January 3. That means time from submission to approval was four days in total.

I have two major complaints about this process.

First, the inconsistency is absolutely maddening. The time discrepancy between review times between platforms is annoying, especially considering you can submit multiple items for review for a universal app at once — and the fact that, you know, the app is universal. Wouldn’t it make sense to review and approve both at the same time? More obviously and more infuriating is the fact that these apps are identical with identical release notes. There were no issues with the iOS app release notes mentioning macOS, but apparently you cannot mention iOS in the release notes for a macOS app.

Second, while I appreciate Apple’s new approach to allowing apps to be approved for minor “violations” without having to resubmit, it does not work well in practice (obviously). In 2020, Apple announced “for apps that are already on the App Store, bug fixes will no longer be delayed over guideline violations except for those related to legal issues. Developers will instead be able to address the issue in their next submission.” (Emphasis mine.) This sounded great in 2020, but the problem is that my app release was still delayed. I’m glad I did not have to wait another three days, but I did have to wait another entire day because of this inconsistent, bureaucratic nonsense. Instead of the back-and-forth, why not simply approve the submission immediately and then mandate changes on the next submission?

It is so disappointing, after so many years, that the App Store approval process continues to be so erratic, unpredictable, petty, and (often) slow for such benign app updates — all the while scam apps continue to get approved and promoted in the top charts, much less get rejected.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

A list of books I read in 2023

2023-12-29T12:02:14-08:00

Continuing another tradition, here are the books I read in 2023. Similar to my previous post highlighting my top posts of 2023, I also skipped publishing my reading list last year, for 2022. Again, I was simply too burnt out by the end of that year. I also did not read that much compared to previous years — thanks again to burnout. You can find previous years here under the #reading-list tag.

Since I skipped last year, I’ll include everything for 2022 and 2023 in this list. As usual, these are in no particular order but I’ve grouped books by the same author together.

The Will to Change: Men, Masculinity, and Love, by bell hooks
Bone Black, by bell hooks
All About Love: New Visions, by bell hooks
Night Sky with Exit Wounds, by Ocean Vuong
Time Is a Mother, by Ocean Vuong
Happy-Go-Lucky, by David Sedaris
The Hidden Life of Trees, by Peter Wohlleben
War and Peace in Kurdistan, by Abdullah Öcalan
Liberating Life: Woman’s Revolution, by Abdullah Öcalan
Arabian Love Poems, by Nizar Qabbani
Salt Houses, by Hala Alyan
How to Be an Antiracist, by Ibram X. Kendi

Hopefully, I can get back into a better reading routine for 2024.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

How to fix Mac menu bar icons hidden by the MacBook notch

2023-12-16T10:48:15-08:00

Last week I wrote about setting up a new MacBook Pro — my first Apple Silicon Mac, and thus my first MacBook with a notch. I lamented how poorly macOS interacts with the notch, specifically how menu bar apps and icons simply get hidden if you have too many to display. Lots of folks on Mastodon offered various solutions, and some readers emailed me with options as well. I figured it was worth making a separate post about this specific issue to list all of the workarounds and alternatives. It is clear that this is a widespread problem that users are having.

Problems with the notch

I previously wrote:

I have gripes about the notch. There isn’t enough room to display all of my menu bar apps and icons, so… they just get hidden!? Apparently, everyone in Cupertino thinks the best solution to this problem is to hide them with zero indication that there are more that simply can’t be displayed because of the notch. I wasted so much time trying to figure out why Little Snitch and 1Password were not running on my new machine. Was there a compatibility issue with Apple Silicon that I didn’t know about? That couldn’t be. It turns out, they were running the whole time but they were hidden by the notch.

[…]

This “design” (or lack thereof) is so dumb. It is utterly ridiculous to me that this is still how it “works” two years after the introduction of the redesigned MacBook Pro with a notch. How hard could it be to add an overflow menu with a “«” (or should it be “»”?) button that shows the remaining apps and icons that can’t be displayed? This entire situation with the notch is ironic, because the iPhone notch and “dynamic island” are so thoughtfully designed with zero compromises regarding the functionality of iOS. In fact, they actually provide a better user experience. Yet on the Mac, how the notch interacts with macOS is laughably incompetent. It is shockingly lazy regarding attention to detail, and results in an outright disruptive and confusing user experience.

And as Michael Tsai pointed out, the situation from a developer’s perspective is just as bad:

Aside from the problem of the icons being hidden, there’s no API for an app to tell whether its icon is hidden. NSStatusItem.isVisible tells you whether the app or user wants the icon to be visible, but it will return true if the icon is hidden in the notch—or even if it’s hidden behind a menu title.

First-party workarounds

If you prefer not to install any third-party apps (like me), there are a number of steps you can take to alleviate your crowded menu bar and possibly remedy the issue entirely (which I’ve successfully done). My goal with the steps below is to get all of my apps and icons to display when Finder is active. Some applications have more menu items that span across the other side of the notch, and in this scenario there is not much we can do to prevent hidden menu bar icons — which was actually the case before the notch existed for applications with a very large number of menu items.

Move macOS system-provided icons into Control Center. A number of icons can be configured to display only in Control Center, which frees up space in your menu bar for icons and third-party apps that must be displayed in the menu bar. For example, you can move WiFi, Bluetooth, Battery level, AirDrop, etc. into Control Center. Additionally, some icons can be configured to only display when they are active, like Focus status or Screen Mirroring.
Reorder your apps and icons from right to left to display the ones that are most important to you on the right and least important on the left. The result is that the least important icons are the ones that get hidden by application menus or the notch, while the most important icons are more likely to remain visible. For example, I like having Time Machine in the menu bar, but it doesn’t matter if it gets hidden while I’m working in an app with a large menu that spans to the other side of the notch, thus hiding Time Machine. Therefore, I have placed Time Machine in the left-most position. Furthermore, I place system icons that display only when active (like Focus status) in the right most position. This is important for me, because I want to make sure I always see when these things are active.
Reduce the menu bar item spacing and padding via UserDefaults. (Thanks to Oliver Busch for the tip. Also see this Reddit post.) There are two defaults settings you can configure via Terminal, NSStatusItemSpacing and NSStatusItemSelectionPadding.

Read the current defaults:

defaults -currentHost read -globalDomain NSStatusItemSpacing
defaults -currentHost read -globalDomain NSStatusItemSelectionPadding

Note: These values are not set by default. This means you will get an error that the keys and values do not exist if you have not previously set them.

Write the defaults by providing an integer value:

defaults -currentHost write -globalDomain NSStatusItemSpacing -int 12
defaults -currentHost write -globalDomain NSStatusItemSelectionPadding -int 8
killall SystemUIServer

After some experimentation, I landed on the values above — 12 for spacing and 8 for padding fit my needs. You should experiment as well. The smallest tolerable values are probably around 6 or 8.

Remove the values to restore the default behavior:

defaults -currentHost delete -globalDomain NSStatusItemSpacing
defaults -currentHost delete -globalDomain NSStatusItemSelectionPadding
killall SystemUIServer

Third-party solutions

There are several third-party applications to help organize and manage all of your menu bar apps and icons. The apps I have listed below seem to capture the three broad categories of possible solutions. I know there are a few others out there with similar functionality, but I think these are the most representative.

Bartender. (Paid with Free Trial. Website). This one is very advanced and complex with elaborate customization options, including styling the entire menu bar. It works well, but I found it to be very heavy-handed and a bit cumbersome for my needs. It felt clunky and glitchy to me, in ways that I think the developer has tried hard to mitigate, but I imagine Apple does not make developing this sort of app easy. (I don’t think there are any public APIs for this stuff.) Bartender seems to rely on some hacks (like screen recording) to dynamically hide and show your overflowed menu bar apps. Like iOS, macOS now has a privacy feature where you are notified when apps are using the camera, microphone, screen recording, etc. On iOS there’s a little dot indicator that shows in the status bar, on macOS there’s an icon that displays in your menu bar. One specific issue I had with Bartender, was that the privacy indicator icon for screen recording appears very frequently, which was annoying.
Hidden Bar. (Free. Mac App Store, GitHub). This one is extremely lightweight, providing a simple chevron “<” icon to expand and collapse the extra icons. You can customize which icons are always shown, and which are hidden when the menu is collapsed.
Say No to Notch. (Free with IAPs, Mac App Store). This is another heavy-handed approach. This one adds a letterboxed-style black bar to the top of your screen and shifts the entire menu bar down below the notch — along with the entire contents of your screen. I do not like the reduced screen real estate that this creates.

All of these apps have pros and cons. Unfortunately, I was not quite satisfied with any of them. However, your experience and preferences might be very different!

Update 29 May 2024

Thanks to reader Moritz Thiele who suggested some alternative third-party solutions. They use zNotch in combination with Raycast shortcuts.

Conclusion

As noted above, I have opted for the collection of first-party workarounds. For me, all of the third-party apps felt cumbersome, wonky, lacking, or simply did not match my aesthetic taste. That’s not to say they aren’t great apps and creative solutions — they just aren’t for me. In any case, I hope this post has been helpful if you’ve been searching for solutions to the MacBook notch problem.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Find me on Mastodon

2023-12-15T16:28:37-08:00

With the recent announcement that Threads.net is starting to integrate with ActivityPub, I figured it would be a good time to remind folks that you can follow me on Mastodon at @jsq@mastodon.social. Many of my connections have moved over from Twitter — but sadly, not all of them. Although, some have moved over to Threads. If you would like to join Mastodon.social, you can use my invite link.

As I previously wrote, Mastodon is pretty fucking awesome and I really enjoy it. It is currently my only (active) social media account. I am no longer using Twitter, for reasons I hope should be obvious by now. Seriously, what a shitshow. However, my posts on this blog are still automatically posted to Twitter for now. (That’s another reason for this post, so I don’t have to login to that awful website.)

I have no plans to create an account on Threads. Let’s be honest, Facebook is truly not that much better than Twitter. All (for-profit) social media is predatory, manipulative, invasive, and socially destructive.

If you were hoping to find me on Threads, sorry. But if Threads follows through on its promise to federate, then that shouldn’t be a problem for either of us.

Originally published on jessesquires.com.

Hire me for iOS freelance and contracting work.

Buy my apps.

Sponsor my blog and open source projects.

Jesse Squires

Mariposa: a lightweight Swift CLI to automate sharing blog posts to social media

Motivation

How it works

Workflow

Example usage

Developer notes

Workaround: how to silence individual deprecation warnings in Swift

Treating warnings as errors

Using Clang #pragma directives

Swift workaround

How does this even work?

Is this practical?

How to automate perfect screenshots for the Mac App Store

Screenshot composition

Current options for Mac app screenshots

Automatic screenshots via Xcode

Post-processing Xcode screenshots

Perfect menu bar and desktop background

The final product

How to remove unwanted Swift Package schemes in Xcode

* * *

AI Code review is always wrong

Xcode Tip: spell checking

Reading Notes: From misery to boredom to anxiety

* * *

* * *

* * *

* * *

* * *

* * *

* * *

* * *

Type erasure for Equatable and Hashable types in Swift: Lessons from ReactiveCollectionsKit

A brief overview and history of type erasure in Swift

Generics and type erasure in ReactiveCollectionsKit

Conclusion

UIKit DiffableDataSource API inconsistencies with Swift Concurrency annotations explained

Diffing in ReactiveCollectionsKit: Understanding Identity and Equality

Identity

Equality

Becoming diffable

Shortcomings in UIKit

Introducing ReactiveCollectionsKit: A Swift replacement for IGListKit

A very brief history

What about SwiftUI?

ReactiveCollectionsKit overview

Architecture and design

Review of prior art

IGListKit

ReactiveLists

JSQDataSourcesKit

Goals

Future Work

Kintsugi

* * *

SwiftUI's Observable macro is not a drop-in replacement for ObservableObject

Background

Example

The bug

The fix

Additional reading

UI testing improvements in Xcode 16

Our App Store screenshot nightmare is (almost) over

* * *

SwiftUI app lifecycle: issues with ScenePhase and using AppDelegate adaptors

Limitations of ScenePhase events (and view lifecycle events)

Bugs and quirks with ScenePhase

Behavior on iOS

Behavior on macOS

App delegate adaptors are discouraged

Using app delegate adaptors (and their issues)

Conclusion

Swift concurrency hack for passing non-sendable closures: Uncheck yourself before you wreck yourself

Background

Solution (It’s a hack)

Is this good?

Update 05 June 2024

Workaround: Xcode deletes Package.resolved file and produces 'missing package product' errors

The bug

Using Clang `#pragma` directives

Limitations of `ScenePhase` events (and view lifecycle events)

Bugs and quirks with `ScenePhase`

The `Package.resolved` file and git

Handling `Package.resolved` deletions