Creating A New Android Project

The Android Development Tools plugins kindly provides a Wizard for setting up new Projects which will allow us to create new Eclipse projects relatively quickly for either new or existing code.

Select File > New > Project

1. Select Android > Android Project, and press Next
2. Select the contents for the project:

• Select Create new project in workspace to start a project for new code. Enter the project name, the base package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.
• Select Create project from existing source to start a project from existing code. Use this option if you want to build and run any of the sample applications included with the SDK. The sample applications are located in the samples/ directory in the SDK. Browse to the directory containing the existing source code and click OK. If the directory contains a valid Android manifest file, the ADT plugin fills in the package, activity, and application names for you.

Press Finish.

Once completed the ADT plugin will go ahead and create the following files and folders as appropriate for the type of project selected:

• src/ A folder that includes your stub .java Activity file.
• res/ A folder for your resources.
• AndroidManifest.xml The manifest for your project.

Creating A Launch Configuration For Eclipse

In order to be able to run and debug your own Eclipse applications you must first create a launch configuration. Simply, a launch config is used to specify which project to launch, which activity to start and the specific emulation options to use.

To create a launch configuration for the application, please see the following steps:
1. Select Run > Open Run Dialog… or Run > Open Debug Dialog… as appropriate.
2. In the project type list on the left, right-click Android Application and select New.
3. Enter a name for your configuration.
4. On the Android tab, browse for the project and Activity to start.
5. On the Emulator tab, set the desired screen and network properties, as well as any other emulator startup options.
6. You can set additional options on the Common tab as desired.
7. Press Apply to save the launch configuration, or press Run or Debug (as appropriate).

Running and Debugging an Eclipse Application

Once both steps 1 and 2 have been completed and your project and launch configs are up and running you will now be able to run or debug your application.

From the Eclipse main menu, select Run > Run or Run > Debug as appropriate. This command will run or debug the most recently selected application.

To set or change the active launch configuration, use the Run configuration manager, which you can access through Run > Open Run Dialog… or Run > Open Debug Dialog….

Running or debugging the application will trigger the following actions:

• Starts the emulator, if it is not already running.
• Compile the project, if there have been changes since the last build, and installs the application on the emulator.
• Run starts the application.
• Debug starts the application in “Wait for debugger” mode, then opens the Debug perspective and attaches the Eclipse Java debugger to the application.

Developing Android Applications with Other IDEs and Tools

Although it is recommended you use Eclipse with the Android plugin to develop your applications, the SDK also provides tools which will enable you to develop with other IDE’s including intelliJ (alternatively you could just use Eclipse without the plugin).

Creating an Android Project

Bundled with the Android SDK is a program called activityCreatory. activityCreator will generate a number of ‘stub’ files for your chosen project alongside a build file. This can be used to either create an Android project for new code or from existing code.

For Linux and Mac users the Android SDK provides a Python script called activityCreator.py, with Windows users receiving a btach script called activityCreator.bat. The program is used in the same way regardless of operating system.

In order to run activityCreator and create an Android project, follow these steps:

1. In the command line, change to the tools/ directory of the SDK and create a new directory for your project files. If you are creating a project from existing code, change to the root folder of your application instead.
2. Run activityCreator. In the command, you must specify a fully-qualified class name as an argument. If you are creating a project for new code, the class represents the name of a stub class that the script will create. If you are creating a project from existing code, you must specify the name of one Activity class in the package. Command options for the script include:

–out which sets the output directory. By default, the output directory is the current directory. If you created a new directory for your project files, use this option to point to it.

–ide intellij, which generates IntelliJ IDEA project files in the newly created project
Here’s an example:

/android_linux_sdk/tools$ ./activityCreator.py –out myproject your.package.name.ActivityName
package: your.package.name
out_dir: myproject
activity_name: ActivityName
~/android_linux_sdk/tools$

The activityCreator script generates the following files and directories (but will not overwrite existing ones):

• AndroidManifest.xml The application manifest file, synced to the specified Activity class for the project.
• build.xml An Ant file that you can use to build/package the application.
• src/your/package/name/ActivityName.java The Activity class you specified on input.
• your_activity.iml, your_activity.ipr, your_activity.iws [only with the -ide intelliJ flag] intelliJ project files.
• res/ A directory to hold resources.
• src/ The source directory.
• bin/ The output directory for the build script.

Once complete you will now be able to move your folder wherever you choose for development but you’ll need to bear in mind then you will need to use the adb program in the tools folder in order to send the files to the emulator.

How-To Build An Android Application

Here’s how to use the Ant build.xml file generated by activityCreator to build your application.

1. If you don’t have it, you can obtain Ant from the Apache Ant home page. Install it and make sure it is on your executable path.
2. Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to where the JDK is installed.Note: When installing JDK on Windows, the default is to install in the “Program Files” directory. This location will cause ant to fail, because of the space. To fix the problem, you can specify the JAVA_HOME variable like this: set JAVA_HOME=c:\Prora~1\Java\. The easiest solution, however, is to install JDK in a non-space directory, for example: c:\java\jdk1.6.0_02.
3. If you have not done so already, follow the instructions for Creating a New Project above to set up the project.
4. You can now run the Ant build file by simply typing ant in the same folder as the build.xml file for your project. Each time you change a source file or resource, you should run ant again and it will package up the latest version of the application for you to deploy.

How-To Run An Android Application

In order to run a compiled application you will first need to upload the .apk file to the /data/app/ directory in the emulator using the adb tool:

1. Start the emulator (run $SDK_HOME/tools/emulator from the command line)
2. On the emulator, navigate to the home screen (it is best not to have that application running when you reinstall it on the emulator; press the Home key to navigate away from that application).
3. Run adb install myproject/bin/.apk to upload the executable. So, for example, to install the Lunar Lander sample, navigate in the command line to $SDK_ROOT/sample/LunarLander and type ../../tools/adb install bin/LunarLander.apk
4. In the emulator, open the list of available applications, and scroll down to select and start your application.

Please Note: When installing an activity for the first time you may need to restart the emulator engine in order for the activity to show up in the application launcher or before any other application can call. This is usually down to the fact that the package manager normally only examines manifests completely on emulator start-up.

How-To Attach a Debugger to Your Application

The following section details how to display debug information directly onto the screen (for example CPU usage). It also shows you how to hook up your IDE to debug running applications on the emulator.

The Eclipse plugin automatically attaches a debugger but you can configure other IDE’s to wait on a debugging port by doing the following:

Start the Dalvik Debug Monitor Server (DDMS) tool , which acts as a port forwarding service between your IDE and the emulator.

1. Set optional debugging configurations on your emulator, such as blocking application startup for an activity until a debugger is attached. Note that many of these debugging options can be used without DDMS, such as displaying CPU usage or screen refresh rate on the emulator.
2. Configure your IDE to attach to port 8700 for debugging. We’ve included information higher up on how to set up Eclipse to debug your project.

How-To Configure Your IDE To Attach To The Debugging Port

DDMS will automatically assign a specific debugging port for every virtual machine that it detects on the emulator. You must either attach your IDE to that port, or use a default port 8700 to connect to whatever application is currently selected on the list of discovered virtual machines.

Ideally your IDE will attach to the application running on the emulator, showing its threads and allowing you to suspend them, inspect them, or set breakpoints. If you choose to “Wait for debugger” in the Development settings panel, this will cause the application to run when Eclipse connects therefore you will need to set any breakpoints you want before connecting. If you change the application being debugged or the “Wait for debugger” then the system will kill the selected currently running application.

This can be handy if your application is in a bad state, you can simply go to the settings and toggle the checkbox to kill it.

Debugging Android

Google Android has a fairly extensive set of tools to help you debug your programs:

• DDMS – A graphical program that supports port forwarding (so you can set up breakpoints in your code in your IDE), screen captures on the emulator, thread and stack information, and many other features. You can also run logcat to retrieve your Log messages. See the linked topic for more information.
• logcat – Dumps a log of system messages. The messages include a stack trace when the emulator throws an error, as well as Log messages. To run logcat, see the linked topic. …
  I/MemoryDealer( 763): MemoryDealer (this=0×54bda0): Creating 2621440 bytes heap at 0×438db000
  I/Logger( 1858): getView() requesting item number 0
  I/Logger( 1858): getView() requesting item number 1
  I/Logger( 1858): getView() requesting item number 2
  D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.google.android.home.AllApps}
  …

• Android Log- A logging class to print out messages to a log file on the emulator. You can read messages in real time if you run logcat on DDMS (covered next). Add a few logging method calls to your code.

To use the Log class, you just call Log.v() (verbose), Log.d() (debug), Log.i() (information), Log.w() (warning) or Log.e (error) depending on the importance you wish to assign the log message.
Log.i(“MyActivity”, “MyClass.getView() — Requesting item number ” + position) You can use logcat to read these messages

• Traceview – Android can save a log of method calls and times to a logging file that you can view in a graphical reader called Traceview. See the linked topic for more information.
• Eclipse plugin – The Eclipse Android plugin incorporates a number of these tools (ADB, DDMS, logcat output, and other functionality). See the linked topic for more information.

Debug and Test Device Settings – Android exposes several settings that expose useful information such as CPU usage and frame rate.

Debug and Test Settings on the Device

Android enables you to set a number of options that will make it far easier to test and debug your applications.

To get to the development settings page on the emulator simply go to Dev Tools > Development Settings. This will in turn open up the development settings page with the following options (among others):

• Debug app Selects the application that will be debugged. You do not need to set this to attach a debugger, but setting this value has two effects:

It will prevent Android from throwing an error if you pause on a breakpoint for a long time while debugging.

It will enable you to select the Wait for Debugger option to pause application startup until your debugger attaches (described next).

• Wait for debugger Blocks the selected application from loading until a debugger attaches. This way you can set a breakpoint in onCreate(), which is important to debug the startup process of an Activity. When you change this option, any currently running instances of the selected application will be killed. In order to check this box, you must have selected a debug application as described in the previous option. You can do the same thing by adding waitForDebugger() to your code.
• Immediately destroy activities Tells the system to destroy an activity as soon as it is stopped (as if Android had to reclaim memory). This is very useful for testing the onFreeze(Bundle) / onCreate(android.os.Bundle) code path, which would otherwise be difficult to force. Choosing this option will probably reveal a number of problems in your application due to not saving state.
• Show screen updates Flashes a momentary pink rectangle on any screen sections that are being redrawn. This is very useful for discovering unnecessary screen drawing.
• Show CPU usage Displays CPU meters at the top of the screen, showing how much the CPU is being used. The top red bar shows overall CPU usage, and the green bar underneath it shows the CPU time spent in compositing the screen. Note: You cannot turn this feature off once it is on, without restarting the emulator.
• Show screen FPS Displays the current frame rate. Mostly useful for games to see the overall frame rate they are achieving. Note: You cannot turn this feature off once it is on without restarting the emulator.
• Show background Displays a background pattern when no activity screens are visible. This typically does not happen, but can happen during debugging.