Cheap VPS & Xen Server

Residential Proxy Network - Hourly & Monthly Packages

Setting Up An Android App Build Environment With Eclipse, Android SDK, PhoneGap (Ubuntu 10.10)


This tutorial describes how you can set up a development environment for building Android apps on an Ubuntu 10.10 desktop using Eclipse, the Android SDK, and PhoneGap. I will describe how to build Android apps from the command line with PhoneGap and from the GUI with Eclipse and PhoneGap and how to test them in an Android emulator and on a real Android device. PhoneGap allows you to develop your Android applications using web technologies such as HTML, CSS, and JavaScript (e.g. with JavaScript libraries such as jQuery/jQTouch), and it will turn these web apps into native Android apps (in fact, PhoneGap supports multiple platforms such as Android, iPhone, Palm, Windows Mobile, Symbian, so you can use the same sources to create apps for multiple platforms).

I do not issue any guarantee that this will work for you!

 

1 Preliminary Note

I will not explain how to develop an Android app using HTML, CSS, and JavaScript. You can find lots of tutorials about this on the Internet, e.g. this one:

Tutorial: A simple Twitter client with JQTouch

In fact, I’m using a slightly modified version of the Twitter client described in the link to build a Twitter app in this tutorial.

 

2 Installing Eclipse And Prerequisites For The Android SDK/PhoneGap

First open a terminal (Applications > Accessories > Terminal):

1

Eclipse and the prerequisites for the Android SDK and PhoneGap can be installed as follows:

sudo apt-get install openjdk-6-jdk eclipse ruby rubygems ruby-dev git ant libxml2 libxml2-dev libxslt-dev

Next run

sudo gem install nokogiri

 

3 Installing The Android SDK

Open Firefox and go to http://developer.android.com/sdk/index.html. There you will find links for the Android SDK for the different platforms (Windows, Mac OS X, Linux). Copy the link location of the download for Linux (i386) (don’t worry, this download works on both i386 and x86_64 platforms!)…

2

… and download and uncompress it as follows:

cd ~
wget http://dl.google.com/android/android-sdk_r08-linux_86.tgz
tar xvfz android-sdk_r08-linux_86.tgz

This will give you the directory android-sdk-linux_86 in your home directory ($HOME). We must add the $HOME/android-sdk-linux_86/tools directory and the $HOME/android-sdk-linux_86/platform-tools directory to our PATH variable which we do as follows:

Open ~/.profile

gedit ~/.profile

… and add the following line at the bottom of the file:

[...]
PATH="$HOME/android-sdk-linux_86/tools:$HOME/android-sdk-linux_86/platform-tools:$PATH"

To make the change effective (so that we don’t have to log out and back in), run:

export PATH=”$HOME/android-sdk-linux_86/tools:$HOME/android-sdk-linux_86/platform-tools:$PATH”

Now start the Android SDK:

android

This is how the Android SDK looks:

3

Select Available packages in the left panel and then select Android Repository in the right panel to download SDK packages:

4

The packages that belong to the Android Repository group should now all be checked. Click on the Install Selected button:

5

A new window opens; mark the Accept radio box and click on Install

6

… to start the download of the SDK packages:

7

If ADB (Android Debug Bridge) needs to be restarted, click on Yes:

8

Click on Close after the download has finished – this will close the download window:

9

4 Integrating The Android SDK Into Eclipse

If you want to use Eclipse to create your Android apps instead of the command line, you need to integrate the Android SDK into Eclipse. To do this, start Eclipse (Applications > Programming > Eclipse):

10

Click on OK if you see the Workspace Launcher window (you can check the Use this as the default and do not ask again checkbox to not see this message anymore):

11

Now in Eclipse, go to Help > Install New Software…:

12

The Available Software window opens. Click on the Add… button:

13

A small Add Site window opens. Fill in the following values and click on OK:

  • Name: ADT Plugin
  • Location: https://dl-ssl.google.com/android/eclipse/

14

Back in the Available Software window, you should now see the software Developer Tools. Select that software and click on Next >:

15

In the next window, click on Next > again:

16

Now accept the license agreements and click on Finish:

17

The packages needed to integrate the Android SDK into Eclipse are now being downloaded and installed:

18

If you see the following message about unsigned content, it’s ok to click on the OK button:

19

At the end of the installation, Eclipse needs to be restarted. To do this, click on Yes:

20

Now there’s one final step to complete the Android SDK integration in Eclipse: Go to Window > Preferences:

21

In the Preferences window, select Android in the left panel, and then click on the Browse… button that belongs to the SDK Location field in the right panel:

22

Select the directory where the Android SDK is located (it’s android-sdk-linux_86 in your home directory) and click on OK:

23

Back in the Preferences window, click on Apply (you should then see the supported Android versions in the Target Name column)…

24

… and then on OK:

25

5 Installing PhoneGap

To install PhoneGap, open Firefox and go to https://github.com/phonegap/phonegap-android. Click on the Downloads button:

26

Select Download .tar.gz from the overlay that comes up:

27

In the Firefox download dialogue, please choose Save File:

28

After the download has finished, go to the directory where the download has been saved (e.g. ~/Downloads/):

cd ~/Downloads/

Take a look at the directory’s contents to learn how the PhoneGap download is named:

ls -l

falko@falko-desktop:~/Downloads$ ls -l
total 11184
-rw-r–r– 1 falko falko 11452333 2011-01-24 15:40 phonegap-phonegap-android-0.9.3-21-gee01b50.tar.gz
falko@falko-desktop:~/Downloads$

As you see, in my case it is named phonegap-phonegap-android-0.9.3-21-gee01b50.tar.gz. Now lets uncompress the file:

tar xvfz phonegap-phonegap-android-0.9.3-21-gee01b50.tar.gz

In my case this creates the directory phonegap-phonegap-android-ee01b50 inside the Downloads directory. I want to move that directory to my home directory and rename it to phonegap-phonegap-android:

mv phonegap-phonegap-android-ee01b50 ~/phonegap-phonegap-android

We must add the bin directory inside $HOME/phonegap-phonegap-android to our PATH variable, therefore we edit ~/.profile again:

cd ~
gedit ~/.profile

Replace the previously added PATH variable with this one:

[...]
PATH="$HOME/android-sdk-linux_86/tools:$HOME/android-sdk-linux_86/platform-tools:$HOME/phonegap-phonegap-android/bin:$PATH"

To make the change effective, run:

export PATH=”$HOME/android-sdk-linux_86/tools:$HOME/android-sdk-linux_86/platform-tools:$HOME/phonegap-phonegap-android/bin:$PATH”

Now we are finished with setting up our Android development environment; finally we can start doing things with it!

 

6 Starting An Android Emulator

The Android SDK comes with an emulator so that you can test your apps in the emulator instead of on a real Android device. To create an emulator, we first need to know which Android versions (targets) are available:

android list targets

falko@falko-desktop:~$ android list targets
Available Android targets:
id: 1 or “android-3”
Name: Android 1.5
Type: Platform
API level: 3
Revision: 4
Skins: HVGA-L, HVGA-P, QVGA-L, HVGA (default), QVGA-P
id: 2 or “android-4”
Name: Android 1.6
Type: Platform
API level: 4
Revision: 3
Skins: WVGA854, WVGA800, HVGA (default), QVGA
id: 3 or “android-7”
Name: Android 2.1-update1
Type: Platform
API level: 7
Revision: 2
Skins: WVGA854, WQVGA432, WQVGA400, WVGA800, HVGA (default), QVGA
id: 4 or “android-8”
Name: Android 2.2
Type: Platform
API level: 8
Revision: 2
Skins: WVGA854, WQVGA432, WQVGA400, WVGA800, HVGA (default), QVGA
id: 5 or “android-9”
Name: Android 2.3
Type: Platform
API level: 9
Revision: 1
Skins: WVGA854, WQVGA432, WQVGA400, WVGA800, HVGA (default), QVGA
falko@falko-desktop:~$

I will now create an emulator called mySim for Android 2.2 (id 4 or android-8):

android create avd -n mySim -t android-8

(The emulator for Android 2.3 seems to be buggy; the apps I built for 2.3 crashed immediately after starting them, while they run fine on 2.2; therefore I use Android 2.2 here.)

falko@falko-desktop:~$ android create avd -n mySim -t android-8
Android 2.2 is a basic Android platform.
Do you wish to create a custom hardware profile [no]
<– ENTER
Created AVD ‘mySim’ based on Android 2.2,
with the following hardware config:
hw.lcd.density=160
falko@falko-desktop:~$

To start the emulator, run:

emulator -avd mySim

It can take a few minutes until the emulator is up and running, but then it should look as follows:

29

7 Creating An Android App

To build my Android app (which I call TweetMe) from its HTML, CSS, and JavaScript sources, I create a folder called tweetme in my home directory, and in that tweetme folder I place another folder called tweetme wich contains the sources (HTML, CSS, JavaScript):

HOME
|
|
+ tweetme
|
|
+tweetme
|
|
SOURCES (HTML, CSS, JavaScript)

Go to ~/tweetme/tweetme/:

cd ~/tweetme/tweetme/

You should see the HTML, CSS, JavaScript sources in that directory:

ls -l

falko@falko-desktop:~/tweetme/tweetme$ ls -l
total 96
-rw-r–r– 1 falko falko  4233 2011-01-24 00:20 index.html
drwxr-xr-x 2 falko falko  4096 2011-01-24 15:55 jqtouch
-rw-r–r– 1 falko falko 78601 2011-01-23 23:15 jquery.js
drwxr-xr-x 4 falko falko  4096 2011-01-24 15:55 themes
falko@falko-desktop:~/tweetme/tweetme$

Now we can create an app either from the command line or by using Eclipse:

 

7.1 Creating An Android App From The Command Line

In the ~/tweetme/tweetme/ directory, run:

droidgap create

(If you get the error message droidgap: command not found, please run

export PATH=”$HOME/android-sdk-linux_86/tools:$HOME/android-sdk-linux_86/platform-tools:$HOME/phonegap-phonegap-android/bin:$PATH”

and try again. )

This will create the directory ~/tweetme/tweetme_android which contains everything we need to build our final app from it. The ~/tweetme/tweetme_android/assets/www/ directory contains our HTML, CSS, JavaScript sources plus the phonegap.js file.

cd ../tweetme_android/

ls -l

falko@falko-desktop:~/tweetme/tweetme_android$ ls -l
total 44
-rw-r–r– 1 falko falko 2000 2011-01-24 18:43 AndroidManifest.xml
drwxr-xr-x 3 falko falko 4096 2011-01-24 18:43 assets
drwxr-xr-x 2 falko falko 4096 2011-01-24 18:43 bin
-rw-r–r– 1 falko falko  696 2011-01-24 18:43 build.properties
-rw-r–r– 1 falko falko 3201 2011-01-24 18:43 build.xml
-rw-r–r– 1 falko falko  362 2011-01-24 18:43 default.properties
drwxr-xr-x 2 falko falko 4096 2011-01-24 18:43 libs
-rw-r–r– 1 falko falko  424 2011-01-24 18:43 local.properties
-rw-r–r– 1 falko falko 1034 2011-01-24 18:43 proguard.cfg
drwxr-xr-x 7 falko falko 4096 2011-01-24 18:43 res
drwxr-xr-x 3 falko falko 4096 2011-01-24 18:43 src
falko@falko-desktop:~/tweetme/tweetme_android$

ls -l assets/www/

falko@falko-desktop:~/tweetme/tweetme_android$ ls -l assets/www/
total 200
-rw-r–r– 1 falko falko   4311 2011-01-24 15:59 index.html
drwxr-xr-x 2 falko falko   4096 2011-01-24 15:57 jqtouch
-rw-r–r– 1 falko falko  78601 2011-01-24 15:57 jquery.js
-rw-r–r– 1 falko falko 105761 2011-01-24 15:57 phonegap.js
drwxr-xr-x 4 falko falko   4096 2011-01-24 15:57 themes
falko@falko-desktop:~/tweetme/tweetme_android$

The libs/ directory contains the file phonegap.jar:

ls -l libs/

falko@falko-desktop:~/tweetme/tweetme_android$ ls -l libs/
total 120
-rw-r–r– 1 falko falko 122227 2011-01-24 15:57 phonegap.jar
falko@falko-desktop:~/tweetme/tweetme_android$

Now we must edit the index.html file in the assets/www/ folder and add the phonegap.js file to the <head></head> section (before all other JavaScript files/JavaScript code).

gedit assets/www/index.html

Lets assume the file starts as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Tweetme</title>

    <!-- include JQuery through Google API => Always have the latest version -->
    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript"> google.load("jquery", "1.3.2"); </script>

    <!-- import JQTouch -->
    <script src="jqtouch/jqtouch.min.js" type="application/x-javascript" charset="utf-8"></script>

    <!-- Import JQTouch default style (iPhone look).
       Replace the string "themes/apple" with "themes/jq" for a non-iPhone theme -->
    <link type="text/css" rel="stylesheet" media="screen" href="jqtouch/jqtouch.css">
    <link type="text/css" rel="stylesheet" media="screen" href="themes/apple/theme.css">
[...]

Add the line <script type=”text/javascript” charset=”utf-8″ src=”phonegap.js”></script> before all other JavaScript so that it looks as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Tweetme</title>
    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <!-- include JQuery through Google API => Always have the latest version -->
    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript"> google.load("jquery", "1.3.2"); </script>

    <!-- import JQTouch -->
    <script src="jqtouch/jqtouch.min.js" type="application/x-javascript" charset="utf-8"></script>

    <!-- Import JQTouch default style (iPhone look).
       Replace the string "themes/apple" with "themes/jq" for a non-iPhone theme -->
    <link type="text/css" rel="stylesheet" media="screen" href="jqtouch/jqtouch.css">
    <link type="text/css" rel="stylesheet" media="screen" href="themes/apple/theme.css">
[...]

Now, still in the ~/tweetme/tweetme_android directory, we can finally build our app:

ant debug

It should say BUILD SUCCESSFUL at the end:


-package-debug-sign:
[apkbuilder] Creating tweetme-debug-unaligned.apk and signing it with a debug key…

debug:
[echo] Running zip align on final apk…
[echo] Debug Package: /home/falko/tweetme/tweetme_android/bin/tweetme-debug.apk

BUILD SUCCESSFUL
Total time: 28 seconds
falko@falko-desktop:~/tweetme/tweetme_android$

You can now find your app in the bin/ directory (called tweetme-debug.apk; apk is the extension for Android apps):

cd bin/
ls -l

falko@falko-desktop:~/tweetme/tweetme_android/bin$ ls -l
total 764
drwxr-xr-x 3 falko falko   4096 2011-01-24 16:00 classes
-rw-r–r– 1 falko falko 140552 2011-01-24 16:01 classes.dex
-rw-r–r– 1 falko falko 166392 2011-01-24 16:01 tweetme.ap_
-rw-r–r– 1 falko falko 232458 2011-01-24 16:01 tweetme-debug.apk
-rw-r–r– 1 falko falko 232405 2011-01-24 16:01 tweetme-debug-unaligned.apk
falko@falko-desktop:~/tweetme/tweetme_android/bin$

To install it to the first running emulator, we can run

adb -e install -r tweetme-debug.apk

falko@falko-desktop:~/tweetme/tweetme_android/bin$ adb -e install -r tweetme-debug.apk
660 KB/s (232458 bytes in 0.343s)
pkg: /data/local/tmp/tweetme-debug.apk
Success
falko@falko-desktop:~/tweetme/tweetme_android/bin$

(Instead of running ant debug first and then adb -e install -r tweetme-debug.apk from the bin/ directory to install the app, we could have run

ant debug install

which would have built and afterwards installed the app in one go.)

Now go to your emulator, and you should find the new app listed among the other apps:

30

 

This is what the app looks like:

31

32

33

7.2 Creating An Android App From Eclipse

In the ~/tweetme/tweetme/ directory, run:

droidgap create

(If you get the error message droidgap: command not found, please run

export PATH=”$HOME/android-sdk-linux_86/tools:$HOME/android-sdk-linux_86/platform-tools:$HOME/phonegap-phonegap-android/bin:$PATH”

and try again. )

This will create the directory ~/tweetme/tweetme_android which contains everything we need to build our final app from it. The ~/tweetme/tweetme_android/assets/www/ directory contains our HTML, CSS, JavaScript sources plus the phonegap.js file.

cd ../tweetme_android/

ls -l

falko@falko-desktop:~/tweetme/tweetme_android$ ls -l
total 44
-rw-r–r– 1 falko falko 2000 2011-01-24 18:43 AndroidManifest.xml
drwxr-xr-x 3 falko falko 4096 2011-01-24 18:43 assets
drwxr-xr-x 2 falko falko 4096 2011-01-24 18:43 bin
-rw-r–r– 1 falko falko  696 2011-01-24 18:43 build.properties
-rw-r–r– 1 falko falko 3201 2011-01-24 18:43 build.xml
-rw-r–r– 1 falko falko  362 2011-01-24 18:43 default.properties
drwxr-xr-x 2 falko falko 4096 2011-01-24 18:43 libs
-rw-r–r– 1 falko falko  424 2011-01-24 18:43 local.properties
-rw-r–r– 1 falko falko 1034 2011-01-24 18:43 proguard.cfg
drwxr-xr-x 7 falko falko 4096 2011-01-24 18:43 res
drwxr-xr-x 3 falko falko 4096 2011-01-24 18:43 src
falko@falko-desktop:~/tweetme/tweetme_android$

ls -l assets/www/

falko@falko-desktop:~/tweetme/tweetme_android$ ls -l assets/www/
total 200
-rw-r–r– 1 falko falko   4311 2011-01-24 15:59 index.html
drwxr-xr-x 2 falko falko   4096 2011-01-24 15:57 jqtouch
-rw-r–r– 1 falko falko  78601 2011-01-24 15:57 jquery.js
-rw-r–r– 1 falko falko 105761 2011-01-24 15:57 phonegap.js
drwxr-xr-x 4 falko falko   4096 2011-01-24 15:57 themes
falko@falko-desktop:~/tweetme/tweetme_android$

The libs/ directory contains the file phonegap.jar:

ls -l libs/

falko@falko-desktop:~/tweetme/tweetme_android$ ls -l libs/
total 120
-rw-r–r– 1 falko falko 122227 2011-01-24 15:57 phonegap.jar
falko@falko-desktop:~/tweetme/tweetme_android$

Now open Eclipse and go to New > Project…:

34

In the New Project window, select Android > Android Project and click on Next >:

35

In the New Android Project window, select Create project from existing source (we have previously created the source by running droidgap create) and click on the Browse… button – don’t fill out any other fields in that window:

36

Select the ~/tweetme/tweetme_android directory and click on OK:

37

Back in the New Android Project window, all other fields should now be filled. Click on Finish:

39

Add the phonegap.js file to the <head></head> section (before all other JavaScript files/JavaScript code).

Lets assume the file starts as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Tweetme</title>

    <!-- include JQuery through Google API => Always have the latest version -->
    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript"> google.load("jquery", "1.3.2"); </script>

    <!-- import JQTouch -->
    <script src="jqtouch/jqtouch.min.js" type="application/x-javascript" charset="utf-8"></script>

    <!-- Import JQTouch default style (iPhone look).
       Replace the string "themes/apple" with "themes/jq" for a non-iPhone theme -->
    <link type="text/css" rel="stylesheet" media="screen" href="jqtouch/jqtouch.css">
    <link type="text/css" rel="stylesheet" media="screen" href="themes/apple/theme.css">
[...]

Add the line <script type=”text/javascript” charset=”utf-8″ src=”phonegap.js”></script> before all other JavaScript so that it looks as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Tweetme</title>
    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <!-- include JQuery through Google API => Always have the latest version -->
    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript"> google.load("jquery", "1.3.2"); </script>

    <!-- import JQTouch -->
    <script src="jqtouch/jqtouch.min.js" type="application/x-javascript" charset="utf-8"></script>

    <!-- Import JQTouch default style (iPhone look).
       Replace the string "themes/apple" with "themes/jq" for a non-iPhone theme -->
    <link type="text/css" rel="stylesheet" media="screen" href="jqtouch/jqtouch.css">
    <link type="text/css" rel="stylesheet" media="screen" href="themes/apple/theme.css">
[...]

Now save the file.

40

 

Next right-click the libs/phonegap.jar file and select Build Path > Add to Build Path:

41

Now right-click the root of our source tree, tweetme, and select Run As > Android Application:

 

43

8 Using A Real Android Device

If you have a real Android smartphone and want to test your app on this device instead of the emulator, you have to first enable USB debugging on the device (Menu > Settings > Applications > Development > USB-Debugging) and then plug it into your Ubuntu desktop using the device’s USB cable.

Now check if Ubuntu has correctly identified the device:

adb devices

If you see a lot of question marks like this…

falko@falko-desktop:~$ adb devices
List of devices attached
????????????        no permissions

falko@falko-desktop:~$

… then Ubuntu did not identify your device. In this case create the file /etc/udev/rules.d/51-android.rules

sudo gedit /etc/udev/rules.d/51-android.rules

… with the following contents:

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

Replace 0bb4 (this is for HTC phones) with the correct vendor ID which you can find here: http://developer.android.com/guide/developing/device.html#VendorIds

Then run:

sudo chmod a+r /etc/udev/rules.d/51-android.rules

Plug out your phone and plug it back in, and Ubuntu should now recognize it:

adb devices

falko@falko-desktop:~$ adb devices
List of devices attached
SH0ARPL12791        device

falko@falko-desktop:~$

If you have your app as an apk file, you can now install it onto your phone as follows:

adb -d install -r tweetme-debug.apk

(Please note that I use -d (for device) instad of -e (for emulator) here.)

 

  • Eclipse: http://www.eclipse.org/
  • Android SDK: http://developer.android.com/sdk/index.html
  • PhoneGap: http://www.phonegap.com/
  • Ubuntu: http://www.ubuntu.com/
  • jQuery: http://jquery.com/
  • jQTouch: http://www.jqtouch.com/
  • Tutorial: A simple Twitter client with JQTouch: http://www.timo-ernst.net/2010/08/tutorial-a-simple-twitter-client-with-jqtouch/

 

 

 

 

 

 

 

 

 

Comments

comments