If you write scripts of any kind for macOS – shell scripts, AppleScripts, or anything similar – now is the time to join the Catalina beta programme (if you’re not already signed up) if you want those scripts to work with macOS 10.15 when it’s released in a month or so. There are plenty of changes to security and privacy which you’ll need to check out, but my concern in this article is the effect of Catalina’s read-only system volume on paths – a topic which doesn’t seem to have been discussed much, but which may well break many scripts and apps.

In Session 710 of WWDC in June, Apple’s Max Matveev described how the new Catalina volume layout is intended to work, dividing the current contents of what by default is a single volume named Macintosh HD into a writable volume named Macintosh HD - Data and a read-only system volume retaining the original name of Macintosh HD. Instead of there being four volumes in the standard boot container (Preboot, Recovery, VM and Macintosh HD), there are now five.

Connecting these two volumes are bidirectional firmlinks, which effectively mean that the writable directory /usr/local can be accessed and traversed freely on both the writable and read-only volumes, as can /Users.

Reality is always more complex than a slide in a WWDC presentation, and there are a great many more folders/directories which are affected by this new division. I’m hoping that Apple is going to produce a full map of the folder structure of the release version of Catalina for both the developer and system administrator documentation, but I’m not holding my breath.

The best way to illustrate the current state of play is with some examples taken from my own apps, where I’ve had to add new paths so that key files and bundles could be located properly when running in Catalina.

Paths to command tools

The good news is that hard-coded paths to the commonly-used directories containing command tools don’t appear to need any change. Paths such as /usr/sbin/spctl and /usr/bin/csrutil work fine, as should those in libexec directories. The further that you get from those well-worn paths, though, the more likely you are to encounter changes.

For example, although I don’t actually run the MRT app, it’s one of the bundles whose version number is checked by several of my apps like SilentKnight. Before Catalina, you’ll find it in
/System/Library/CoreServices/MRT.app
but with the new volume layout, that becomes
/Library/Apple/System/Library/CoreServices/MRT.app
and that’s a good general rule for anything located in the CoreServices directory and its contents.

Other important directories

My apps lost track of a few directories previously located in /System/Library. At least part of /System/Library/Sandbox/ has become /Library/Apple/Library/Bundles/, for example.

At the root of the old single-volume system is the hidden and protected version database at /.DocumentRevisions-V100. But it isn’t there in Catalina. A little patient searching found it at /System/Volumes/Data/.DocumentRevisions-V100 instead.

If you’ve lost something which is likely to be on the writable system volume now known by default as Macintosh HD - Data, a good path to look in is /System/Volumes/Data/ which appears to be the root of that writable volume, probably the result of one of Apple’s new firmlinks.

When addressing issues in my app Cirrus, I have had to change all its paths for directly accessing iCloud Drive. Previously these have been based on ~/Library/Mobile Documents/com~apple~CloudDocs/ but that has to be changed now to ~/Library/CloudStorage/iCloudDrive.
Moving up a level from the former directory used to open up access to other folders held in iCloud, but there’s no equivalent in ~/Library/CloudStorage in Catalina.

Unfortunately, the illusion created by the Finder is unhelpful for identifying paths to be used in Terminal, scripts or apps: important new paths like /System/Volumes/Data/ aren’t shown there even when you enable the display of hidden items. Indeed, browsing the new folder hierarchy in the Finder looks very clean and simple, but will only cause endless confusion. We do need a good roadmap.