I love watching really skilled magicians. Even though you know that they’ll distract your attention away from their sleight of hand, catching them transferring the card they’re just about to trick you with is almost impossible. So with Apple: over the last couple of years, rumours about Apple Silicon grew steadily stronger and more credible, and all the time the most giveaway clue was right under our noses, in plain sight. But none of us spotted it.

The clue was in the command tool lipo, something which had been quietly fading away since the last processor transition and its Universal Binaries. By High Sierra, it had withered to the point where anyone wanting real use from it preferred to work with the version shipped in Xcode. What none of us noticed was that two years ago Mojave brought a rejuvenated and highly capable update to lipo, which Apple even documented fully in a long and explicit man page dated 31 August 2018.

With the wisdom of hindsight, there couldn’t really have been a clearer sign that Apple Silicon and Universal Binaries were just around the corner. Yet we all missed it.

The tool’s name lipo refers not to the last transition to Intel, but way back to the introduction of the PowerPC, when Universal Apps were named Fat, usage which is now deemed inappropriate. Liposuction is of course the term for the removal of local fat deposits in cosmetic surgery, and conveniently retains the original allusion without compromising inclusivity. Since the passing of the last generation of Universal Binaries nine years ago, lipo has seen limited use with the 32-bit and 64-bit transition, and has been much more used when building apps for iOS.

It’s not as if lipo is one of those rambling portmanteau tools which does everything provided you choose the right verb, options and day of the week. It creates Universal Binaries, divides them up again, and tells you all about them. It’s well-documented, and perhaps an example of what a good command tool should be.

What’s a little bit disconcerting here is the apparent lack of support for similar features in the Big Sur SDK. There has long been a wealth of support for apps to work with bundles, structured folders containing (optionally) executable code. System calls are available to discover almost anything you might want to know about a bundle, including of course the architectures which its executable code supports. But there doesn’t appear to be anything equivalent for Mach-O files.

Neither does Apple have any extant documentation which details the Mach-O file format, such as the opening bytes which are the ‘Magic’ header of a Universal Binary, or the subsequent data structures which set out which architectures are supported by a Universal Binary. There are some copies of an old reference, the Mac OS X ABI Mach-O File Format Reference, which was last updated eleven years ago, and seems to have been removed from Apple’s archives more than four years ago. Other than that, the closest we’ve got from Apple in the way of documentation are C header files.

That reference to the Mach-O format is one of the saddest pieces of Apple’s documentation that I have read. The first entry in its Revision History, from 2002, reads “This was a preliminary draft distributed with the April 2002 Developer Tools CD.” For those not old enough to remember, Apple used to distribute a free monthly CD to all its developers, containing its wealth of documentation for Mac OS.

The next entry, from exactly a month later, “was a preliminary draft distributed with the WWDC 2002 developer tools”. This “incorporated many corrections from developer review”, and responded to “popular demand” by adding some usage scenarios and a whole new chapter. Two months later, another revision was released following “more developer feedback”. And so the revision notes go on, until the last on 4 February 2009, which signs off with the terse “made minor changes”.

We may have missed Apple’s sleight of hand in the changes it made to lipo, but it’s only too obvious what has happened with documentation over the last decade. Want to know about one of the most fundamental file formats in macOS? Try the header files, or third-party documentation, because Apple has magicked much of its old documentation away.