Chris Campbell

If you use features provided in newer APIs, your program won't work on older version of the OS.

• Using new frameworks and libraries will cause linker errors when the application is double-clicked on computers with older OS versions that don't have those frameworks and libraries

• Using gcc 4.0 will create an executable that can't be run on anything older than 10.3.9

• Calling a method that only exists in certain versions of the OS can cause crashes at runtime when executed on a computer that doesn't have the necessary OS version

The result of the first two examples is an application that won't launch on older OS versions. There is no feedback to the user -- the icon bounces int the dock for a split second, then disappears.

There are workarounds (weak-linking frameworks and testing for their existence at runtime, using gcc 3.3, etc) but they add maintenance costs, testing costs, and support costs. For example: you might not have a computer running Mac OS X 10.0 with which to test your application.

Which is why, sometimes, you just want to require a minimum OS version. Running the application on an older OS would then be flat-out unsupported, so the application would check the OS version when launched and exit (with an appropriate error message for the user) if the OS is too old.

Adding an OS version check to your code still requires that the application is able to be launched on all OS versions, which involves the same workarounds mentioned earlier. With the same maintenance, testing, and support costs.

SystemVersionCheck reduces those headaches. It's a pre-built executable that can run on every version of Mac OS X (all the way back to 10.0). When run, it will check the OS version and present an alert message to the user if the OS is too old to run your application. It's even a Universal Binary. And it's transparent to the user: they just double-click your application.

It's designed to be very easy to integrate into the Xcode build system for your application. You simply copy the pre-built executable into your application's .app folder, let it perform the OS version check for you, and only load your executable if the OS is suitable. You set the minimum OS version with another entry in the Info.plist file.

The LaunchServices framework provides a similar solution by letting you define an LSMinimumSystemVersion key in the Info.plist file, but it only works on Mac OS X 10.2 and 10.4. In addition, the alert message that pops up is very terse and confusing to the user. SystemVersionCheck's error message is more user-friendly, and offers to open Software Update if that's all the user needs to do to upgrade to the required OS version (the user has 10.3 but 10.3.9 is required, for example).

See the original blog entry about SystemVersionCheck (version 1.0) for some sample screenshots.

You can download SystemVersionCheck (version 1.1) below. It includes the pre-compiled SystemVersionCheck executable as well as the source code. There's also a HelloWorld sample application that demonstrates how to use SystemVersionCheck inside an Xcode project.

Everything's released with a BSD-style license. In a nut shell: you have unrestricted use of every file in the download (without any attribution), but I'm not responsible if something goes wrong.

    SystemVersionCheck-1.1.dmg

1. Copy the SystemVersionCheck file into your project directory and rename it "Foo-SystemVersionCheck", where "Foo" is the name of your application's executable. By default, the executable name is the same as the project name, which you can in the "Packaging" collection of build settings in the Get Info window for your target.

2. Add the "Foo-SystemVersionCheck" file to your project, but do not add it to any targets. Uncheck all targets listed in the sheet.

3. Create a new "Copy Files" build phase for your application target. 

4. Choose "Executables" as the destination of the "Copy Files" build phase.

5. Drag the "Foo-SystemVersionCheck" icon into the "Copy Files" build phase. When Xcode builds your application, it will now copy the "Foo-SystemVersionCheck" file into the Contents/MacOS directory of your application.

6. Change the CFBundleExecutable entry of your Info.plist file to

7. Specify the minimum OS version that your application requires by adding another entry to your Info.plist file (if you don't do this step, 10.3.9 is assumed to be the minimum OS version required):

8. Open up the build settings for your application target and select the "Release" build configuration. Add a custom setting named "SYSTEM_VERSION_CHECK_SUFFIX" and set its value to "-SystemVersionCheck"

Xcode can't run or debug your application if it's being launched through SystemVersionCheck. So it's important to only perform step 8 for your Release configuration. That way, you can run and debug your application inside Xcode using the Debug configuration (which will not use SystemVersionCheck), and build the Release configuration when you want to use SystemVersionCheck and send the application out into the world.

The build environment for SystemVersionCheck 1.0 required that the SystemVersionCheck executable be installed in place of your actual executable ("Foo"), and your actual executable be named "Foo.real". This was more difficult to implement in an Xcode build system.

The SystemVersionCheck 1.1 code falls back to the 1.0 behavior (launching "Foo.real") if the CFBundleExecutable entry in the Info.plist file doesn't have the "-SystemVersionCheck" suffix.