Lessons learned from trying PhoneGap\Cordova on Windows

I am investigating using PhoneGap as a platform for building mobile apps for several operating systems including Android. While doing so I have ran into various issues, and this article is intended to help others avoid the same headaches (with a focus on Android).

PhoneGap vs Cordova

The PhoneGap installation documentation says you could install PhoneGap using this command (will come back to that later).

npm install -g phonegap

But if you check the documentation or take various online tutorials you’ll notice they say you should install and use cordova. So what is PhoneGap and what is Cordova and which one should you use?

The best explanation comes from the PhoneGap itself:

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.

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.

In summary, PhoneGap is a distribution of Cordova and for the time being there is no other difference than the name of the package.

(Bonus read: PhoneGap or Cordova? Don’t confuse and tell me the differences!)

The question is then, which one should you use? If you plan to use Adobe’s utilities and services such as PhoneGap Build, then you should use PhoneGap. Otherwise you could pick Cordova. That is what I picked.

(Bonus read: Apache Cordova vs Adobe PhoneGap: the differences and which one to use)

Pre-requisites

In order to install either PhoneGap or Cordova you need to first install Node.js. Node.js is is a cross-platform runtime environment and a library for running applications written in JavaScript outside the browser.

  1. download and install Node.js
  2. add Node.js installation folder (e.g. C:\Program Files\nodejs) to the PATH environment variable

Installing Cordova

To install Cordova run this command in a console:

npm install -g cordova

The version I have installed is 3.5.0. The rest of the article relates to this version of Cordova.

Dependencies for Android

In order to be able to create and build for Android you need additional components.

  • Java
  • Apache Ant, a Java library and command-line tool for building software
  • Android SDK that provides libraries and tools for building, testing and debugging apps for Android

However, just installing these components is not enough. You need to set-up several environment variables, as they are required by Cordova/Phonegap.

  • create a variable called JAVA_HOME and set it to the Java installation folder (e.g. C:\Program Files\Java\jdk)
  • create a variable called ANT_HOME and set it to the Apache Ant installation folder
  • create a variable called ANDROID_HOME and set it to the Android SDK installation folder

After you have created these environment variables you also need to update the PATH variable to enable all these command line tools to be run from a console. Add the following paths to PATH:

%JAVA_HOME%\bin;%ANT_HOME%/bin;%ANDROID_HOME%\tools;%ANDROID_HOME%\platform-tools

Just having the Android SDK installed is not enough. You need to use the Android SDK Manager to install the appropriate tools for your Cordova version. For 3.5.0 the target API is 19 (or Android 4.4.2). When you install the tools make sure you also install a system image so you could create an Android emulator later. (Note that installation may take a while.)
android19
The next step is creating a virtual device for Android. You can run the following command to open up the Android Virtual Device Manager.

android avd

android-avd

Having done all this you can go ahead and create a cordova/phonegap application.

Create a HelloWorld application

To create, build and run a first cordova application execute the following commands in a console:

  1. create an application called HelloWorld
    cordova create HelloWorld app.marius.helloworld HelloWorld
  2. edit the application index.html page replacing the text of the text of the “event received” class paragraph:
    <p class="event received">Device is ready!</p>

    with

    <p class="event received">Hello World from Cordova!</p>
  3. add the Android platform to the application
    cd HelloWorld
    cordova platform add android
    
  4. build the application for Android:
    cordova build android
    
  5. run the application in an Android emulator
    cordova emulate android
    

Here is a screenshot of the Android application running in the emulator.
cordova-hw

Troubleshooting

If you missed any of the steps described in this article you will run into various errors when you try to create, edit, build or emulate your application. Below are several possible problems you may encounter and their solution.

Missing Apache Ant

When you try to add a platform to your application you may get this error message:

Error : Executing command ‘ant’, make sure you have ant installed and added to your path.

This is either because you did not install Apache Ant or because you have not setup the environment variables as described above.

Error querying Android targets

When you try to add a platform to your application you may get this error message:

Checking Android requirements…
(Error: An error occurred while listing Android targets)

This is either because you did not install the Android SDK or because you have not setup the environment variables as described above.

Missing Android target

When you try to add a platform to your application you may get this error message:

Error: Please install Android target 19 (the Android newest SDK). Make sure you have the latest Android tools installed as well. Run “android” from your command-line to install/update any missing SDKs or tools.

This is because you do not have the appropriate Android tools required by the installed cordova/phonegap version. For Cordova 3.5.0 the required platform tools are version 19 or Android 4.4.2. You can use the SDK Manager to install the appropriate tools.

No emulator available

When you try to emulate your application you may get this error message:

ERROR : No emulator images (avds) found, if you would like to create an avd follow the instructions provided here: http://developer.android.com/tools/devices/index.html
Or run ‘android create avd –name –target ‘ in on the command line.

This is because no emulator is defined. You need to use the Android Virtual Device Manager to create one or more emulators.

Using Eclipse

You probably do not want to do everything from the command line and plan to use an IDE. Eclipse comes bundled with everything you need for developing for Android. See the following references for using Android with Cordova.

Leave a Reply

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