Building the Sample Application

Building the Sample Application

Now that we have the sample application directory created, the next thing to do is work out how to build and run the native application in the Android emulator.

NOTE: As mentioned previously, Ant is used by the Android SDK to build native applications. If you don’t already have Ant installed on your system, then you will need to obtain and install it before you can go further in this chapter. Instructions for installing Ant on various systems are available at http://ant.apache.org/manual/install.html.

With Ant installed and available on your system path, in a terminal window or at command prompt, change directory to the newly created sample directory, and execute ant with no command-line parameters to see the list of valid build targets. Figure 9–2 shows output generated from running the command.

CHAPTER 9: Native Bridging with PhoneGap

Figure 9–2. Attempting to build the sample project fails, as the path to the Android SDK is not yet known. Hmmm, that can’t be right—we should have seen a more meaningful message than that.

While the sample project is quite complete in terms of everything required to create a PhoneGap project, it doesn’t know the location of the Android SDK, and as a result the Ant build fails. This can be rectified by using the android command-line tool (one of the core tools in the Android SDK; it was introduced in Chapter 1) to generate a local.properties file for the build.

Simply run the following from the command line, with the copied sample directory as the current directory:

android update project -p ./ This creates a local.properties file for the project that contains a single property,

sdk.dir. This tells Ant where it can find the Android SDK, and consequently the required build tools to build the sample application.

Attempting to run Ant again once the local.properties file has been created will generate output similar to that shown in Figure 9–3.

CHAPTER 9: Native Bridging with PhoneGap

Figure 9–3. Running Ant with no command-line options provides information on how to build, and also validates that the build process is working correctly.

Now that Ant is configured and working correctly, we can build our app. While a number of options are displayed, for the moment the following are of most interest:

debug: The Ant debug target is used to build the application and sign it with a debug key. Once the application is built with the debug key, it can then be installed in the emulator (or a device configured for development) and therefore run.

install: The install target is used to copy the compiled executable to the emulator or device.

uninstall: Using the uninstall target in Ant will allow us to remove the application from either the emulator or the device. This can be very helpful, as removing an application from a device otherwise takes quite a bit of mucking around.

Now it’s time to build the app. First, you will need an emulator or device connected for the install target to be able to run successfully. Run the following command from the command line to check that you have an emulator or device that the app can be installed to successfully:

CHAPTER 9: Native Bridging with PhoneGap

adb devices The adb command (which stands for Android Debug Bridge) is one of the tools installed

with the Android SDK. This particular command provides information on the Android emulators and devices that are currently connected. Any Android device that is currently connected can then be interfaced with using a variety of developer tools. For more information regarding debugging Android web apps, see Appendix A.

If you have a valid emulator running, then you should see output similar to Figure 9–4. If not, then you will need to start an emulator instance or attach an Android device via USB.

Download from Wow! eBook <www.wowebook.com>

Figure 9–4. If an emulator is running (or a device is attached), then it will be shown by running “adb devices.” An emulator can be started by following the instructions outlined in Chapter 1.

Alternatively, you can run the following command: emulator @android_web_apps The emulator executable is used to start the Android emulator directly from the

command line. You specify which of the Android Virtual Device (AVD) images to use by providing a single parameter that has the ID of the AVD image with an @ symbol preceding it.

CHAPTER 9: Native Bridging with PhoneGap

TIP: While it is not mandatory to include the ANDROID_SDK/tools directory in your system path, it’s definitely worthwhile. Being able to access the adb and emulator commands without having to specify a full path will definitely save a lot of time. If you haven’t already done so, then we’d recommend you do that now.

Given that you now (if you didn’t already) have an Android emulator running or a device connected, you can run the build process to create a native Android application from the sample PhoneGap project and see how that looks.

Run the following from the command line, with the created sample directory as the current directory:

ant debug install This will instruct Ant to execute both the debug and install targets in the build.xml file. If

the build process completes successfully, you will see the magic words “BUILD SUCCESSFUL” (see Figure 9–5), and at this point you should be able to locate and run the sample PhoneGap application in your emulator.

Figure 9–5. Successful completion of the build and installation of the PhoneGap wrapper application

CHAPTER 9: Native Bridging with PhoneGap

If you see a message saying “BUILD FAILED,” then unfortunately something has not gone to plan. In most cases, this will be related to the build process not being able to deploy the sample application to the emulator or device. Retrace your steps and recheck the output of the adb devices command; you need to see a device listed in the output of this command, and its status should be shown as “device.” If the emulator is running but it is either not listed or is marked as “offline,” then close and restart the emulator and try again.

Once the application is installed, you will be able to run the application. Note that this does not happen automatically; rather, you need to locate and launch the app as you would any other Android application. Figure 9–6 shows an example of the sample application successfully installed.

Figure 9–6. If the build process has gone to plan, the sample application will be shown in the application menu.

CHAPTER 9: Native Bridging with PhoneGap

NOTE: With the release of the Android 2.3 SDK (Gingerbread) in early December 2010, a bug was introduced that prevents PhoneGap applications executing for this version of Android (previous versions are unaffected). At the time of writing, this bug is being monitored in the Android issue tracker at the following URL: http://code.google.com/p/android/issues/detail?id=12987.

If you are looking to build and release an Android web application that ships natively using PhoneGap, then this is a very important issue to keep track of. Unfortunately, there is no way of working around this particular bug if deploying your web app with a native wrapper is a priority for you, so we would recommend starring the issue in the issue tracker if it is not resolved by the time you read this chapter.

Let’s now have a look at the application. Figure 9–7 shows a screen capture of the sample PhoneGap application.

Figure 9–7. The PhoneGap sample application is running. I wonder what those buttons do? With the application now running, we will dive in and have a look at some of the code

behind the sample. This will give you an understanding of the kinds of things that you can do using PhoneGap that aren’t possible in a standalone web application.

CHAPTER 9: Native Bridging with PhoneGap

NOTE: Investigating and working with the PhoneGap sample application is best done if you actually have an Android device. This is because the sample works with device-level features (as you would expect) and the behavior of these is pretty limited in the emulator.

You will still be able to look at the code using the emulator, and we will look at alternative ways to monitor the device-level communication, but nothing beats holding your Android phone and having device-level features working from a web application.