Running the iPad Simulator with the PhoneGap Command-line Tools

The PhoneGap command-line tools are very nicely done. Once you have installed PhoneGap, creating a new project is as simple as:

/path/to/phonegap/lib/ios/bin/create /path/to/myproject com.example.myproject myproject

This generates a fully functional PhoneGap application in the directory you specified. To run the application you just need to install ios-sim, the command-line launcher for the iOS simulator. Assuming you already use Homebrew:

brew install ios-sim

Now you can run your new project in the iOS simulator.

cd /path/to/myproject
cordova/run

This will build the application and launch it in the iPhone simulator. You don’t even need to launch XCode!

What if you want to simulate an iPad application?

The cordova/run script is just a shell script that launches ios-sim. Looking at the script you’ll see there’s no obvious way to launch the iPad simulator instead of the iPhone simulator, short of modifying the script to pass the --family argument to ios-sim. Modifying the run script might make for a bumpier upgrade down the road, so I’d rather not.

If you explore the cordova directory some more, you’ll find the cordova/emulate script. It is mostly the same as the cordova/run script, but it passes the --family argument to ios-sim.

The emulate script takes device family as an argument, but it is the second argument to the script. The first argument is the path to the built project. You can launching the iPad simulator with the emulate script like this:

cordova/emulate build/myproject.app ipad

The emulate script also accepts DEVICE_FAMILY as an environment variable. So if you don’t want to specify the path to your project every time (since the script will find the project automatically), you could launch the iPad simulator like this:

env DEVICE_FAMILY=ipad cordova/emulate

If you’ll be testing with the iPad simulator exclusively, you can just set the DEVICE_FAMILY variable in your .bash_profile, and then whenever you run cordova/emulate it will launch the iPad simulator.

There is also nothing preventing you from adding another script to the cordova directory that will launch the iPad emulator. For example, you might add cordova/emulate-ipad to the cordova directory:

#!/bin/bash
CORDOVA_PATH=$( cd "$( dirname "$0" )" && pwd -P)
env DEVICE_FAMILY=ipad $CORDOVA_PATH/emulate

So why do both the run and emulate scripts exist? I’m not sure!