How to build your first PhoneGap application

I recently started looking into PhoneGap again (been a few months and the upgrade from 2.7 to 3.3 went smoothly).

PhoneGap is a distribution of Apache Cordova. You can think of Apache Cordova as the engine that powers PhoneGap, similar to how WebKit is the engine that powers Chrome or Safari. (Browser geeks, please allow me the affordance of this analogy and I’ll buy you a beer later.)

Over time, the PhoneGap distribution may contain additional tools that tie into other Adobe services, which would not be appropriate for an Apache project. For example, PhoneGap Build and Adobe Shadow together make a whole lot of strategic sense. PhoneGap will always remain free, open source software and will always be a free distribution of Apache Cordova.

Currently, the only difference is in the name of the download package and will remain so for some time.Cordova Logo

What is Apache Cordova to a PhoneGap developer? (i.e. someone who just wants to build apps)

As a developer building PhoneGap applications, nothing has changed. PhoneGap is still free, openly licensed, and the main focus of the PhoneGap team. If your goal is to build cross platform apps with HTML, JS and CSS then keep on using PhoneGap for everything you need. This isn’t to say the transition has been perfect. We messed up the last release by not correctly updating the documentation to reflect the name change which confused new users. Future releases will have checks in place to ensure our documentation has the correct references. If you happen to be reading this and nodding in frustration, I encourage you to use as the canonical source for edge documentation. If you want to help us keep this stuff on point, please read on.


he Command-Line Interface

This guide shows you how to create applications and deploy them to various native mobile platforms using the phonegapcommand-line interface (CLI). This tool allows you to create new projects, build them on different platforms, either locally or on a remote server, and run them within an emulator or device. You can also use the CLI to initialize project code, after which you use various platforms’ SDKs to develop them further.


Before building projects locally, you need to install SDKs for each platform you wish to target. (See the Platform Guides for details on how to install each.) Otherwise, you can use the cloud-based PhoneGap Build service to compile apps for the following platforms remotely:

  • Android
  • iOS
  • BlackBerry 6
  • Windows Phone 7
  • WebOS
  • Symbian

Unlike PhoneGap Build, local builds support BlackBerry 10. The WebOS and Symbian platforms are only available when building remotely. The following platforms are only available when building locally:

  • Windows Phone 8
  • Windows 8

See Platform Support for an overview of all available options. See below for details on how to use PhoneGap Build to build remotely.

If building locally, you need to run the command-line interface from the same machine that supports the platform’s SDK. The CLI supports the following combinations:

  • iOS (Mac)
  • Android (Mac, Linux)
  • BlackBerry 10 (Mac, Linux, Windows)
  • Windows Phone 7 (Windows)
  • Windows Phone 8 (Windows)

On the Mac, the command-line is available via the Terminal application. On the PC, it’s available as Command Prompt underAccessories.

The more likely it is that you run the CLI from different machines, the more it makes sense to maintain a remote source code repository, whose assets you pull down to local working directories.

To install the phonegap command-line tool, follow these steps:

  1. Download and install Node.js. Following installation, you should be able to invoke node or npm on your command line.
  2. Install the phonegap utility. In Unix, prefixing the additional sudo command may be necessary to install development utilities in otherwise restricted directories:
    $ sudo npm install -g phonegap

    The installation log may produce errors for any uninstalled platform SDKs. Following installation, you should be able to run phonegap on the command line.

Create the App

Go to the directory where you maintain your source code, and run a command such as the following:

    $ phonegap create hello com.example.hello HelloWorld

The first argument specifies a hello directory to be generated for your project. Its www subdirectory houses your application’s home page, along with various resources under cssjs, and img, which follow common web development file-naming conventions. The config.xml file contains important metadata needed to generate and distribute the application.

The other two arguments are optional: the com.example.hello argument provides your project with a reverse domain-style identifier, and the HelloWorld provides the application’s display text. The -i and -n command-line options and their corresponding flags make these explicit:

    $ phonegap create hello -n HelloWorld -i com.example.hello
    $ phonegap create hello --name HelloWorld --id com.example.hello

Alterately, you can edit both of these optional values in the config.xml file later during development.


I went through all the steps and I got a few errors:

Obviously – this comes from disregard of the prerequisites: iOS native environment requires Mac OSX.
Second, I did not install any Java tools (Android SDK).

To get the Android SDK, you need to go to the Android Developer Website: and download the Android SDK Zip for your computer (in my case, Windows, X64). The zip file is quite big (400Mb+) and unarchived, goes up to a staggering 2GB. Once you apply all the updates that you need, it will go close to 2.5GB.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.