3. Configuring an Android Development Environment for PhoneGap
There are several options for PhoneGap development on Android; the tools run on Linux, Apple Macintosh OS, and Microsoft Windows. Additionally, developers have access to both an Eclipse plug-in as well as command-line tools for building applications. This chapter includes the steps to follow to install and use the Android development tools on Macintosh OS and Windows.
Refer to the Android Developer web site (http://developer.android.com) for additional or more up-to-date installation instructions including instructions for installation on a system running Linux.
To complete the steps outlined in this chapter, you must first perform several installation steps using instructions provided elsewhere in the book:
1. Install the PhoneGap framework using the instructions provided in Appendix A.
2. Install the Oracle Java Developer Kit (JDK) using the instructions provided in Appendix B.
3. If you are intending to use the command line to build Android applications, install Apache Ant using instructions provided in Appendix C.
Once those steps have been completed, you’re ready to start work on PhoneGap applications for Android.
Installing the Android SDK
The Android SDK is deployed in two parts. First, you install the SDK starter package on the local system; second, SDK components are added to the existing installation via download from the Android developer web site. The starter package contains utility programs used to manage the Android software development environment on the computer and the individual Android version SDKs are installed as needed. This allows for a single installation on a developer workstation, and then needed software updates (including adding additional SDKs) are performed on the fly via software download.
To download the started package, point your browser of choice to http://developer.android.com. On the landing page, click the Download link highlighted in Figure 3-1.
Figure 3-1 Android developer web site landing page
On the page that opens, shown in Figure 3-2, select the appropriate download for the operating system running on the computer.
Figure 3-2 Android SDK download options
For Windows users, use the recommended option and download the Windows executable. Once the file has downloaded, launch the downloaded file to begin the installation. Using this option installs the software and places the appropriate shortcuts for running the Android tools onto the Windows Start menu.
Windows Installation Issues
You must pay attention to several issues related to the Android SDK Starter Package installation on Windows when installing the software.
Early versions of the Android SDK installed its files in the root of the system’s hard drive. For some reason, Google changed its approach, and more recent SDK versions have installed its files in the Windows Program Files folder. While this is a good thing, conforming to Windows standards, there have been many bugs reported when the files are installed in that location. Google is aware of the problems and is working on fixing them, but I recommend you don’t allow the installer to install in the Program Files folder; instead, install the files off of the root of the system’s hard drive (c:android-sdk, for example).
On Windows, the installer sometimes has difficulty locating the required JDK installed on the system (described in Appendix B). When this happens, just click the Back button, and then click Next again in the installation wizard. The installer is usually able to find the JDK if you give it another chance. Repeat the process as many times as necessary depending on your experience with the installer.
For Macintosh computers, download the Macintosh version of the SDK to your system’s downloads folder. The Macintosh OS may automatically extract the files within the folder; if not, manually extract the files to the location of your choice. You can either execute the tools from the downloads folder or open Finder and drag the Android SDK folder to the Applications folder or another folder of your choice.
When the installation is complete, launch the Android SDK Manager (the file is called Android SDK.exe on Windows and android on Mac OS). When the program launches, it will connect to the Android developer web site and retrieve the list of SDK packages available for download. Each package refers to a specific version of the Android operating system. You can select only the packages you need based upon the OS versions you know you will be developing for, or you can just accept the default of all packages and click the Install Selected button to begin the installation, as shown in Figure 3-3.
Figure 3-3 Selecting Android SDK packages for installation
A lot of files are associated with each SDK package, so the process of downloading and installing the packages will take a very long time. Make sure you’re on a fast network connection before starting the installation and have other work you can do while you wait for the download and installation to complete. When the package installation completes, you may be prompted to restart the Android SDK Manager before continuing.
In the next step, you’ll need to create an Android Virtual Device (AVD) to use for your testing of PhoneGap applications. The AVD is an Android device emulator representing a standard Android device. Click the “Virtual devices” option in the Android SDK and AVD Manager, as shown in Figure 3-4.
Figure 3-4 Android Virtual Devices view
Click the New button, and you will see a dialog similar to the one shown in Figure 3-5. In the dialog, give the AVD a name and select the options appropriate for your Android application development needs; then click the Create AVD button.
Figure 3-5 Create new Android Virtual Device (AVD) dialog
Most modern smartphones (excluding Apple iOS) include a certain amount of device memory plus provide the means to add memory through an extra memory card (typically a Micro SD card). More sophisticated mobile applications will make use of both types of memory, using device memory for transient values and a memory card for storing ancillary files or larger data sets or databases. It’s likely that in your PhoneGap development efforts you’ll someday need to write and read data from a memory card, so when you’re setting up your Android AVD, be sure to allocate some space for an SD card as shown in the figure. The file option points the emulator to a local file on the development workstation, which allows you share the contents of a simulated SD card between emulators.
The Skin option is used to define the size of the emulated Android device. Keep in mind when making a selection here that the emulator can take up quite a large amount of screen real estate, so if you are working on a developer workstation with a smaller monitor, you may want to select a smaller skin so the emulator doesn’t exceed the boundaries of the screen.
As shown in Figure 3-6, the AVD manager allows you to define many different Android emulator configurations, which allow you to more easily text your PhoneGap applications using different predefined configurations.
Figure 3-6 Android AVD Manager with an Android emulator defined
To launch an emulator, select the emulator definition in the AVD Manager and click the Start button. The AVD manager will display a dialog allowing you to change some emulator settings before launching, such as scaling the emulator on the screen, wiping emulator memory, or launching from a particular snapshot. Click the Launch button to start the emulator.
On many systems, the emulator will take a very long time to start, so be patient. When the emulator launches, it will display a screen similar to the one shown in Figure 3-7. There will be an image of an Android smartphone screen on one side and a keyboard with additional simulator control options on the other side.
Figure 3-7 An Android emulator all ready to go
At this point, you would interact with the emulator just like you would a regular device—swiping and clicking, launching applications, and more.
Eclipse Development Environment Configuration
Google provides an Eclipse plug-in that simplifies the development of Android applications. Eclipse (www.eclipse.org) is a free, popular, open source integrated development environment (IDE) that’s used primarily for Java and web development but supports many other options as well. There are several editions of Eclipse, each addressing a particular type of development or a particular suite of tools.
Google’s tools support multiple editions of Eclipse and currently (although subject to change) support Eclipse 3.5 (Galileo) or greater. Since PhoneGap projects consist of both native and web technologies, I recommend installing the Eclipse IDE for Java EE Developers, which includes the Java development tools needed for Android development and the appropriate web content editors needed for PhoneGap web application development.
Applaud Eclipse Plug-In
In case you’re interested, Mobile Developer Solutions (www.mobiledevelopersolutions.com) offers a free Eclipse plug-in called Applaud that helps simplify PhoneGap development for Android devices.
Point your browser of choice to www.eclipse.org/downloads/, and select the appropriate download for your developer workstation. Figure 3-8 shows a subset of options for Windows computers, the page should automatically detect Macintosh or Linux computers and display the appropriate options for the current OS. If not, simply select the OS from the drop-down list at the top of the download list to change to an appropriate list of downloads.
Figure 3-8 Eclipse download page
Be sure to select the appropriate download bit-depth for the operating system you are running. For example, select the 32-bit version of the download if your development system is running a 32-bit OS, even if the system processor is 64-bit.
Once the Eclipse files have been downloaded, extract the downloaded files to the appropriate folder (your choice, as appropriate for the target OS) on your system’s hard drive and create the appropriate application shortcut needed to launch the Eclipse executable (eclipse.exe for Windows and eclipse for Macintosh OS).
Note
Later versions of Microsoft Windows (Windows Vista and Windows 7) have implemented a security structure that by default removes a user’s ability to modify the contents of the Windows Program Files folder. If you attempt to extract the Eclipse files to the Program Files folder and receive an error, just extract the files to the download folder and then copy the extracted eclipse folder to the Program Files folder afterward.
Next you’ll need to install the Eclipse plug-in for Android development. Launch Eclipse and open the Eclipse Workbench. Open the Help menu, and then select Install New Software. Eclipse will display an installation wizard similar to the one shown in Figure 3-9, although the wizard page initially displayed will not have any of the data shown in the figure. Populate the “Work with” field with https://dl-ssl.google.com/android/eclipse/ and press Enter. Eclipse will connect to the Android software downloads site (represented by the URL you entered) and download information about the available options. If you encounter a problem doing this, make sure you used an https instead of http when typing in the server URL.
Figure 3-9 Adding the Android Developer Tools to Eclipse
When the list of options appears in the dialog, place a check next to the Developer Tools option (which will accept all options) and click the Next button. Follow through the remaining options in the installation wizard including accepting the Android license agreement to complete the installation. During installation, Eclipse will prompt you to trust the software you are installing and will ask to restart Eclipse at the end of the installation process.
When Eclipse restarts, open the Window menu, and then select Preferences. In the dialog that appears, select the Android option and Eclipse will display a blank list of Android SDK targets. In the dialog, click the Browse button, navigate to the folder where you installed the Android SDK earlier in the chapter, and then click the OK button. Once the Android SDK location has been set, click the Apply button, and Eclipse will refresh the list of the Android SDK versions available at the specified location. At this point, your Android configuration in Eclipse should look like Figure 3-10.
Figure 3-10 Configuring Android SDK settings in Eclipse
Creating an Android PhoneGap Project
For building PhoneGap applications for Android, two options are available to you. You can build the application using Eclipse, or you can use the Android command-line tools and your web content editor of choice. In this section, I’ll show how to create a new Android PhoneGap project for each method.
New Eclipse Project
To create a new Android PhoneGap project using Eclipse, open the Eclipse IDE, open the File menu, and select New and then Project. Eclipse will present a wizard similar to the one shown in Figure 3-11. Expand the Android option, select Android Project, and click the Next button. If an option for Android projects does not appear in this wizard, the Android plug-in for Eclipse (installed earlier in the chapter) must not have installed correctly.
Figure 3-11 Eclipse’s New Wizard: selecting project type
Eclipse will then prompt for the Android-specific settings for the project, as shown in Figure 3-12. You will need to provide a name for the project, HelloWorld in the example shown, plus select the Android SDK build target for the application.
Figure 3-12 Eclipse’s New Wizard: defining Android project options
Warning
Although the dialog is presenting what appears to be a list of checkboxes, implying that you can select more than one option in the list, the checkboxes actually work like radio buttons and will allow you to select only one option.
You will also need to scroll down in the dialog shown in Figure 3-12 and provide a package name for your application (such as com.phonegapbook.helloworld). Set other project options as needed, and then click the Finish button to create the project.
The first thing you have to do is create two new folders in the project folder structure: libs and assets/www. The folders must be placed in the root directory of the project folder. To create the folders, right-click the HelloWorld project in the Eclipse Package Explorer (on the far left side of the Eclipse window shown in Figure 3-13). From the menu that appears, select New and then Folder. When prompted, enter libs into the New Folder dialog and click Finish.
Figure 3-13 A new PhoneGap project in Eclipse
Repeat the same process for the second folder, entering assets/www in the New Folder dialog. For this one, Eclipse will create two nested folders; it will first create a folder called assets and then create a folder called www within the assets folder.
Next, we have some files and folders to copy from the PhoneGap software installation’s Android folder. First close the Eclipse IDE, and then from the file system (Finder on Macintosh or Windows Explorer for Windows) perform the following steps:
1. Copy the phonegap.js file to the project’s assets/www folder. The file will be named phonegap-x.y.0.js where x refers to the major version number and y is the minor version number. Example: phonegap-1.3.0.js.
2. Copy the phonegap.jar file to the libs folder. The file will be named phonegap-x.y.0.jar where x refers to the major version number and y is the minor version number. Example: phonegap-1.3.0.jar.
3. Copy the entire xml folder to the res folder (created by the Android plug-in when the project was first created).
Once all of the files have been copied to the project, it’s time to modify the project’s source files and convert the Android Java project into a PhoneGap project. In the Eclipse Package Explorer, expand the HelloWorld project, expand the src folder, and then double-click the HelloWorldActivity.java file. Eclipse will open the project’s Java source file in the editor (as shown in Figure 3-13). Make the following changes to the Java source file:
1. Remove the android.app.Activity import. Since the project is no longer a standard Android activity, it’s no longer needed.
2. Add an import for com.phonegap.*. This provides the application with access to the PhoneGap library functions in the phonegap.jar file you copied over earlier.
3. Change the HelloWorldActivity class so that it extends from DroidGap instead of Activity. This essentially changes the project from an Android activity to a PhoneGap project.
4. Replace the setContentView(R.layout.main) with super.loadUrl ("file:///android_asset/www/index.html"). This instructs the program to load the application’s startup HTML file when the application launches.
When you complete the changes, the Java source file should match the following:
package com.phonegapbook.helloworld;
import android.os.Bundle;
import com.phonegap.*;
public class HelloWorldActivity extends DroidGap {
/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
super.loadUrl("file:///android_asset/www/index.html");
}
}
TipWhen you save the project, Eclipse may complain that it doesn’t recognize the code you’ve entered. This is because Eclipse can’t locate the phonegap.jar file you copied to the project folder. If this happens, in the Eclipse Package Explorer, right-click the libs folder and select Build Paths and then Configure Build Paths. In the dialog that appears, select the Libraries tab, and then add the .jar file to the project.
Once the Java source file is configured correctly, you will need to update the project’s manifest file. In the Eclipse Package Explorer, right-click the AndroidManifest.xml file, select Open With, and then select Text Editor.
Paste the following permissions XML into the manifest file immediately following the <manifest /> entry:
<supports-screens
android:largeScreens="true"
android:normalScreens="true"
android:smallScreens="true"
android:resizeable="true"
android:anyDensity="true"
/>
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name=
"android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name=
"android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name=
"android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
<uses-permission android:name=
"android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name=
"android.permission.RECEIVE_SMS" />
<uses-permission android:name=
"android.permission.RECORD_AUDIO" />
<uses-permission android:name=
"android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name=
"android.permission.READ_CONTACTS" />
<uses-permission android:name=
"android.permission.WRITE_CONTACTS" />
<uses-permission android:name=
"android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name=
"android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name=
"android.permission.GET_ACCOUNTS" />
The <supports-screens /> entry tells the Android virtual machine which screen properties are supported by the application. Since we’re building a web application that will scale according to the available screen real estate, we’re telling Android which options are supported. For tablet applications, you could also add the following to the list of options:
android:xlargeScreens="true"
Next, add the following to the first <Activity /> tag in the manifest file:
android:configChanges="orientation|keyboardHidden"
This tells the Android device running the application that the application will automatically handle orientation changes or when the user hides the keyboard.
Then add a second activity to the manifest using the following XML:
<activity android:name="com.phonegap.DroidGap"
android:label="@string/app_name"
android:configChanges="orientation|keyboardHidden">
<intent-filter></intent-filter>
</activity>
When completed, the manifest should match the following:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android=
http://schemas.android.com/apk/res/android
package="com.phonegapbook.helloworld"
android:versionCode="1" android:versionName="1.0">
<supports-screens android:largeScreens="true"
android:normalScreens="true" android:smallScreens="true"
android:resizeable="true" android:anyDensity="true" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name=
"android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name=
"android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name=
"android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
<uses-permission android:name=
"android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name=
"android.permission.RECEIVE_SMS" />
<uses-permission android:name=
"android.permission.RECORD_AUDIO" />
<uses-permission android:name=
"android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name=
"android.permission.READ_CONTACTS" />
<uses-permission android:name=
"android.permission.WRITE_CONTACTS" />
<uses-permission android:name=
"android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name=
"android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name=
"android.permission.GET_ACCOUNTS" />
<uses-sdk android:minSdkVersion="8" />
<application android:icon="@drawable/icon"
android:label="@string/app_name">
<activity android:name=".HelloWorldActivity"
android:label="@string/app_name"
android:configChanges="orientation|keyboardHidden">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name=
"android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
<activity android:name="com.phonegap.DroidGap"
android:label="@string/app_name"
android:configChanges="orientation|keyboardHidden">
<intent-filter>
</intent-filter>
</activity>
</application>
</manifest>
Depending on the nature of your development project, you will likely want to change the android:minSDKVersion element to reflect the minimum SDK version required for the application:
<uses-sdk android:minSdkVersion="8"/>
Save the changes, exit the text editor, and return to Eclipse.
The final step is to create the index.html file that will be the main interface for the PhoneGap application. In Eclipse, right-click the www folder in the Package Explorer and select New and then File. In the New File dialog, enter index.html as the file name, and then click Finish. Double-click the newly created file, and Eclipse will load the file into the HTML editor window. Paste in the HTML from the HelloWorld3 application from Chapter 2.
Save your changes, and select Run from the Eclipse Run menu. Eclipse will launch the default Android emulator you have defined and start the application. When it loads, you should see a screen similar to what is shown in Figure 3-14.
Figure 3-14 Android HelloWorld application running in the emulator
Using Command-Line Tools
For developers who want to do Android development using a different editor than Eclipse or just prefer to use command-line tools, you can manage Android projects directly from the command line. The information provided in this section covers this topic at a high level; you can find additional details on the build process at the Android Developer web site (http://developer.android.com).
To create a new Android application project, open a terminal window (Macintosh) or command prompt (Windows), navigate to the Android SDK tools folder, and then issue the following command:
android create project --target 14 --name HelloWorld --path
c:devHelloWorld --activity HelloWorldActivity
--package com.phonegapbook.helloworld
The Android tools will create an Android project folder structure at the specified location and create the necessary source and configuration files for the project. Figure 3-15 shows a sample of the output from the process.
Figure 3-15 Creating an Android project using command-line tools
Launching Unix Applications from the Command Line
When launching applications from the command line in Unix (which applies to computers running Macintosh and Linux), when you navigate to a folder where the application resides, you must predicate the application name with a ./ in order to launch the application. For example, to launch the Android application on Mac OS, the command begins with ./android and then includes any command-line options being passed to the application on launch.
Table 3-1 describes the command-line options used during this process.
Table 3-1 Android Tools Create Project Command-Line Options
At this point, the project is exactly the same as the project created within Eclipse (it’s actually this process that Eclipse uses behind the scenes to create new Android projects). To convert this new Android project into a PhoneGap project, complete the steps outlined in the previous section to modify the project’s files with the appropriate PhoneGap components and code.
To build your new PhoneGap project using the command-line tools, you will need to install Apache Ant (the installation steps are provided in Appendix C) and then open a terminal or command prompt window, navigate to your project’s root folder, and issue the following command:
ant debug
The Ant Build script included with the Android project will call the Java compiler and build a debug version of the Android application that can be deployed to an Android device (or Android emulator) for testing. Figure 3-16 shows an example of the build process output. The executable application file, the HelloWorld-debug.apk file, will be located in the project’s bin folder.
Figure 3-16 Building a PhoneGap application using the command-line tools
To build a version of the application for distribution to production devices, issue the following command:
ant release
Android applications must be signed before they can run on an Android device. The details of this part of the process are beyond the scope of this book. Refer to the Android developer web site at http://developer.android.com/guide/publishing/app-signing.html for additional information about application signatures and the signing process.
Testing Android PhoneGap Applications
When it comes to testing and debugging a PhoneGap application, developers have the option of using the Android emulator or running the application on a physical device. The information provided in this section covers this topic at a high level; you can find additional details on the debugging process at the Android developer web site (http://developer.android.com).
The ability to test and debug an application on a device or emulator is built into the Eclipse plug-in. As shown previously, simply launch the emulator or load onto a device directly from the IDE. The following sections provide information on how to test PhoneGap applications using the command-line tools.
Using the Emulator
When working with the command-line tools, you can easily deploy Android applications directly from a terminal or command prompt window.
When testing using the Android emulator, the first thing you must do is launch the Android SDK and AVD Manager highlighted in Figure 3-6; then select one of the emulators you have defined, and click the Start button. It may take a while, but the selected emulator will launch and wait for your input. Once the emulator is running, you must install the application being tested. From the Android SDK tools directory (c:android-sdk ools, for example), install the application’s .apk file on the emulator using the following command:
adb install <file_path><application>.apk
In this example, <file_path> refers to the folder where the file is located, and <application> refers to the executable file name for the application. By default, the application’s executable (the application’s .apk file) will be located in the project’s bin folder. For the HelloWorld application highlighted in this chapter, the project was created in c:devHelloWorld and the file name is HelloWorld-debug, so the command to install the application on the simulator would be as follows:
adb install c:devHelloWorldinHelloWorld-debug.apk
Installing on a Device
Before you can run your application on a device, you must ensure that USB debugging is enabled on the device. The setting can be located on most Android devices by launching the Settings application and selecting Applications, then Development, and finally USB debugging.
Warning
To be able to test on a live device, your computer system must be able to recognize an Android device when it’s connected to the system via a USB cable. If you connect a device and it’s not recognized by the system, you must resolve any connectivity issues before continuing.
Once your device is set up and connected via USB, navigate to the Android SDK platform-tools/ directory (c:android-sdkplatform-tools, for example), and install the .apk on the device using the following command:
adb -d install <file_path><application>.apk
The -d parameter passed to adb instructs the program to install the application to a physically connected device (rather than to an emulator). This process will return an error if more than one device is connected to the computer.