Designing macOS Menu Bar Extras

A great article by Marc Edwards, essentially the “missing manual” for macOS menu bar extras:

Apple’s HIG is great, but it doesn‘t contain much information related to designing menu bar extras. This article aims to provide additional details and context needed to create icons for macOS menu bar extras.

There are a lot of subtleties to get right, and this will help you if you are unfamiliar with the conventions!

Quieting CVDisplayLink Logging

In recent months I’ve noticed an accumulation of garbage log messages when I’m debugging an app in Xcode. Line after line along the lines of:

[] [0x124858a00] CVDisplayLinkStart
[] [0x124858a20] CVDisplayLink::start
[] [0x600003c3cee0] CVXTime::reset

Today I went digging to find the source of these log messages, and in the process I discovered a workaround that disables them. Just pass “-cv_note 0” as a parameter to the Run task in the Xcode scheme. Alternatively, you could disable them across all of your apps by setting this global default:

defaults write com.apple.corevideo cv_note 0

The only downside to disabling the messages globally is that you will have to remember you disabled it if you ever decide you want to see massive quantities of Core Video debugging logs!

I discovered this user default by spelunking the system frameworks code from which they originate. After setting a breakpoint early in my app’s launch, I set a breakpoint on a variety of logging related methods until I discovered that these messages are all originating from a function called cv_note() in the CoreVideo framework. Within that function, there is a call to another function called “cv_note_init_logging_once”, and within that is a check for a user default value along with this tasty morsel:

Screenshot of Xcode disassembly showing a log message: Thanks for setting defaults write com.apple.corevideo cv_note -int %d

And thank you, Apple, for providing such a mechanism, even if it’s unfortunately configured to log by default. I filed FB9960090: “CoreVideo logging should default to 0”, requesting that Apple change the behavior of this initialization function so that if a user has not set the cv_note value to anything particular, it defaults to 0.

Hacking NSAlert Button Appearance

This morning my attention was grabbed by an old post in the Apple Developer Forums, bemoaning the appearance of NSAlert in Big Sur. No, not the usual complaints about alerts on Big Sur and later, but specifically about the way buttons appear when there are more than three:

screenshot of macOS alert panel with three primary buttons, two of which are drawn without a border or background

Notice how the “Bar” and “Baz” buttons do not have a border or background color, making it difficult to know whether they are even buttons at all. The line between Bar and Baz clunks up the interface even more.

At first I thought this situation was the result of more buttons than were expected being squeezed into too small a space, but after some experimentation I discovered that even forcing the alert to give the buttons more room did not alleviate the problem. This exploded view from the Xcode view debugger shows that the top, default button, is showing the background for the button, while the other buttons don’t have one at all:

screenshot of view debugger from Xcode with 3-dimensional layout of UI components

After a good amount of hacking about in the debugger, I discovered the cause was rooted in the buttons simply having their showsBorderOnlyWhileMouseInside property set to true. This suggests it’s a stylistic decision on Apple’s part, but I have to think it wasn’t completely thought through because this simply does not look good! Furthermore, that clunky line after the second button seems to be placed there as an alternative to the buttons being distinguished by their own backgrounds. It looks particularly weird to my eye, so much that it looks more like an unintended drawing glitch than an intentional interface element.

So how would you work around such a problem? As I shared in the thread on the forums, one approach that seems both safe and effective is to patch up the appearance of the buttons, and hide the unwanted line. Because NSAlert performs a great number of modifications as it’s displaying the alert, you have to subclass and override its “layout()” method to catch it after it’s done tweaking the UI:

class HackAlert: NSAlert {
  @objc override func layout() {
    super.layout()

    for button in self.buttons {
      button.showsBorderOnlyWhileMouseInside = false
    }

    if let container = self.buttons.first?.superview {
      let boxes = container.subviews.compactMap { $0 as? NSBox }
      boxes.forEach { $0.isHidden = true }
    }
  }
}

With the hack in effect, the alert looks much nicer:

screenshot of macOS alert with all buttons showing visible background bezel

The key to hacking framework shortcomings is to identify a way to make the tweak such that the desired outcome is achieved, with little risk of unwanted outcomes. The changes I made here are only likely to cause problems if, in the future, Apple redesigns the UI so that it really does make sense for these buttons to “hide their borders”, or if Apple adds additional NSBox elements to the container view that holds these buttons. These seem unlikely enough to proceed with caution, but as always you should weigh the risks yourself, and only ship what you’re comfortable with!

Hold It Right There

In Apple’s latest round of pro laptops, the much-maligned Touch Bar is notably absent from the lineup. Like many people, I never found the Touch Bar to be super useful, but there was one convenience I consistently found indispensible: its support for invoking Xcode commands while debugging an app.

Any Mac or iOS developer will be familiar with the strip of buttons that facilitate various debugging tasks in Xcode:

screen capture of Xcode's debugger buttons

Being able to enable and disable breakpoints, pause and resume the app, and break into Xcode’s View Debugger are crucial to testing and debugging app functionality, and most of the time just clicking the button right in Xcode is all you need. But in some circumstances, to achieve the desired outcome, one of these buttons would have to be effectively clicked without interrupting an action in the target app such as tracking a button or menu item. In those situations, it was particularly useful to be able to set up the debug scenario in the host app, and then to simply tap a corresponding button on the Touch Bar to invoke the desired debugging utility.

For example if I am debugging FastScripts, my menu-bar based scripting utility, I might want to break into the view debugger while the menu bar icon is highlighted and the mouse is tracking menu items:

screenshot of FastScripts menu bar icon invoked with the script menu displayed

Since I gave up the Touch Bar, I’ve been at a loss for how to deal with this kind of situation, so I’ve worked around the problem as best as I can. Still, it’s frustrating after all that time enjoying the advantages of the Touch Bar, to have to give it up.

Today I finally devised a permanent solution that works independently of the Touch Bar, facilitated by none other than FastScripts itself: custom scripts to trigger the pertinent buttons by way of AppleScript GUI Scripting.

screen capture of FastScripts menu items for View Debugger, Pause or Continue, and Toggle Breakpoints

I chose the keyboard shortcuts to be convenient enough for me to invoke with my left hand while tracking the mouse with my right. Now when I am midway through a menu selection and want to instantly capture the view hierarchy for debugging, I just press Cmd-Shift-Ctrl-` and I’m off to the races.

If you think you might find this useful, download all three scripts and configure them with your favorite keyboard shortcut utility. As I’ve mentioned, FastScripts will do a great job, but the scripts should work just as well with a variety of other utilities.

I want to acknowledge Daniel Kennett, who accomplished the same type of functionality by programming his Stream Deck to simulate the behavior of the Touch Bar’s Xcode interface. His solution inspired me to finally follow through on my longstanding plan to develop these scripts. For those of you who prefer a physical interface, and have access to a Stream Deck, his project might be just the ticket!

Xcode’s Environmental Pollution

For a while now my build server has been issuing a large number of mysterious but important sounding warnings along these lines:

warning: include location '/usr/local/include' is unsafe for cross-compilation [-Wpoison-system-directories]

I’m allergic to warnings, and tend to abide by a 100% no-warnings-allowed policy, at least when it comes to release builds. So it was important to me to track this down and finally silence it.

I was really scratching my head because I don’t specify this include location anywhere in my build commands. Normally when an issue like this comes up, it’s easy enough to debug the problem by copying the build command out of the build log and pasting it into the Terminal. Invoking it independently of the xcodebuild process usually reproduces the same warning, and gives you the specific combination of command line options that is leading to the warning being generated.

In this case however, copying and pasting the command line to the Terminal did not yield the warning. What’s going on?

I figured I would take a step back and just try to reproduce the problem independently from my build scripts. Instead of copying and pasting the specific “clang” invocation that yields the warning, I’ll copy and paste the “xcodebuild” line instead. Bzzt! Still no warning.

After a lot of trial and error, I came across the strangest observation: if I invoke “xcodebuild” from within my Python-based build script, the warning is emitted. If I invoke it directly from the Terminal, it isn’t. In fact, if I simplify my build script to simply invoking “xcodebuild”, the warning happens. Stranger still? If I change the script from “python3” to just “python”, the warning goes away again.

I strongly suspected that the difference in behavior must be based in environment variables, so I decided to add a line to the top of the python script:

import os; print(os.environ)

Sure enough, the environment variables differed when I ran the script with “python” vs. “python3”. To get a feel on your own Mac for how the two commands differ, you could run this as a one-liner with python and with python3:

python3 -c "import os; print(os.environ)"

If your configuration is like mine, the output will include a “CPATH” value something like this:

{... 'CPATH': '/usr/local/include', 'LIBRARY_PATH': '/usr/local/lib'}

That “CPATH” entry for example only exists when invoking the script with python3, and it’s this very environment variable that is creating the unexpected Xcode warnings!

I was perplexed about how or why the version of Python could impact these environment variables, but then I remembered that python3 is bundled in Xcode itself, and the version at /usr/bin/python3 is a special kind of shim binary that directs Apple to locate and run the Xcode-bundled version of the tool. Apparently, a side-effect of this mechanism causes the problematic environment variable to be set! Running the python3 implementation directly where it lives in the Xcode installation:

`xcrun -f python3` -c "import os; print(os.environ);"

Does not exhibit the problematic environment variable!

So the issue is not about running python vs. python3 per se, but about invoking an Xcode build via any mechanism that leads to Apple’s “relocation” shim being executed and inadvertently mucking with environment variables that will impact the build process. I’ve filed FB9776086 requesting that the unwanted environment variables not be set when invoking commands, but in lieu of a system-wide fix, I’ll be adding this to the top of my Python build scripts:

import os
if "CPATH" in os.environ: os.environ.pop("CPATH")

Now my automated builds are beautifully warning-free again!

Dangerous Logging in Swift

I recently came across a perplexing crash in my unit tests that led me down a path of discovery, culminating in an awareness that “I was holding it wrong” when it comes to using NSLog in Swift.

Here is the source code to an extension on FileManager intended to make it easy to read the last modification date of a file:

@objc(rsLastModificationDateAtURL:)
func lastModifedDate(at url: URL) -> Date? {
    do {
        let resourceValues = try url.resourceValues(forKeys: [.contentModificationDateKey])
        return resourceValues.contentModificationDate
    } catch {
        NSLog("Failed to get modification date at URL: \(url) - \(error)")
        return nil
    }
}

I’ve highlighted the line of interest, an invocation of NSLog in the case where a modification date could not be read because of some exception. For example, if the file were not found this line of code would be reached. Looks innocent enough, right? Here’s what I came up against while running the unit tests for one of my apps:

highlighted source code line showing NSLog invocation crashing with EXC_BAD_ACCESS

At first I thought that one of the url or the error variables must be bad. After all, Swift string interpolation and NSLog are both battle-tested. Surely if there were a way to easily crash by logging good variables, it would be fixed a long time ago. But no, both of the variables in this instance were perfectly valid references. So what gives?

The Problem

The problem is rooted in the fact that NSLog from Swift calls through to the underlying C-based interface which supports template strings and variadic arguments. This is why, for example, you can invoke NSLog(@"Hi %@", name) in Objective-C and, if name represents the string “Daniel”, you get “Hi Daniel” printed to the console.

In the scenario of my crash, the interpolation of “url” and “error” results in surprise template placeholders, because of the presence of spaces in the path that the URL represents. In my tests, a file called “Open Program Ideas File” exists and is used to test some file manipulations. When the path to this file is encoded as a URL, the name of the file becomes “Open%20Program%20Ideas%20File”. Since the error’s failure message reiterates the name of the file it couldn’t find, we end up with another copy of the percent-escaped string in the parameter to NSLog. Each instance of “%20” followed by a letter is liable to be interpreted by NSLog as a printf-style format specifier. So as far as our filename’s string is concerned, we have “%20P”, “%20I”, and “%20F” threatening to cause trouble. Capital letters in printf formats are pretty uncommon, but the %F format specifier is documented as:

64-bit floating-point number (double), printed in decimal notation

In short, we have a situation where logging the URL and the error inadvertently asks NSLog to look for a 64-bit floating point number in the arguments list. A 64-bit floating point number of size 20, whatever that means in this case. So, whether the unit test, or app, crashes or not in a situation like this depends entirely on what data happen to be in the places where the variadic arguments would be, and whether that data causes a crash when attempting to interpret it as a type of the specified print format.

How to Fix It

So how do we fix it? Well, we need to make sure that the string that ultimately gets passed to NSLog doesn’t contain these surprise placeholder values. If this were Objective-C, we wouldn’t run into the problem because the parameters would need to be passed as variadic arguments:

NSLog(@"Failed to get modification date: %@ - %@", url, error);

But if we try that in Swift, we run into trouble. NSLog in Swift doesn’t support variadic arguments:

screenshot of build error indicating that variadic arguments are not allowed with NSLog in Swift

I’m pretty sure this is how I ended up in this situation in the first place: I probably tried to adapt my old Objective-C code to Swift, ran into this error, and obediently changed to using inline variable substitution instead. It just seemed like “the Swift thing to do.” But if we can’t use NSLog with inline substitution, and we can’t use variadic arguments, what are we supposed to do? Update: Thanks to Sebastian Celis for pointing out on Twitter that variadic arguments do work with NSLog. I think the failure above is specifically because I’m passing non-NSObjects to NSLog, which isn’t supported.

A few years ago Apple introduced a new logging framework called the Unified Logging System, which supports logging with variadic arguments from both Swift and Objective-C. It also supports a host of other features that allow you to categorize and prioritize your log message and, well, it sounds great, but it’s also quite a bit more complicated than just invoking NSLog. It’s complicated enough that I can’t offer a one-line fix for the situation I’ve described here, but I encourage you to investigate your options.

Audit Your Code

I also encourage you to audit your own code, and I’ll describe a method for searching your own code base to see if you might be vulnerable to the kind of unpredictable crash that inline interpolation can cause with NSLog. In Xcode, create a custom search scope that allows you to easily search just the Swift files in your code base, then search for instances of the problematic pattern. Obviously if you’ve got a 100%-Swift code base, creating the custom search scope is not necessary:

  1. Show the Find Navigator by selecting View -> Navigator -> Find from the menu bar.
  2. Click the “In Project” (by default) search scope label beneath the search field. This reveals the list of search scopes currently configured in your workspace.
  3. Click the “New Scope” button and configure a scope designed to match all files with the “swift” file extension”:

    screenshot of custom search scope popover showing title

  4. Click the Find type (“Text” by default) in the search parameters above the search field, and change it to “Regular Expression”.
  5. Type or paste in the search string NSLog\(.*\\\( — this is a regular expression that will find intances of the string “NSLog(” followed by any number of characters that includes the substring \(, the tell-tale sign of Swift string interpolation:

    screenshot of search results showing multiple files with

In my own code base, this audit results in an alarming 23 instances in 17 files, all of which I will soon be converting to a safer logging method. I encourage you to do the same in your code base. Hopefully you’ll have been followingn a safer pattern all along and won’t have any work to do, but if you’re anything like me, you might find you’re more vulnerable to the problem than you thought!

Discoverable Key Commands

As I make progress on Black Ink for iOS, I have taken care to add keyboard shortcuts to make the app more usable on an iPad with external keyboard. One standard behavior of iPadOS is that when an app supports keyboard shortcuts, simply holding down the command key presents a nice heads-up display (HUD) with the list of shortcuts. For example, if you press the command key on the iPad home screen, you’ll see something like this:

Screenshot of prompt showing list of keyboard shortcuts on iPad.

This panel is supposed to appear automatically for any app that declares keyboard shortcuts using the UIKeyCommand interface of UIKit, which Black Ink does. I couldn’t figure out why the panel never appeared in the app. When the Command key is pressed, I confirmed that my puzzle view was the “first responder”, meaning it is the view that iOS should consult when building the list of key commands to show. What could possibly be going wrong?

Never being one to take the easy route when solving a problem, I found myself tracing the UIKit system code deep into the infrastructure that determines whether or not to show a panel or not. When the command key is held for a sufficiently long time, an internal timer expires and “-[UIKeyCommandDiscoverabilityHUD _HUDPopTimerFired:]” is reached. This method ends up calling a private “_performableKeyCommandsWithResponder:” method, which finally leads to some code that … asks each UIKeyCommand for its discoverabilityTitle, or as a backup, its title. Hmm, what is the discoverability title? Let’s look at the header for UIKeyCommmand:

// Creates an key command that will _not_ be discoverable in the UI.
+ (instancetype)keyCommandWithInput:(NSString *)input modifierFlags:(UIKeyModifierFlags)modifierFlags action:(SEL)action;

// Key Commands with a discoverabilityTitle _will_ be discoverable in the UI.
+ (instancetype)keyCommandWithInput:(NSString *)input modifierFlags:(UIKeyModifierFlags)modifierFlags action:(SEL)action discoverabilityTitle:(NSString *)discoverabilityTitle;

Face, meet palm.

When implementing support for keyboard shortcuts, I had leaned on code completion and went with the easiest option. The shortcuts worked, so what could go wrong? It turns out you have to declare a title for UIKeyCommand or the system won’t present a prompt to users about it. It makes sense, because what would it list as the explanation for what it does, if nothing is set on it?

After I added discoverability titles, everything looks as it should:

Screenshot of Black Ink for iOS showing a full list of keyboard shortcuts for puzzle navigation, etc.

Hopefully this will help others who are stuck trying to figure out why their app’s keyboard shortcuts aren’t showing up.

Not Applicable

From time to time, particularly when I’m working with xib files of a certain vintage, Xcode simply refuses to offer any inspector tools for the contents of a particular Interface Builder document. Instead of the typical controls for setting an object’s properties, I get this:

UntitledImage

Look familiar? It’s super-frustrating when you simply can’t get at the settings for something you desperately need to change. I’ve sometimes gotten Xcode to relent through some combination of closing the file in question, closing assistant editors, etc. But sometimes I just can’t get it to show the properties for an object no matter what I try.

The one thing that always works is to simply make a copy of the xib file in question, which Xcode will happily edit, and then copy it back over the original. It’s really that simple:

  1. Copy MyInterface.xib to MyInterface Copy.xib
  2. Double-click the copy to edit it.
  3. Save changes.
  4. Replace MyInterface.xib with MyInterface Copy.xib

This has vexed me long and hard enough that I thought some others will not have recognized there is such an easy workaround. It would be great if Apple fixes whatever bug is causing this, but in the meantime at least there’s a solution.

Similar Detritus Not Allowed

Over the past few weeks, I’ve noticed a spike in the number of Mac and iOS developers who are running into a specific code signing error while building their apps. I myself ran into it last week after saving a new version of an image file from Preview into my app’s bundled resources.

I’ve noticed folks on Twitter and in developer Slack’s coming up with the same problem. I don’t know if something has changed in the code signing toolchain, or we’re just having an unlucky break, but I thought I’d blog about it because it seems many people may need this advice now.

The error in question is always along these lines:

resource fork, Finder information, or similar detritus not allowed

It comes up when the code signing process comes across traces of metadata in one of the files that is bundled with your app, or in some instances in the binary executable itself. This problem is common enough that Apple even posted a technical note several years ago that explains:

Code signing no longer allows any file in an app bundle to have an extended attribute containing a resource fork or Finder info.

This technical note gives advice for how to use the xattr tool to both examine and remove the unwanted extended attributes on the file. At least one colleague has reported that whatever was wrong with the file in their case was not detectable by xattr and therefore also not reparable with that tool.

Here’s a foolproof trick that is likely to address the problem, whether it’s unwanted extended attributes, resource forks, or whatever. Simply cat the affected file into another file, and then replace the original. For example, if you’ve got an image file called Whatever.png in your app, and it’s triggering the error above, try this in the Terminal:

cat Whatever.png > Whatever2.png
mv Whatever2.png Whatever.png

Et voilà! It’s as simple as that. The cat command cares not about whatever special attributes or resource forks are causing the code signing process grief. It only cares about the binary bits that comprise “the main file”.

Excluded Embedded Binaries

After updating to Xcode 11.5 my release builds started failing because a failure in the “embedded binary validation” build step, which occurs after the last explicit build phase over which we as developers have the ability to affect how products are built.

I was able to trace the problem to an attempt to validate an app extension that is embedded into my app but then removed by a later build phase. The rationale here is that the app extension in question is used internally, and shouldn’t be shipped to customers. But you can’t have dependencies and binary embedding vary based on the build configuration, so I always build the app extension, embed it, and remove it only when building a “Release” build.

This strategy has worked well for years, but in the latest Xcode, it attempts to validate the embedded binary even if it no longer exists. I guess there’s some wisdom to this. After all, a missing binary certainly isn’t valid! But historically Xcode has allowed custom build phases to substantially change the layout and contents of the built product without causing the post-build steps to fail.

I created and submitted to Apple a simple test app that exhibits the problem. In this case, an app named InvalidApp.app embeds an app extension Whatever.appex, and then removes it in a build phase. It results in this errr:

error: Couldn't load Info dictionary for <DVTFilePath:0x7f86ef4be800:'/Users/daniel/Library/Developer/Xcode/DerivedData/InvalidApp-bqvdubwezowsaccymccleomclddp/Build/Products/Debug/InvalidApp.app/Contents/PlugIns/Whatever.appex'> (in target 'InvalidApp' from project 'InvalidApp')

Yes, there is no Info.plist for this app extension because the whole thing is gone! I worried that I would have to rejigger my whole build process and figure out another way to ensure this app extension is avialable only in internal builds, but luckily Apple got back to me with a suggestion to use the EXCLUDED_SOURCE_FILE_NAMES build setting to exclude the app extension.

I am familiar with this build setting, which can be used to impose powerful variations on which source files contribute to a particular built product. For example, it can be used to cause different source files to be compiled for the iOS version of an app than the Mac version. See Dave Delong’s excellent post series on conditional compilation to learn more about this powerful technique.

But I hadn’t considered that the build setting might apply to embedded binaries. After all, Whatever.appex isn’t a “source file.” But lo and behold, adding the app extension name to the excluded source file names for my target, only in the Release build configuration, completely solves the problem. Not only does it avoid the erroneous validation error, it achieves my original goal of excluding the app extension by never copying it to the bundle in the first place. I can remove the custom build phase that selectively removed the app extension, in favor of a build setting that effectively communicates to the Xcode build system exactly what I want it to do.