First Steps Building and Running the Micro Jobs Application

So now that we know a bit about which files are located in which folders, what happens when we ask Android to run the MJAndroid application? And for that matter, how do we ask Android to run the application? Let's take a closer look at the Android SDK environment and the views and commands available to us for running and debugging any application.

A Very Short Tour of the Android SDK/Eclipse IDE

The Android SDK provides three "perspectives" for working with Android projects and applications. If you're new to Eclipse, a perspective is a collection of Eclipse views that provides a particular viewpoint of an application. Eclipse and the Android SDK have preassembled sets of views that developers have found useful, and you can switch between those views, either by selecting one from the Window menu or by using the icons in the upper-right corner of the Eclipse window. You are also free to customize the perspectives, but in this book we will assume you use the standard ones provided:

Java

This is the default perspective, launched by Eclipse when you first say that you want to view the workspace. It includes:

Package Explorer

Used for viewing folders and selecting files Source Editor

Used for editing Java and XML source files

Tabbed Views

Contains a set of useful views, accessed by tabs:

• Problems, which lists errors that Eclipse and the Android SDK find in the application

• Javadoc, which extracts and displays Javadoc documentation from the application

• Declaration, which makes it easy to find the declaration for any variable in the code

• Console, which shows the console terminal output from either the emulator or the Android phone

• Search, which is used to search for results

• Progress, which displays progress as an application is launched and runs

Debug

This perspective is primarily for debugging the application, obviously. If you select Debug from the Run menu, Eclipse switches automatically to this perspective, providing you with views that are useful for debugging:

Debug

A view of the application call stack, showing you how you got to the current debug point Source View

This shows you the current source location in the running (or stopped) application

Console and Tasks Views

This contains the console terminal (as in the Java perspective), and a window where development tasks can be recorded and tracked Variables, Breakpoints, and Expressions

This is where you can view current variable values, view breakpoints, and evaluate expressions while debugging

Outline

This shows you an outline of the current activity being executed: the classes declared, and the instances and methods defined

DDMS

This perspective, which stands for Dalvik Debug Monitor Service, is unique to Android. It provides Android-specific debug information, including:

Devices

This shows you what devices (emulated or hardware) are available to run your applications. Emulator Control

This is where you can adjust parameters that define how the telephony and location emulators work. When running on the emulator, we'll use this to manually send location updates to the location provider.

LogCat

This is a view of the very powerful logging facility available under Android, which allows you to see everything going on in the target system, and to filter out the information you really care about.

Threads, Heap, and File Explorer

This is a tabbed set of views where you can follow the running threads in the application, see how the heap is being used, and select files from the folder hierarchy.

Loading and Starting the Application

Running MJAndroid from the SDK is complicated by the fact that the application uses a MapView. Android requires a special Map API Keywhenever you use a MapView, and the key is tied to your particular development machine. You'll learn all about this in Chapter 7, but right now the easiest way for you to run MJAndroid is simply to install the .apk file in the emulator.

Running the MJAndroid Code

If you downloaded the MJAndroid code and tried to use the Android SDK to compile it and run it, it probably didn't work. The most likely reason is that you didn't change the Map API Key to match the key needed by your installation of the SDK. To run an application such as MJAndroid that uses the MapView, you need a Map API Key. The easiest way to run the application is to install the binary we provided from the .apk file in the book's examples: MJAndroid-1.0.0.apk. You can install the file into the emulator by simply starting the emulator (if it's not already running) from a terminal window:

$ emulator

You'll then need to open another terminal window to enter the installation command: $ adb install MJAndroid-1.0.0.apk

Once MJAndroid is installed on your emulator, you can launch it from the Application Launcher, just like any other application.

If you want to be able to make modifications to the code and build and run under the SDK, read Chapter 7 to learn how to get the Map API Key you need.

You are probably already in the Java perspective, but if not, select it now. If you loaded the MJAndroid application into your Eclipse workspace folder as described earlier, you should see it in the Package Explorer. If you now right-click on the MJAndroid entry, you get a long menu of options. Select Open Project, a little over halfway down the list, and Eclipse will open the MJAndroid project and allow you to see its contents.

If we didn't have to deal with the Map API Key issue, starting the application would be as easy as selecting Run from the menu of the same name. Eclipse shows a dialog box (labeled "Run As") that asks how you want to run the application. You will always select Android Application from the top of the list.

At this point, the Android SDK will either select the target hardware you identified or start the emulator as the target. It will automatically load your application on the target and attempt to start it. In the case of MJAndroid, you should see the opening screen, shown earlier in Figure 3-1.

Digging a Little Deeper: What Can Go Wrong?

As you are developing your application, at some point you will try to run it, as just described, and it won't work. You'll either get an unexpected result or you'll get an error on the target screen that may be less than informative. Let's spend a little time looking at what the Android SDK does to get an application running, and what might go wrong.

As you know, Android applications run under a virtual machine called Dalvik. When you selected "Run" in the previous section, tools in the Android SDK saw that there was not a compiled version of MJAndroid available to run. They first took all the layout and variable information that was coded into XML files and converted it into Java source code (in the R.java folder), and then compiled all the Java source code into Java bytecode files (.class files). A translator converted the Java bytecodes into Dalvik bytecode files (.dex files). The Dalvik modules were combined with other information about the application, including the manifest file AndroidManifest.xml, and packaged into an Android package (or .apk) file. In the case of the MJAndroid application, this file is MJAndroid.apk, located in .../MJAndroid/bin. An Android package is what the target receives to load and start the application running. A lot of the startup information is in the AndroidManifest.xml file, so let's take a closer look at it.

When you double-click the AndroidManifest.xml listing in the Package Explorer, the Android SDK starts the Android Manifest editor in the middle pane of the Java perspective, and loads the file, as shown in Figure 3-2.

As you see, there are five tabs at the bottom of the editor pane, which give you five different views of the manifest file:

Overview

This is the view presented by default (if the file hasn't been opened before). It shows the package name for the application and shared user ID information (for use when multiple applications have to share a common user ID), presents some options for exporting and signing your application, and provides links to each of the tabs described next.

Application

This view provides access to a lot of the parameters that can be set for an application. Most of these are either self-explanatory or are not used in an application like MJAndroid. Two areas of interest are:

• Icon, which tells Android where to find a drawable icon to use for the application on the target.

ci Android Manifest Overview

» Genera! Information

Def i n es g en era I informaition a bout th e An d roi d Ma n if est.Hm I

Package com.microjobsinc.mjandroid

Version code Version name Shared user id

» Exporting

To export the application for distribution:

1. Export the unsigned apk.

2. Sign yourapk using jarsigner.

- Links

The content of the Android Manifest is made up of three sections, You can also edittheXML directly, Cl Application: Activities, intent filters, providers, services and receivers. CI Permission: Permissions defined and permissions used. Cl In stru m entati o n : Instru m entati on d efi n ed. Cl XML Source: Directly edit the AndroidManifest.Hml file.

Cl Documentation: Documentation from the Android SDK for AndroidManifest.xml.

Overview | Application Permissions Instrumentation AndroidManifest.Hml

Figure 3-2. Android Manifest editor

• Application Nodes, which identifies the activities, services, and providers in the application. There are a number of things worth noting in this section.

Uses Library

For MJAndroid, we will use the MapActivity to display maps. That class is not part of the core Android libraries, so we call out here that we need access to the additional library com.google.android.maps. Activity Attributes

Click on the little triangle to the left of MicroJobs (Activity) to see the intent filters attached to that activity. If you recall, activities in Android are run when their intent filters satisfy an intent that was expressed by some already running application. In this case we see two filters for MicroJobs:

<action android:name="android.intent.action.MAIN" />

This tells the Android application launcher that this activity is the one to be started first for MJAndroid. <category android:name="android.intent.category.LAUNCHER" />

This tells Android that the icon for this activity and application is to be displayed on the menu of launchable applications.

We'll talk about the intent filters assigned to the other activities as we get to their use in the code.

Permissions

Android controls what applications are allowed to do by requiring that they ask for permission to perform critical actions. When the application is installed on a real device, the user can choose whether to allow the requested permissions and proceed with installation, or to reject installation (in the emulator environment, it is assumed all permission requests are granted). It is important to include only the permissions needed by your application; you don't want to ask the user for permissions that you don't need. For MJAndroid, we'll need the permissions shown in this tab:

• <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"

/> allows us to use fine-grained location providers, such as GPS.

• <uses-permission android:name="android.permission.ACCESS_LOCA TION_EXTRA_COMMANDS" /> allows us to access additional location commands.

• <uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION"

/> allows the creation of mock location providers.

• <uses-permission android:name="android.permission.INTERNET" /> allows us to access the Internet.

• <uses-permission android:name="android.permission.CALL_PHONE" /> allows the application to place telephone calls.

Instrumentation

Android allows developers to replace Dalvik classes with substitute classes when running in the emulator environment. The intent is to allow one to better instrument particularly tricky code. We won't be using this feature in this book, but you can search for "Instrumentation" in the Android documentation to find out more.

AndroidManifest.xml

This view shows the actual XML file that results from all the choices made in the other views. If you are already comfortable with XML, you may prefer to edit the file directly in this view, rather than using the others. Be careful, though, because Android is very choosy about seeing the right tags in the right places, and doesn't always give you an error message indicating what, exactly, is wrong. The editor used in this view does XML syntax checking for you, but it doesn't know anything about the semantics of the various XML tags defined by Android. It's interesting to make changes in the other views and see their effect on the actual XML file by looking at this view.

So there is a lot of information in the AndroidManifest.xml file, and the system uses that information when launching the application. In the next chapter, we'll see what actually goes on inside the application as it starts up.

Running an Application on the T-Mobile Phone

Emulators are great development timesavers, and the QEMU emulator used by Android runs particularly well. You can probably debug 95% of your application just using the emulator. But an Android application doesn't have much raison d'être until it gets the chance to run on real phones. Luckily, Android makes it easy for you to try your application on one. As this is written, the T-Mobile G1 phone is the only Android phone on the market, so we'll give instructions for using it with the Android SDK. Future Android phones should be similar.

Enable USB debugging on your phone

Before you connect your T-Mobile G1 to the host, go to the Desktop screen on the phone, and push the Menu button. One of the menu options is Settings. Touch it to select, and you will be taken to the Settings dialog for the phone, which consists of a list of things you can set. The list is bigger than the screen, so scroll up and down until you find Applications, and touch that entry. You're taken to a sublist related to applications, and one of the entries is Development. Touch that, and you're shown two options:

USB Debugging

You want to enable this option by touching it. A green checkmark should appear in the adjacent checkbox.

Stay awake

This option will keep the screen on as long as the USB cable is connected. It can be annoying when the screen goes off, taking you back to the opening screen, so you might as well enable this too.

Your T-Mobile G1 now expects to receive debug information through the USB port, but don't plug it in just yet, because we may need to load a special driver on the host.

Load the USB driver for ADB

Depending on which host operating system you are using, you will need to install a driver for the USB port, or configure the existing driver:

Windows (either Vista or XP)

You will need to install a USB driver that is included with the Android SDK. The driver is located in <SDK>/usb_driver, where <SDK> is the location in which you installed the Android SDK.

Once you've extracted the driver, plug in the USB cable connecting the phone to the host. A Found New Hardware dialog will pop up that gives you a chance to load the new driver. The details will vary slightly, but in general:

1. Windows will ask if you want to search for a driver, which you don't. Instead, you want to tell it where you put the driver directory, so select the option that is something like "Install from a list or specified location."

2. Ignore any dire warnings from Windows about the driver not being certified. This just means that no one paid Microsoft to perform the certification tests.

3. When asked for the driver's location, browse to the USB driver directory, <SDK>usb_driver. The extraction should have created a subdirectory called android_usb_windows. Select that subdirectory and click OK.

Windows will load the driver and tell you that the hardware is ready to use.

Mac OS X

You're all set without doing anything. Ubuntu Linux

For Ubuntu, you need to configure the USB connection with a rules file, located at /etc/udev/rules.d/50-android.rules. The contents of the rules file are slightly different depending on which version of Ubuntu you are using. If you are using a different Linux distribution, you'll need to look at its documentation to understand how USB rules files are configured.

Ubuntu Dapper Drake

Create a file at /etc/udev/rules.d/50-android.rules with one line in it:

SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"

Ubuntu Gutsy Gibbon or Hardy Heron

Create a file at /etc/udev/rules.d/50-android.rules with one line it it:

SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"

In all cases (Dapper, Gutsy, or Hardy), make the rules file readable and executable by executing from the shell as root:

chmod a+rx /etc/udev/rules.d/50-android.rules

Connecting the phone

Now that you have the driver loaded, you are ready to plug in the USB cable that connects the T-Mobile G1 to the host. The phone will beep, and Eclipse will update itself as it learns of the new target. If you go to a terminal (Linux or OS X) or Command window (Windows) and type adb devices, you should see something like this:

>adb devices List of devices attached emulator-5554 device HT840GZ12968 device

Running MicroJobs on the phone

Now when you select Run from the Eclipse menu, you will still get the dialog that asks what kind of application you want to run (Android Application, Java Applet, Java Application, etc.), but now you will get a second dialog that asks which target you want to run on. The available targets will be listed, and you can click on either the emulator or the phone, depending on which you'd prefer. Select the phone, and the application is downloaded (using the debug signature; more about application signatures in Chapter 7), and started on the phone. Most of the debug features available on the emulator (covered in detail in Chapter 5) are also available when running in debug mode on the phone.

0 0

Post a comment