This version of the documentation is outdated! Click here for the latest released version.

OS X Platform Guide

This guide shows how to set up your SDK development environment to deploy Cordova apps for OS X computers. See the following for more detailed platform-specific information:

The command-line tools above refer to versions prior to Cordova 3.0. See The Command-Line Interface for information about the current interface.

Requirements and Support

Apple® tools required to build OS X applications run only on the OS X operating system on Intel-based Macs. Xcode® 6.0 (the minimum required version) runs only on OS X version 10.9 (Mavericks) or greater, and includes the OS X SDK (Software Development Kit). To submit apps to the Apple App Store℠ requires the latest versions of the Apple tools.

You can test all of the Cordova features using the XCode or any other IDE such as JetBrain's AppCode, but you need to use XCode to sign before submitting to the App Store. To sign the apps, you must also be a member of Apple's OS X Developer Program.

Install the SDK

There are two ways to download Xcode:

from the App Store, available by searching for "Xcode" in the App Store application.
from Apple Developer Downloads, which requires registration as an Apple Developer.

Once Xcode is installed, several command-line tools need to be enabled for Cordova to run. From the Xcode menu, select Preferences, then the Downloads tab. From the Components panel, press the Install button next to the Command Line Tools listing.

Create a New Project

Use the cordova utility to set up a new project, as described in The Cordova The Command-Line Interface. For example, in a source-code directory:

$ cordova create hello com.example.hello "HelloWorld"
$ cd hello
$ cordova platform add osx
$ cordova prepare              # or "cordova build"

Run the app

To run the app on your desktop:

$ cordova run

And you should see a bordered window with the example app:

You can also use cordova run --help to see additional build and run options.

Open a Project in the SDK

Once osx platform is added to your project, you can open it from within Xcode. Double-click to open the hello/platforms/osx/HelloWorld.xcodeproj file. The screen should look like this:

TIP You can also use the open command to open the XCode project directly from the command line:
$ open platforms/osx/HelloWorld.xcodeproj

Common Problems

Deprecation Warnings: When an application programming interface (API) is changed or replaced by another API, it is marked as deprecated. The API still works in the near term, but is eventually removed. Some of these deprecated interfaces are reflected in Apache Cordova, and Xcode issues warnings about them when you build and deploy an application.

Missing Headers: Compilation errors relating to missing headers result from problems with the build location, and can be fixed via Xcode preferences:

Select Xcode → Preferences → Locations.
In the Derived Data section, press the Advanced button and select Unique as the Build Location as shown here:

This is the default setting for a new Xcode install, but it may be set differently following an upgrade from an older version of Xcode.

For further information, consult Apple's documentation:

Member Center home page provides links to several OS X technical resources including technical resources, the provisioning portal, distribution guides and community forums.
Xcode User Guide
The xcode-select command, which helps specify the correct version of Xcode if more than one is installed.

(Mac®, OS X®, Apple®, Xcode®, App Store℠, iPad®, iPhone®, iPod® and Finder® are Trademarks of Apple Inc.)