All posts by Daniel Jalkut

Discoverable Key Commands

Debugging, iOS

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

Tips, Xcode, ,

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

Tips, Xcode

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

Tips, Xcode

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.

Xcode 11.4 Beta 1: Couldn’t Load Spec With Identifier

Debugging, Xcode

When Apple updates Xcode, they usually add a slew of deprecations and warnings that might turn your otherwise warning-free project into a virtual hailstorm of yellow warning triangles.

One of the warnings that popped up for me with the recent Xcode 11.4 Beta 1 release, is this inscrutable little gem:

Screenshot of a warning from Xcode. Text in post content below.

Hmm, “Couldn’t load spec with identifier ‘com.apple.compilers.gcc.4_0’ in domain ‘macosx'”, what does it mean? I know this is an old project, and has a lot of history. Maybe I have some old GCC setting that needs to be zapped? I searched the build settings for “gcc” but nothing came up at all, and certainly nothing with the specificity of “gcc.4_0”.

I was perplexed. Rather than fish around any longer in Xcode, I headed to Terminal for some brute force searching:

% cd /path/to/My.xcodeproj
% grep -r gcc *
project.pbxproj:			compilerSpec = com.apple.compilers.gcc.4_0;
...

Aha! Let’s open that file up and see what the context is for these:

65F44C4917D681F3002A02AA /* PBXBuildRule */ = {
	isa = PBXBuildRule;
	compilerSpec = com.apple.compilers.gcc.4_0;
	fileType = sourcecode.c;
	inputFiles = (
	);
	isEditable = 1;
	outputFiles = (
	);
};

Build rules? We don’t need no steekin’ build rules! I have rarely used a custom build rule, so never think to search in that tab when examining a target’s properites. Particularly not when I’m coping with new Xcode warnings. Sure enough, I took a look in the Build Rules tab and found these:

Screenshot of Xcode's build rules editor, listing two custom rules, one for C file and one for Assembly files, specifying an

These custom build rules must have come from a time when the target included C and Assembly files. These days, it only contains Objective-C files, so I feel extra safe in deleting these. After doing so, the new warnings are gone.

Bitwise Manipulation

Hacking, Tips

Since as long as I have been a programmer, bitwise operators have been an important but sometimes daunting part of my work. These are the programming tools with which you take a numerical value, let’s say seven, and manipulate it at the level of the bits that make up its binary representation. You can display the binary representation of any value in lldb, the standard Apple debugger, using “p/t”:

(lldb) p/t 7
(int) $0 = 0b00000000000000000000000000000111

One of the most common use cases for bitbwise manipulation is to squeeze lots of information into a small amount of computer memory. For example, a 32-bit integer can hold 32 distinct boolean values:

(lldb) p/t -1
(int) $1 = 0b11111111111111111111111111111111

Yep! The signed, 32-bit value for -1 is often represented as “all the bits are on!” But we could also consider this bit field to be a representation of the enabled/disabled states for 32 distinct preferences in our app. In which case, it’s common to declare numerical constants in code that make it easy to know which bit stands for what.

In C, this is often done by declaring an enumeration where each element is a different power of two, which is by definition the numeric value of each of the bits in any binary number. Apple’s own Objective-C headers use this all over the place. For example, CALayer declares a mask type that allows the four corners of a rectangle to be identified as 1, 2, 4, or 8:

typedef NS_OPTIONS (NSUInteger, CACornerMask)
{
  kCALayerMinXMinYCorner = 1U << 0,
  kCALayerMaxXMinYCorner = 1U << 1,
  kCALayerMinXMaxYCorner = 1U << 2,
  kCALayerMaxXMaxYCorner = 1U << 3,
};

To work with these types of values, you often need to use bitwise operators to set, test, unset, or toggle particular elements in a value. Working with bitwise values can be pretty brain-bending, but I recommend that everybody learn about and understand why and how each of the most common bitwise operators work. I won’t delve too deep here, but for example if you wanted to “add” the value 8, for kCALayerMaxXMaxYCorner, to an existing mask of value 7, representing all three other corners, this is what it would look like at a bitwise level:

(lldb) p/t 7
(int) $2 = 0b00000000000000000000000000000111
(lldb) p/t 8
(int) $3 = 0b00000000000000000000000000001000
(lldb) p/t 7 | 8
(int) $4 = 0b00000000000000000000000000001111

A bitwise operator acts on each bit of a value independently, potentially transforming it into a new value. The bitwise OR operator, which is “|” in C, did this above by looking at every bit in the value for 7, and every bit in the value for 8, and if either one had a value of 1, the bit in the resulting value is also set to 1. You can see this visually by playing with the operators in lldb as I’ve demonstrated above.

Even once you fully understand bitwise operators, they’re pretty annoying to work with on a day-to-day basis. That’s why in C, I’ve used these macros for years that simplify the task of performing these common tasks. I’ll leave it as an exercise to figure out why these all work the way they do:

// Basic bitwise operators for our convenience
#define RS_SET_BIT(mask, addedBit) (mask |= addedBit)
#define RS_TEST_BIT(mask, testBit) ((mask & testBit) != 0)
#define RS_CLEAR_BIT(mask, removedBit) (mask &= ~(removedBit))
#define RS_TOGGLE_BIT(mask, toggledBit) (mask ^= toggledBit)

For example, if you were maintaining a list of corner masks, and wanted to remove the kCALayerMinXMaxYCorner value, you just:

CACornerMask existingCornerMask = ... whatever ...
RS_CLEAR_BIT(existingCornerMask, kCALayerMinXMaxYCorner);

It’s more readable, easier to remember, and most importantly easier to get right than always coming up with the exact combination of bitwise operations to remove a value from a binary bitmask.

What about Swift? These macros are based on C’s macro preprocessor, and Swift doesn’t support such a thing. The good news is Swift handles bitmasks in a fundamentally better way, by promoting them to a first-class type called OptionSet. If you’re lucky enough to be working in Swift, you can achieve the same thing as above with:

var existingCornerMask: CACornerMask = ... whatever ... 
existingCornerMask.remove(.layerMinXMaxYCorner)

Bitwise manipulation is important in most every field of computer programming, and as I said, you should really understand it. But as I also said, once you’ve understood it, you should probably strive to never use bitwise operators again. At least not directly.

Casting Objective-C Message Sends

Cocoa, iOS, Links, ObjC, OS X, Xcode

Mike Ash shares interesting news that the latest Xcode SDKs include a change to the function prototype of Objective-C’s msgSend family of functions. Where objc_msgSend was previously defined in terms of the couple of parameters it usually takes, and with the return type that it sometimes has, it is now declared as taking no parameters and returning no value:

OBJC_EXPORT void
objc_msgSend(void /* id self, SEL op, ... */ )

In practial terms, this will have an impact if you are still using direct objc_msgSend calls anywhere in your code. For example, imagine you have a “transformer” class that is capable of performing a variety of text manipulations on strings. You might have some code that derives a “SEL” programmatically and then messages the transformer to perform the action. Here’s a contrived example:

SEL tSEL = @selector(uppercaseString:);
NSString* upString = objc_msgSend(transformer, tSEL, lowString);

While that would have worked previously (apart from some ARC warnings), on the latest SDKs you’ll get a compile-time error on the objc_msgSend call:

Too many arguments to function call, expected 0, have 3

Obviously, you need to pass the arguments or the invocation will be useless, but how do you do it? Mike’s post has the advice:

Because it still has a function type, you can still cast it to a function pointer of the appropriate type and invoke it that way. This will work correctly as long as you get the types right.

As long as you get the types right … so, how does one do that? Mike includes an example of inline-casting objc_msgSend, but if you need to do this more than once in your code, I think a more elegant way of casting objc_msgSend is by declaring a global variable as a function pointer with the desired types:

#import "objc/message.h"

NSString* (*PerformWithStringReturningString)(id, SEL, NSString*) = (NSString* (*)(id, SEL, NSString*)) objc_msgSend;

Now when you want to invoke “objc_msgSend” on an object that you know accepts and returns a string type, you can do so like this:

NSString* upString = PerformWithStringReturningString(transformer, tSEL, lowString);

No compiler warnings, ARC knows just what to do with all the types, and you have a very clear understanding of what objc_msgSend is expected to do with this particular invocation.

Notarization Provider IDs

Apple, Mac, Xcode

Update: 3 November, 2019: As of Xcode 11 the altool command features a new parameter, “–list-providers” which makes it much easier to obtain the provider ID described below. See the updated documentation for more information.

With the release of macOS 10.15 fast-approaching, more and more Mac developers will be scurrying to ensure their apps are notarized. This is the process by which binary applications are submitted to Apple for cryptographic seal-of-approval indicating that the app meets minimum requirements for safety, and shows no obvious signs of being malware.

Apple offers substantial documentation about notarizing your apps. Many developers will find that Xcode automatically notarizes the app as part of the built-in process for archiving an app for release. For those of us with existing, automated command-line build & release processes, there is a separate guide just for us:

Customizing the Notarization Workflow

The steps for automating notarization involve running the “altool” command from Terminal. Everything in the guide linked above should work perfectly unless you’re a member of more than one development team. If you have more than one team associated with your Apple ID, the back-end at Apple doesn’t know which one it should notarize on behalf of. You’ll see an error message like this:

Error: Your Apple ID account is attached to other iTunes providers. You will need to specify which provider you intend to submit content to by using the -itc_provider command. Please contact us if you have questions or need help. (1627)

Here’s where things get fun: what the heck is your ITC provider ID? It’s not listed anywhere obvious on the Apple developer site or in Xcode, and can’t be obtained from the very tool that is asking for it. I came across a message from the ever-helpful Quinn in the Apple Developer Forums. It details a method for locating the provider ID by running a command-line tool, iTMSTransporter, from deep within Apple’s Application Loader app.

Application Loader has since been eliminated from Xcode 11, so if you’re running with modern tools, you’ll be hard pressed to find it. Fear not, the binary is preserved deep within the Xcode app bundle itself:

% xcrun -f iTMSTransporter
/Users/daniel/Applications/Xcode/Xcode.app/Contents/Developer/usr/bin/iTMSTransporter

All that said, here is a surefire list of steps for obtaining your ITC Provider ID, or as it’s described in the altool man page, your ASC Provider Shortcode.

  1. Create a new App-Specific Password from your Apple ID management page.
  2. From Terminal, invoke iTMSTransporter with the following options: 
    xcrun iTMSTransporter -m provider -u <yourAppleID> -p <yourAppSpecificPassword>
  3. At your discretion, revoke the App-Specific Password you created for this process.

NOTE: These instructions apply if you are using Xcode 11. If you’re still using Xcode 10, you’ll need to dig up the iTMSTransporter binary from within Application Loader.app. Instead of “xcrun iTMSTransporter” above, it will be something like /path/to/Application Loader.app/Contents/itms/bin/iTMSTransporter.

If all goes well, you should see a list of your Apple development teams, including the Long Name and Short Name. The Short Name is what you need to pass whenever altool requires an ITC or ASC Provider ID.

Cryptic App Store Upload Error

Apple, iOS

I recently had cause to take another look at Swish, my iOS app for generating white noise and static visuals. OK, the reason was Apple sending me an email notification that, because it has been over three years since I last updated the app, they were going to remove it from the App Store in 30 days.

I had previously had it in mind to ship an update that supports the newest screen sizes for devices such as iPhone X, but I sort of lost track of that. This was a good motivation to get an other update out so I made a few quick improvements and set about uploading a build to Apple to “blow out the cobwebs” and see if I was missing anything else.

Upon uploading the app, I was met with this surprising error:

Screenshot of an error from Xcode indicating that \

The Info.plist indicates an iOS app, but submitting a pkg or mpkg.

Hmm. That’s weird. I’m not submitting a pkg or mpkg. At least, I don’t think I am. My Info.plist should indicate an iOS app, because Swish is an iOS app.

I racked my brain trying to figure out what was going on here, and finally ended up filing a bug to Apple. Luckily, they got back to me within a day or two with this unexpected advice:

Please remove the LSMinimumSystemVersion from the Info.plist.

I had added the “minimum system version” to the Info.plist because I decided this update would support only iOS 11 and higher. I didn’t understand why that value would have anything to do with my issue, but I dutifully followed their advice, submitted the app, and … it worked perfectly!

Doing a little research, I discovered that LSMinimumSystemVersion is for macOS only, and that the iOS counterpart is simply called MinimumOSVersion. But, here’s the catch: the Xcode build process generates and inserts that MinimumOSVersion plist entry automatically, based on the deployment target for your app.

I hope this helps some frustrated Mac developer who is simply following old habits, and makes the mistake of adding LSMinimumSystemVersion to their iOS app’s Info.plist. Remove it, and your App Store uploads should work again!

Toggle System Grayscale Mode

Accessibility, Automation, Hacking

A colleague recently asked whether it was possible to connect a custom keyboard shortcut to the system-wide “Use grayscale” setting in the macOS Voiceover system preferences:

Screenshot of macOS preference options for accessibility options inlcuding 'Use grayscale'

I could not find any easy way to do this, and searching the web for solutions revealed that most people are addressing this want by using GUI scripting to automate literally opening System Preferences and clicking the pertinent checkbox.

I thought there must be a way to do this in a more streamlined fashion. Couldn’t the option be automated via AppleScript or something? After some brief research, my conclusion was “no.”

At this point I put on my “hacker hat” and proceeded to analyze the System Preferences code that handles the configuration. It’s a binary in /System/Library/PreferencePanes, and the following Terminal command got me on the right path:

cd /System/Library/PreferencePanes/UniversalAccessPref.prefPane/Contents/MacOS/
nm UniversalAccessPref | grep gray

In short, that means “dump all the symbols (nm) from the VoiceOver preference pane, and search them (grep) for the word ‘gray'”. Here’s what it spits out:

0000000000057210 S _OBJC_IVAR_$_UAPDisplayViewController._grayscaleCheckbox
                 U _UAGrayscaleIsEnabled
                 U _UAGrayscaleKey
                 U _UAGrayscaleSetEnabled

These look to me like exactly the names of functions that the preference pane is calling in order to check the current state, and to set the updated state, of the “Use grayscale” checkbox. The capital “U” stands for “Unimplemented.” I.e. it expects to find these symbols, function names in this case, in another library. But which library?

otool -L UniversalAccessPref

The “otool -L” command will dump all the libraries that the preference pane “links to,” meaning the libraries it expects to load functions or data from. There’s a huge list of frameworks in the output, but the most interesting one to me is:

/System/Library/PrivateFrameworks/UniversalAccess.framework/Versions/A/UniversalAccess

The framework name “UniversalAccess” correlates strongly with the “UA” prefix on the pertinent function names we dug up above. Great, so how do we call these? They’re private system functions which means you should not rely on them for production code, but for a quick hack to make toggling grayscale easier? It’s a reasonable risk in my opinion. Here’s a simple C program that takes advantage of the private methods to simply toggle grayscale mode on or off, depending on the current setting.

If you wanted to assign this functionality to a keystroke, as originally suggested, the easiest way in my opinion is to use an app like my own FastScripts. You could drop the compiled binary above into your ~/Library/Scripts folder, and run it directly from FastScripts. Or, if you don’t want to fuss around with compiling a C program, just copy and paste this AppleScript:

-- Line up a Python script for dynamically loading 
-- the private framework  and invoking the required
-- private methods to get current grayscale mode
-- and set it to the opposite value.
set toggleGrayScript to "python -c 'from ctypes import cdll
lib = cdll.LoadLibrary(\"/System/Library/PrivateFrameworks/UniversalAccess.framework/UniversalAccess\")
lib.UAGrayscaleSetEnabled(lib.UAGrayscaleIsEnabled() == 0)
'"
do shell script toggleGrayScript

This script takes advantage of Python’s ability to dynamically load an arbitrary shared library and invoke its exported functions. I wondered if I might be able to use AppleScript’s own “use framework” functionality but I couldn’t quite figure it out.

Hopefully this has been instructive generally for folks who are interested in hacking at system frameworks, and specifically for folks who were looking for an AppleScript for quickly toggling macOS grayscale mode on and off.