Updated: You’ll need to follow these instructions to get this to work for Xcode 4.3.
While Apple doesn’t provide an “official” way to launch an app in the iOS Simulator from the command line, there’s a few private tricks we can employ. First, the iOS Simulator app itself is located in:
But running that will only bring up the simulator in the last state it was in. How do we install an application in there and then run it automatically like Xcode does?
The trick is in the private
iPhoneSimulatorRemoteClient.framework. Now before
you freak out, don’t worry! This isn’t something you compile your app against
and submit to the store. This is a framework that we can use on our local
machines to control the simulator just like Xcode does. The best part is, all
the work of hooking into it has been done for us!
There are two command line utilities I’ve seen that do this best. I used to use iphonesim and it works great. But I recently switched to WaxSim since it also records video of the simulator in motion. They both are functionally equivalent and small enough to understand. It’s your call, but I recommend the later.1
First, we need to pull down the WaxSim source and install it. Run the following:
git clone https://github.com/square/WaxSim cd WaxSim xcodebuild install DSTROOT=/
Now, you have the
waxsim binary in
/usr/local/bin which should already be
on your path. You can now invoke your application in the simulator like this:
waxsim [application path]
So, where is your application path? That depends on how you build it! First, we’ll need to do a quick walkthrough about building Xcode projects from the command line.
cd into your iOS application’s project directory (the one with the Xcode
project file). Then, invoke the
xcodebuild command like so:
xcodebuild -sdk iphonesimulator5.0 \ -arch i386 \ install DSTROOT=/tmp/MyApp
For most projects, this command will work just fine. However, if you have an
explicit workspace set up, you’ll need to use
man xcodebuild to learn how to
xcodebuild binary to interpret your setup. There’s a lot of good
stuff in there about how to specify whether to build for the simulator or
DSTROOT environment variable on the command above is the most important
DSTROOT is used by Xcode when run with the “install” build action to
figure out where to put the results. We’re specifying
so that we know where the resulting application bundle will be to hand in to
xcodebuild command completes, you should now have an *.app bundle in
/tmp/MyApp/Applications/[YourAppName].app. Of course, subtitute your own
application name in the path. Invoke
waxsim and you’re up and running:
This runs the iPhone simulator with the latest SDK that
waxsim is aware of.
waxsim -h to find out other options like running the iPad simulator or
other using other available SDKs.
You can also record a low resolution video of the simulator like so
waxsim -v myvideo.mov /tmp/MyApp/Applications/[YourAppName].app
And now you’ll have
myvideo.mov in the current directory. It’s a pretty low
res and stuttery video, probably not something you’d use for a promotional
demo, but it’s a nice feature if you need to review results of automated
So, for completeness sake, here’s a shell script that you can modify to build and run your application:
#!/bin/bash # Tell bash to abort the script if any error happens set -e APPNAME=MyApp DSTROOT=/tmp/MyApp xcodebuild -sdk iphonesimulator5.0 \ -arch i386 \ install DSTROOT="$DSTROOT" waxsim "$DSTROOT"/Applications/"$APPNAME".app
Drop this in your project directory and tweak to taste.
So, there you have it. We’ve built the
waxsim binary, learned briefly how to
xcodebuild, and learned how to launch your application in the iOS
simulator on demand and from the command line. Vive la Unix!
I like Square’s fork of WaxSim because they have a lot at stake to keep this working.↩