Using the Android SDK tools

Introduction

The main supported Android development "platform" is Eclipse. It doesn't mean that you have to use Eclipse, if you want to develop Android apps, though. Android can be also used without Eclipse. This tutorial is meant to be a guide for all those, who would like to develop Android apps without using the Eclipse IDE.

Please note, that this tutorial is not a complete guide. There are some unanswered questions, as well as some unasked ones. I hope to improve it as soon as I got the needed knowledge.

Creating the LunarLander sample project

We'll try to make the LunarLander sample from the Android SDK running on the Android emulator. The LunarLander sample distributed with the Android SDK contains of two directories: res (with resources) and src (with Java sources), and of two files: AndroidManifest.xml and sample_lunarlander.png (the main screen image).

The simplest way to make this sample up and running on the Android emulator is to create a new Android project using the android tool. You can read more about this tool on the official Android help pages Developing in other IDEs The short story is that you will need to call android update project --target 1 --path <path to LunarLander example>. This will create the needed build.xml inside the example directory.

The old way is a little bit more complex and will use the activitycreator tool. This program needs two parameters: the directory, where all the project files should be placed, and the name of the main Android application activity class. The directory can be chosen arbitrarily, although I think it shouldn't be the directory where the LunarLander sample is already placed (since I'm not sure whether the activitycreator program overwrites the existing files; that's isn't what we want it to do!).

The main activity class of the LunarLander sample can be found by inspecting the Java source files placed in the src directory of the LunarLander sample. The LunarLander consists of only two source files: LunarLander.java and LunarView.java. The most interesting part of the LunarLander.java file is as follows:

(...)
package com.example.android.lunarlander;
(...)
public class LunarLander extends Activity {
(...)

So, the main activity class of the LunarLander sample is com.example.android.lunarlander.LunarLander.

Now, we have all information needed to create a new Android project: just execute the command

> activitycreator --out LunarLanderProject com.example.android.lunarlander.LunarLander

Moving the project sources to the right place

The activitycreator program is supposed to be used when a new, empty Android project should be created, and that's exactly what it does. In our case, though, the project is already finished and all we want to do is to build it and test on the Android emulator. So, we have to copy all the LunarLander sample files to the newly created project's directory. Note, that some files will be overwritten, and it is exactly what we want.

Building the project

Since the android or activitycreator generated the build.xml file, we can use ant to do the job for us. There are several targets which can be used to build the project. One of them is debug:

> ant debug

This target generates the LunarLander-debug.apk file. You don't have to sign this file in order to successfully install it on the Android emulator.

Another target for building the project is release:

> ant release

This target generates the LunarLander-unsigned.apk file. You have to sign this file before installing it on the Android emulator.

Of course, these commands should be executed from the directory of our LunarLander project. After performing this task, the mentioned files should be available in the bin directory.

Creating keys for signing Android apps

Although this material doesn't belong here (since the topic itself isn't Android-specific), I think it will be helpful for people starting their adventure with Android to have it here. The following instructions are based on material that can be found on this webpage.

If we want to install our packages on the Android emulator, we will have to sign them. It's a quite simple procedure: first we'll need a key. We can generate it using tools from Java SDK. Let's just create a directory to store our key (let's suppose it's C:\YourKey) and execute the following command:

> keytool -genkey -alias your.key.alias -keyalg RSA \
          -validity 20000 -keystore C:\YourKey\your.key.file

We'll have to answer some questions, and enter the password for our key. After the command is finished, the file with our key should be present in the C:\YourKey directory.

Please note, that in the command above I assume we have the bin directory of our Java SDK in our PATH.

Signing the Android packages

Once we have a key, we can sign our Android package and install it on the emulator. It can be done with a single command:

> jarsigner -verbose -keystore "C:\YourKey\your.key.file" \
            -signedjar bin\LunarLander-signed.apk \
            bin\LunarLander-unsigned.apk your.key.alias

Of course, the command above should be executed in the LunarLander project's directory.

Running the emulator

Before the created package will be installed, we need to start the Android emulator. Go to the Android tools directory (the one, when all the Android tools files are placed), and run the command:

> emulator.exe -datadir path\to\some\datadir

WindowsXP: For some reason, I was able to run the emulator from the Android tools directory only. So, it's neccessary to change your working directory to the Android tools one before starting the emulator using the command presented above.

The -datadir path\to\some\datadir is a crucial part of the command: without it emulator won't be started. The directory is needed for the image file used by the emulator. All the packages will be installed to this image file. (So, after restarting the emulator using the same data directory, all the installed packages will be still available in the emulator).

Installing the package

The emulator is up and running, so we can install the built package on it. This activity is performed with the adb tool:

> adb install bin\LunarLander-debug.apk

Note, that the command presented above is supposed to be executed from the LunarLander project's directory.

After the LunarLander package has been installed on the running emulator, the game can be started. Just go to the Android's menu, find the LunarLander icon and start it!

WindowsXP: It's also possible to install the package using ant (the target name is "install"), but the ant script doesn't end after the package is installed. I don't like and I don't use it.

Uninstalling Android packages

All the installed packages can be removed from the emulator using the adb program. First, we should run the shell:

> adb shell
#

The # sign is the shell prompt we should wait for. When the shell is ready, we have to go to the packages directory:

# cd /data/app

Now, we have to find out the files in this directory:

# ls
com.example.android.lunarlander.apk
ApiDemos.apk

As we can see, our LunarLander project is there. We can remove it ("uninstall") with the command:

# rm com.example.android.lunarlander.apk

The shell session can be finished with the exit command.

When we know the name of the package to uninstall, it can be done with single command. For example, in our case we could've done:

> adb shell rm /data/app/com.example.android.lunarlander.apk

or

> adb uninstall com.example.android.lunarlander

Problems

When building you might run into the Unable to get buffer of resource asset file error. The root cause of this is that the new android resource file resources.arsc is larger than the aapt tool allows. You can exchange the .arsc file inside android.jar with an older version or patch the aapt tool by editing frameworks/base/include/utils/Asset.h.

Change both lines UNCOMPRESS_DATA_MAX = 1 * 1024 * 1024 to something bigger. As the new resources file currently has a size of 2.3Mb you should change the lines (both lines mind you) to at least 3*1024*1024.