Inline AppleScript Documentation

While perusing Xcode’s AppleScript scripting dictionary, I was surprised to discover a rather robust “example code” section included right there among the usually spartan reference of the app’s scriptable entities:

Screenshot of Xcode's scripting dictionary, including a section with example script code for the 'build' command

Curious to learn more, I used a relatively little-known trick for examining the raw source code of a scripting dictionary. Simply click and drag from Script Editor’s document proxy icon, into a text editor such as TextEdit, Xcode, or BBEdit:

Screenshot of Script Editor window for a scripting dictionary, with annotations to show where the document proxy icon is

This trick is especially handy because even if the app in question doesn’t have a standard scripting definition (.sdef) file representing its interface, Script Editor will generate one dynamically for you. It’s a quick-and-dirty way to learn how specific outcomes are achieved, and how you might incorporate similar features in your own app’s scripting definition file. In this case, I discovered a new (to me) “documentation” element in the file:

Screenshot of source code reflecting the example script inline documentation pictured above

I was not aware of the feature until a few weeks ago, but apparently it’s been there since at least Mac OS 10.5. Script Debugger supports it, too! You can read more about the “documentation” element by invoking “man 5 sdef” from the Terminal:

When an element needs more exposition than a simple ‘description’ attribute can provide, use a documentation element. A documentation element may contain any number of html elements, which contain text that will be displayed at that point in the dictionary.

Given the sad state of support for AppleScript by Apple, and the continued low level of adoption by 3rd-party developers, a feature like this will probably never be widely used or celebrated. But at least in FastScripts 3.2.4, which I just released this morning, I’m now taking advantage of it:

Screenshot showing FastScripts 'search text' command with an inline documentation block

If you’re among the few remaining Mac developers who is investing time and effort into your AppleScript scripting definitions, hopefully you’ll find this feature useful!

Opting Out of TextKit 2 in NSTextView

Starting in macOS 13 Ventura, Apple is automatically opting-in most NSTextView instances to use TextKit 2, a modern replacement for the traditional NSLayoutManager based text system that has been part of Mac OS X since its debut.

This change may bring a variety of surprises, so it’s important to test carefully if you use NSTextView. Somewhat unintuitively, you are more likely to be affected by the changes if you do little customization of the default NSTextView behavior.

Apple explained the new opt-in behavior and some of the consequences in the 2022 WWDC session titled “What’s New in TextKit and text views”. They also explain that the decision to use TextKit 2 can be explicitly opted out of:

When you explicitly call an NSLayoutManager API, the text view replaces its NSTextLayoutManager with an NSLayoutManager and reconfigures itself to use TextKit 1.

Perhaps the biggest risk for malfunction lies in scenarios where some significant customization is expected to work, but not in a way that affects the text view’s decision to carry on using TextKit 2. One such example is when it comes to customizing the drawing of the insertion point cursor. Since “the dawn of time” Apple has offered an overridable method on NSTextView:

open func drawInsertionPoint(in rect: NSRect, color: NSColor, turnedOn flag: Bool)

A custom NSTextView subclass that thinks it can do better than Apple’s default text-colored vertical bar can override the method to impose its own dubious design choices:

Screenshot of text editor text with an insertion point colored red and green

By default, starting in macOS 13 Ventura, the above customization will fail, because it is evidently not supported by TextKit 2. The simple workaround, for the time being anyway, is to force your text view to use TextKit 1. As explained in the WWDC excerpt above, this is as simple as asking it once for its layout manager, which will cause it to rebuild its entire text architecture to suit the TextKit 1 way of functioning:

let _ = myTextView.layoutManager

I’ve filed FB11771261 with Apple, requesting that the functionality either be restored, or the method in question be overtly documented as non-functioning.

Update: The insertion point behavior described here is among many other bugs documented on Marcin Krzyzanowski’s STTextView project on GitHub. Looks like a good resource for folks who are curious about possible issues, and possibly a good alternative to NSTextView until/unless Apple fixes NSTextView to be more functional in TextKit 2 mode. Thanks to Greg Pierce for the link.

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 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 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() {

    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:

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:


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.