Mac Plugin Developers – You Should Be Using Native Paths!

TL;DR version: if your plugin runs on OS X, you you should be setting the capability “XPLM_USE_NATIVE_PATHS” to 1, like this:

XPLMEnableFeature("XPLM_USE_NATIVE_PATHS",1);

This sets your plugin to use Posix-style file paths on OS X.

I am going through X-Plane looking for APIs that Apple has deprecated and replacing them.  Aliases to custom scenery on other hard drives stopped working in Yosemite because we were using the Alias Manager to resolve the aliases, and the API is deprecated; in Yosemite Apple actually made it stop working.  So now I’m looking to see what other deprecation problems we might be sitting on.*

One thing I noticed in my search is that kCFURLHFSPathStyle is marked deprecated in OS X 10.9.  I don’t know when it will actually stop working, but we’re not supposed to be using it.

And here’s the thing: the only use case we have for it is incredibly silly: if your plugin doesn’t tell us that you can support Posix paths, we’ll convert to HFS paths so that you can then (in your plugin) convert back to Posix paths.  In this use case, both the XPLM and your plugin are using a deprecated API to temporarily convert a file path to a silly format, and then back again.

Why Are Unix Paths Opt-In

The original XPLM API dates back to X-Plane 6 and ran on the classic Mac OS under the HFS file system.  In this environment, all file system paths were HFS paths, e.g. Volume:directory:then:filename.

For a while, X-Plane could run under OS 9 and OS X using the Carbon APIs and CFM file formats; in this environment, the SDK continued to provide HFS file paths to all plugins at all times.

When we introduced the ability for plugins to use the underlying Posix file paths (which makes life much easier for the plugin developer, since Posix paths are what the OS really wants) we had to make it opt-in; a plugin tells us it wants this new thing by setting a new feature.  Plugins that don’t opt in are assumed to be old and are assumed to expect the old convention.

HFS Paths Are Now Obsolete

Here’s the thing: at this point Apple has changed ABIs twice and changed CPU architectures; they have also changed executable formats.  Simply put, no plugin code that runs in X-Plane 9 or 10 can possibly be using HFS file paths directly, because all running plugins are only capable of running on OS X.

But because it was possible to write a plugin that worked both ways (by opting in only when X-Plane was ready) there are still plugins that will run in HFS mode if and only if X-Plane can’t support Posix (e.g. if they are running on X-Plane 9.)

So in order to fully dispose of HFS paths, we need your plugin to start opting in to Posix paths.  Doing so is really easy – it generally involves adding the one line above and deleting your HFS code (which is fun).

When Can You Use Posix Paths

Posix paths in the XPLM are available to plugins starting with X-Plane 10.0.  If your plugin requires X-Plane 10 or the XPLM 2.1, posix paths are always available.

The XPLMEnableFeature APIs are available to plugins with the XPLM API 2.0, starting with X-Plane 9.0.  So if your plugin only runs on X-Plane 9 and 10, you can attempt to set this (because the API is always available).

* Because our minimum OS is OS X 10.6 for X-Plane 10, X-Code normally doesn’t tell us about most deprecations.  To find all of the issues, I temporarily set our minimum to OS X 10.10 just to see the warning list.

About Ben Supnik

Ben is a software engineer who works on X-Plane; he spends most of his days drinking coffee and swearing at the computer -- sometimes at the same time.

View all posts by Ben Supnik →