4. First Steps: Building and Running the MicroJobs 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.
4.1. 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.
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.
4.2. 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.
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. $ 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.
|
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 1.
4.3. 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 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.
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_LOCATION_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.
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.
3.5.4. 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.
4.4.1. 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.
4.4.2. 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:
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.”
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.
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
4.4.3. 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
4.4.4. 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 , and started on the phone. Most of the
debug features available on the emulator are also available when running in
debug mode on the phone.
