Cordova-CLI is doing some great things to make working with multiple platforms in one Cordova project easier. But installing with it can initially seem a little daunting if you’ve never played with it before, and so I thought it would help to write this guide up to help anyone else getting their feet wet.
Note: I’m a Mac OS X user. Therefore, I’ve only tested any of this on my Mac. It should translate to Linux fairly easily. Getting anything to work on Windows is probably going to be painful, given that Cordova-CLI indicates it has only been tested on Mac OS X and Linux.
Downloading and Installing node.js
The first thing you need to do is install node.js. This is available at http://nodejs.org/. You can download the Mac OS X package by clicking “Install”.
Once downloaded, double-click the package file, and step through the instructions. node.js will tell you that it is installing to
/usr/local/bin and that your
PATH will need to be updated to include this.
To update your path, you can simply navigate back to your home directory (
~) and edit your
Next, the following commands in your
.profile will add
/usr/local/bin to your path — be sure to add them at the end of your
# for NODE
Before you do anything, be sure to close and restart your terminal session, or the
PATH won’t be correct. Alternatively, source your
Before installing Cordova-CLI
You need to be absolutely certain that you have access to your development tool’s command-line tools via the command line, or the install will error out later on.
You must have the latest version of each development environment installed, or things will most likely go very wrong.
Install Xcode Command Line Tools
Xcode and then navigate to
Preferences…, then select the
Downloads tab. If the
Components section isn’t already selected, select that.
Now, near the bottom of the list, there should be a
Command Line Tools option with an
Install option if it hasn’t already been installed. Click
Install to let it download and install.
Only proceed once the components have been fully installed. You may need to restart your terminal as well.
Agree to XCode’s License
Once you’ve got the command line components installed, the you must agree to the Xcode license agreement for all users of the computer.
Open terminal and type:
sudo xcodebuild -license
Enter your password when prompted. Then be sure to
[space] through the license, and then type
agree at the end.
Download Most Recent Android SDK
If you don’t have an Android SDK installed, be sure to download the Android SDK from Google at http://developer.android.com/sdk/index.html.
Be sure you’ve got the most recent version of the Android SDK installed. If you’ve already got a version installed and in the
PATH, you can type:
Alternatively, just open Eclipse and navigate to
Android SDK Manager.
If you have any updates, click the
Install # packages… button, then click
Accept All to accept all the license agreements, and then click
Add Android Tools To Your
Once again, navigate to your home directory (
~) and edit your
Then add this to the end of your
# for Android
Be careful to replace
Path-To-Android_SDK with the actual path to your Android SDK. On my Mac, this is under
/Applications, but it may be in another spot on your machine.
Before you do anything more, be sure to close and restart your terminal session, or the
PATH won’t be correct. Alternatively, source your
The install instructions don’t warn you that you need to be
root in order to install the package successfully. So, here’s the command I used:
sudo npm install -g cordova
When prompted, be sure to supply your user’s password, and then you should see output that looks like this:
npm http GET https://registry.npmjs.org/cordova
npm http 304 https://registry.npmjs.org/cordova
npm http GET https://registry.npmjs.org/colors
npm http GET https://registry.npmjs.org/elementtree/0.1.3
npm http GET https://registry.npmjs.org/xcode/0.5.1
If the install hangs, like mine did, just break the process (
CTRL-C), and re-run the installation command.
The final output should look something like this:
SUCCESS: Minimum requirements for blackberry met.
SUCCESS: Minimum requirements for ios met.
SUCCESS: ios ready to rock!
SUCCESS: blackberry ready to rock!
SUCCESS: Minimum requirements for android met.
SUCCESS: android ready to rock!
* WARNING: YOU ARE INSTALLING GLOBALLY INTO A ROOT-ONLY DIRECTORY!!!1one *
* Your node install is global, so global modules get installed there too.*
* You should probably run the following command for this tool to run: *
$ sudo chown -R your-user /usr/local/lib/node_modules/cordova
* This will allow you to run this tool globally without using `sudo`. *
├── email@example.com (firstname.lastname@example.org)
├── email@example.com (firstname.lastname@example.org, email@example.com)
├── firstname.lastname@example.org (email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com)
├── firstname.lastname@example.org (email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com)
├── firstname.lastname@example.org (email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com)
└── firstname.lastname@example.org (email@example.com, firstname.lastname@example.org)
If, at any point you see notices that the minimum requirements aren’t met for a particular platform, be sure that you’ve downloaded the most recent version, agreed to any license agreement, and have the correct paths in
PATH. You can re-run the installation command any number of times to repeat the process until you have all the minimum requirements met.
If you don’t intend to develop for a specific platform, you don’t need to worry if the install process complains that the minimum requirements aren’t met.
Finally, notice that big warning block in the output? This indicates that since node.js has been installed globally for all users, it currently has permissions that would require that you
sudo in order to execute any commands.
Therefore, execute the command as shown in order to make the command friendlier to use:
sudo chown -R your-user /usr/local/lib/node_modules/cordova
Installing iOS Simulator Support
If you intend on using the iOS Simulator from the command line, you aren’t done yet. You need to instal ios-sim first, most easily accomplished using homebrew.
You can learn more about homebrew at http://mxcl.github.com/homebrew/, but essentially it requests that you use the following command:
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
Let me first say how absolutely I abhor this method of installation. Therefore, be absolutely certain you trust the content of the file being downloaded and then executed before you run this command. I looked at it, and it looks safe enough to me, but you are expected to verify that it will be safe for you. If it turns out that it isn’t, not my fault. Sorry.
It will display a list of things it will do to your system, and then prompts you to press
[ENTER] when ready. (Or, press any other key to exit.)
==> This script will install:
==> The following directories will be made group writable:
==> The following directories will have their group set to admin:
Press ENTER to continue or any other key to abort
When it starts to do real work, it will prompt you for your
sudo password (assuming the previous
sudo attempts have timed out).
You should have output similar to this:
==> /usr/bin/sudo /bin/chmod g+rwx /usr/local/. /usr/local/bin /usr/local/include /usr/local/lib /usr/local/share /usr/local/share/locale /usr/local/share/man /usr/local/share/man/man1 /usr/local/share/man/man5
==> /usr/bin/sudo /usr/bin/chgrp admin /usr/local/. /usr/local/bin /usr/local/include /usr/local/lib /usr/local/share /usr/local/share/locale /usr/local/share/man /usr/local/share/man/man1 /usr/local/share/man/man5
==> Downloading and Installing Homebrew...
remote: Counting objects: 105377, done.
remote: Compressing objects: 100% (44209/44209), done.
remote: Total 105377 (delta 74733), reused 88054 (delta 60267)
Receiving objects: 100% (105377/105377), 15.76 MiB | 229 KiB/s, done.
Resolving deltas: 100% (74733/74733), done.
* [new branch] master -> origin/master
HEAD is now at b412fe3 exiftool 9.24
Warning: Install the "Command Line Tools for Xcode": http://connect.apple.com
==> Installation successful!
You should run `brew doctor' *before* you install anything.
Now type: brew help
I’ll be honest as to not knowing why it insists I don’t have Command Line Tools installed — I do.
brew doctor as it suggests. You’ll receive some warnings (I got plenty), but it is up to you to decide if they are worth fixing or not.
Next, we can install ios-sim
brew install ios-sim
You’ll see output like this:
==> Downloading https://github.com/phonegap/ios-sim/tarball/1.6
==> /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/rake install prefix=/usr/local/Cellar/ios-sim/1.6
/usr/local/Cellar/ios-sim/1.6: 4 files, 96K, built in 5 seconds
If you run this and you see a mug of beer, yes – that’s normal.
Creating Your First Project
You should now be able to create the project by issuing the following at the command prompt:
cordova create path-to-project/ reverse.domain.name project-name
For example, you might use something like this:
cordova create ./exampleApp demo.example.com exampleApp
After this, you’ll have a directory structure that looks like this:
Adding Platforms to your Project
Without any target platforms, the project won’t be going anywhere. Let’s add some:
cordova platform add ios android
Now, the directory structure looks like this:
Listing Project-supported Platforms
If you ever in the future want to know what platforms a project supports, you can execute
cordova platform list:
cordova platform list
The output will be something like this:
[ 'android', 'ios' ]
Removing a Platform
Perhaps you’ve decided to remove a platform from the project. You can remove it very easily:
cordova platform remove android
After which a
cordova platform list returns (for our example):
[ 'ios' ]
Compiling a Project
There are several ways you can compile a project.
cordova prepare and then
cordova prepare from the command line, and then use your IDE
cordova build from the command line
If you’re working solely from the command line, the latter is probably the easiest method. If, however, you like to use your IDE for building, deployment, and testing, you could always use the second option.
If you only want to compile for one platform (instead of all of them), you can specify the list of platforms, like so:
cordova build ios android
The first and third options above are the same thing. The latter simply does both steps for you.
Emulating a Project
To emulate a project in your platform’s emulator, you can use:
cordova emulate [platform…]
If you don’t specify any platform, you’ll end up emulating the project on every emulator the project is valid for. While this is sometimes the goal, I often test on one platform first, and then move on to the other. So you’ll almost certainly want to specify a single platform:
cordova emulate android
Note: there’s no prompt as to which device you’re going to emulate. You’ll need to have specified that in advance using the appropriate tool in your SDK.
Now, if you try to emulate an iOS device without installing ios-sim, you’ll hit a roadblock:
[Error: An error occurred while emulating/deploying the ios project.Error: ios-sim was not found. Please download, build and install version 1.4 or greater from https://github.com/phonegap/ios-sim into your path. Or "brew install ios-sim" using homebrew: http://mxcl.github.com/homebrew/
Why Cordova-CLI doesn’t do this (or prompt to do this) or even warn you at install time is beyond me. Rather it creates a rather rude interruption in your workflow that you have to overcome in order to just test on iOS. Now you know why we installed it ahead of time. But, if like me, you get caught by this error, look above at the section entitled “Installing iOS Simulator Support” and follow the instructions before repeating the emulator command.
Testing using a Webkit Browser
If your app doesn’t rely on any of the Phonegap APIs or use any plugins, you can test the app using a Webkit browser such as Chrome or Safari.
cordova serve platform [port]
Here you must specify a platform (like iOS), so if you’ve made changes to the global
www directory, you’ll need to, at a minimum,
cordova prepare the platform in question, or you’ll see out-dated content.
port is optional; it will default to
8000 on its own.
Once started, you’ll see this output:
Static file server running at
CTRL + C to shutdown
Now you can navigate to http://localhost:8000 from your machine, or do the same from any other device (substituting
localhost with the proper
hostname of your development machine).
Keep in mind that this in no way provides a PhoneGap API or emulation to the project. So even if you access the content from your iPhone, you’ll find that it behaves no better than it would in a browser on your machine. That said, it’s still useful for testing rendering without doing a full deploy on your devices.
When done, you can kill the server using
cordova serve on development machines behind a firewall. The web server used in this context is not intended to be used in production.
Before you go much further, you’re going to want to check and update your
config.xml file. It was created when you used
cordova create, and it contains all sorts of properties you’ll need to double-check and change.
The file itself will be in
project-directory/www/config.xml and you can edit it using any editor that understands plain text or XML.
You’ll almost certainly want to update the
author sections to your liking, but you’ll also eventually need to deal with the other properties as well. You can see more about these on PhoneGap’s Documentation Site. You’ll also eventually need to adjust the whitelisting property as well, though by default it allows any external reference.
More, so much more…
There’s far more to Cordova-CLI than what I’ve gone over here. You’ll note that I’ve not covered plugins at all, though I will write an article at some point in the future. In the meantime, if you want the syntax for dealing with plugins, I’ve included it below:
cordova plugin list -- lists all the plugins in the project
cordova plugin add path-to-plugin… -- adds one or more plugins to the project
cordova plugin remove plugin-name… -- removes one or more plugins from the project.
There are also hooks you can add for each command if you need to integrate your own build system or somehow need them for integrating with your version control system. Regardless, they are beyond the scope of this article.
Comments, thoughts, corrections? Post them below, or feel free to reach out to me via my website or my handle on Twitter or ADN (@photokandy). I’m also pretty active on the Google Group for Phonegap.
- March 27, 2013 - Tumblr dropped some inline links. Fixed a couple of spelling errors. Thanks to @Steve in the comments!