Upgrading a System Preference pane

The System Preferences application provides a convenient way to install a preference pane. Double-clicking the preference pane will prompt the user if he wants to install it for the current user only or for all users of the computer. Then System Preferences will copy the preference pane to ~/Library/PreferencePanes or /Library/PreferencePanes according to what was chosen asking for administrator password if necessary. Finally the preference pane will be loaded and presented to the user.

Now, let's see what happens when a preference pane is upgraded. Again, System Preferences is smart: it is able to detect if an older version of the same preference pane is installed and proposes to replace it [1]. Everything seems alright, but it is actually not! Things are more complicated if the preference pane to upgrade has already been loaded. That is, if the user already clicked the preference pane.

Indeed, preference panes are just a special kind of bundle which is loaded into System Preferences with the -(BOOL)[NSBundle load] method (cf. -(BOOL)[NSPrefPaneBundle instantiatePrefPaneObject] method of the PreferencePanes framework). The problem is that on Tiger, a NSBundle can not be unloaded. So when upgrading an opened preference pane, the old code is not unloaded and as a consequence the new code is not loaded. This is because System Preferences calls the -(BOOL)[NSBundle load] method which returns YES, meaning that the bundle was successfully loaded or that the code has already been loaded. In the case of an already opened preference pane, that's how the result of the load method should have been interpreted. Unfortunately, it is interpreted as if the bundle was successfully loaded and System Preferences thinks it has loaded the new bundle, but it has not.

This is very problematic because at this point, the resources (nib files, pictures etc.) of the new bundle have already been copied. So we have the old code which is accessing the new resources. I let you imagine the numerous problems this situation can cause. At best, exceptions will raise and your preference pane will be half working. At worst, your preference pane will simply crash.

So, how do we fix this problem?

First, the preference pane must detect itself when it's upgrading over an older already loaded version as System Preferences does not detect it [2]. This must be done as early as possible, i.e. at the very beginning of the - (id)initWithBundle:(NSBundle *) bundle method. It is possible to detect this situation with the help of the version of your NSPreferencePane subclass. See my detection snippet to understand how detection works.
Once this is detected, we must properly reload the new preference pane. This must be achieved by quitting System Preferences and relaunching System Preferences. This is the not that elegant solution to unload the old preference pane. The elegant solution would be to unload the bundle. This is left as an exercise to the Apple engineers for a future version of System Preferences.

Relaunching System Preferences and selecting the preference pane is quite tricky. A second executable must be responsible for relaunching the System Preferences application. Also, it is nicer for the user if the preference pane he just upgraded is automatically selected. Automatic selection of the pref pane is achieved through Apple Script. Please refer to my reload snippet for implementation details. Note that once you have compiled the reload executable, you have to place it inside the resources directory of your preference pane. Do not place it inside the executable directory (Contents/MacOS) if you do not want to see the reload application popping up in the Dock.

With this reload code in place, if the user ever happens to upgrade a preference pane while the older one was loaded, he will experience a System Preferences flicker as it will quit and reopen right away. While this might be surprising to him, this is still better than a half working preference pane or a crash.

If anything is unclear, just say it so in the comments and I will try to elaborate. If everything is clear, just pick up my code snippets and implement them in your preference pane as soon as possible ;-)

---

1. System Preferences uses the CFBundleGetVersionNumber function to retrieve the version numbers of the new and old bundles as an UInt32 in order to compare them. The documentation says If the bundle’s version number is a number, it is interpreted as the unsigned long integer format defined by the vers resource on Mac OS 9. What every developer understands is that if your Info.plist CFBundleVersion key represents a number (e.g. "519"), the value returned by CFBundleGetVersionNumber will be 519. This is not what actually happens. If you want CFBundleGetVersionNumber to return 519, you have to add an undocumented key in your Info.plist file: CFBundleNumericVersion. Make sure you define it as <integer>519</integer> and not <string>519</string>.↩

2. Note that on Leopard, this situation is actually detected and a dialog is presented to the user telling he must quit System Preferences and then open it again. Unfortunately, no automatic action is taken to circumvent this annoying behavior. System Preferences could restart itself or unload the bundle (this is possible since Leopard) but as of Mac OS X 10.5.2, none of this action is performed.↩