Sunday, July 3, 2011

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


This tutorial describes how you can set up an development environment for building Android apps on an Ubuntu 11.04 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. You can download my modified version from here: http://downloads.howtoforge.com/android_build_environment/tweetme.zip
I'm working with the Ubuntu Classic desktop here (GNOME); the steps should almost be identical if you use Unity.

2 Installing Eclipse And Prerequisites For The Android SDK/PhoneGap

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

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 libnokogiri-ruby git ant libxml2 libxml2-dev libxslt1-dev
If you are on a 64bit system, you also need to install the following two packages:
sudo apt-get install lib32stdc++6 ia32-libs
 

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!)...


... and download and uncompress it as follows:
cd ~
wget http://dl.google.com/android/android-sdk_r11-linux_x86.tgz
tar xvfz android-sdk_r11-linux_x86.tgz
This will give you the directory android-sdk-linux_x86 in your home directory ($HOME). We must add the $HOME/android-sdk-linux_x86/tools directory and the $HOME/android-sdk-linux_x86/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_x86/tools:$HOME/android-sdk-linux_x86/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_x86/tools:$HOME/android-sdk-linux_x86/platform-tools:$PATH"
Now start the Android SDK:
android
This is how the Android SDK looks:


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


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


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


... to start the download of the SDK packages:


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


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


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):


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):


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


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


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/


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


In the next window, click on Next > again:


Now accept the license agreements and click on Finish:


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


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


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


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


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:


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


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


... and then on OK:



5 Installing PhoneGap

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


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


In the Firefox download dialogue, please choose Save File:


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-virtual-machine:~/Downloads$ ls -l
total 11200
-rw-r--r-- 1 falko falko 11467178 2011-06-21 14:01 phonegap-phonegap-android-0.9.5.1-15-g939754e.tar.gz
falko@falko-virtual-machine:~/Downloads$
As you see, in my case it is named phonegap-phonegap-android-0.9.5.1-15-g939754e.tar.gz. Now lets uncompress the file:
tar xvfz phonegap-phonegap-android-0.9.5.1-15-g939754e.tar.gz
In my case this creates the directory phonegap-phonegap-android-939754e 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-939754e ~/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_x86/tools:$HOME/android-sdk-linux_x86/platform-tools:$HOME/phonegap-phonegap-android/bin:$PATH"
To make the change effective, run:
export PATH="$HOME/android-sdk-linux_x86/tools:$HOME/android-sdk-linux_x86/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-virtual-machine:~$ android list targets
Available Android targets:
id: 1 or "android-3"
     Name: Android 1.5
     Type: Platform
     API level: 3
     Revision: 4
     Skins: HVGA (default), QVGA-L, HVGA-P, HVGA-L, QVGA-P
id: 2 or "android-4"
     Name: Android 1.6
     Type: Platform
     API level: 4
     Revision: 3
     Skins: HVGA, QVGA, WVGA854, WVGA800 (default)
id: 3 or "android-7"
     Name: Android 2.1-update1
     Type: Platform
     API level: 7
     Revision: 2
     Skins: HVGA, QVGA, WQVGA400, WVGA854, WQVGA432, WVGA800 (default)
id: 4 or "android-8"
     Name: Android 2.2
     Type: Platform
     API level: 8
     Revision: 2
     Skins: HVGA, QVGA, WQVGA400, WVGA854, WQVGA432, WVGA800 (default)
id: 5 or "android-10"
     Name: Android 2.3.3
     Type: Platform
     API level: 10
     Revision: 1
     Skins: HVGA, QVGA, WQVGA400, WVGA854, WQVGA432, WVGA800 (default)
id: 6 or "android-11"
     Name: Android 3.0
     Type: Platform
     API level: 11
     Revision: 1
     Skins: WXGA (default)
id: 7 or "android-12"
     Name: Android 3.1
     Type: Platform
     API level: 12
     Revision: 2
     Skins: WXGA (default)
falko@falko-virtual-machine:~$
I will now create an emulator called mySim for Android 2.3.3 (id 5 or android-10):
android create avd -n mySim -t android-10
falko@falko-virtual-machine:~$ android create avd -n mySim -t android-10
Android 2.3.3 is a basic Android platform.
Do you wish to create a custom hardware profile [no] <-- ENTER
Created AVD 'mySim' based on Android 2.3.3,
with the following hardware config:
hw.lcd.density=240
vm.heapSize=24
hw.ramSize=256
falko@falko-virtual-machine:~$
To start the emulator, run:
emulator -avd mySim -scale 0.75
It can take a few minutes until the emulator is up and running, but then it should look as follows:


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-virtual-machine:~/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-06-21 14:23 jqtouch
-rw-r--r-- 1 falko falko 78601 2011-01-23 23:15 jquery.js
drwxr-xr-x 4 falko falko  4096 2011-06-21 14:23 themes
falko@falko-virtual-machine:~/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_x86/tools:$HOME/android-sdk-linux_x86/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-virtual-machine:~/tweetme/tweetme_android$ ls -l
total 44
-rw-r--r-- 1 falko falko 2241 2011-06-21 14:25 AndroidManifest.xml
drwxr-xr-x 3 falko falko 4096 2011-06-21 14:25 assets
drwxr-xr-x 2 falko falko 4096 2011-06-21 14:25 bin
-rw-r--r-- 1 falko falko  696 2011-06-21 14:25 build.properties
-rw-r--r-- 1 falko falko 2891 2011-06-21 14:25 build.xml
-rw-r--r-- 1 falko falko  363 2011-06-21 14:25 default.properties
drwxr-xr-x 2 falko falko 4096 2011-06-21 14:25 libs
-rw-r--r-- 1 falko falko  425 2011-06-21 14:25 local.properties
-rw-r--r-- 1 falko falko 1159 2011-06-21 14:25 proguard.cfg
drwxr-xr-x 7 falko falko 4096 2011-06-21 14:25 res
drwxr-xr-x 3 falko falko 4096 2011-06-21 14:25 src
falko@falko-virtual-machine:~/tweetme/tweetme_android$
ls -l assets/www/
falko@falko-virtual-machine:~/tweetme/tweetme_android$ ls -l assets/www/
total 228
-rw-r--r-- 1 falko falko   4233 2011-06-21 14:25 index.html
drwxr-xr-x 2 falko falko   4096 2011-06-21 14:25 jqtouch
-rw-r--r-- 1 falko falko  78601 2011-06-21 14:25 jquery.js
-rw-r--r-- 1 falko falko 132955 2011-06-21 14:25 phonegap.0.9.5.js
drwxr-xr-x 4 falko falko   4096 2011-06-21 14:25 themes
falko@falko-virtual-machine:~/tweetme/tweetme_android$
Important: I found a problem with the phonegap.0.9.5.js file - it contains several lines with a prompt() function that asks the user some questions (it asks for getPort, getToken, getServer, restartServer, usePolling), and this is clearly not what you want inside your app - see the following screenshots:










As a solution for this problem, you can either edit phonegap.0.9.5.js and comment out all lines that contain the prompt() function (there are six lines), or you download PhoneGap 0.9.4 from http://phonegap.googlecode.com/files/phonegap-0.9.4.zip (PhoneGap 0.9.4 doesn't use the prompt() function), extract the phonegap.0.9.4.js file from it, delete phonegap.0.9.5.js from the assets/www/ directory and place phonegap.0.9.4.js in the assets/www/ directory instead.
If you prefer to comment out all lines that contain the prompt() function in phonegap.0.9.5.js, but don't want to edit the file manually, you can use the following command which comments out all six lines automatically (the command works fine for phonegap.0.9.5.js; however, it might not work for future versions, so please keep this in mind!):
sed -i '/prompt/s;^;//;' assets/www/phonegap.0.9.5.js
The libs/ directory contains the file phonegap..jar:
ls -l libs/
falko@falko-virtual-machine:~/tweetme/tweetme_android$ ls -l libs/
total 136
-rw-r--r-- 1 falko falko 139004 2011-06-21 14:25 phonegap.0.9.5.jar
falko@falko-virtual-machine:~/tweetme/tweetme_android$
Now we must edit the index.html file in the assets/www/ folder and add the phonegap..js file to the section (before all other JavaScript files/JavaScript code).
gedit assets/www/index.html
Let's assume the file starts as follows: 

    

    
    

    
[...]
Add the line before all other JavaScript so that it looks as follows (if you have replaced phonegap.0.9.5.js with phonegap.0.9.4.js, please use the line instead ): 

    
    
    

    
    

    
[...]
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: 38 seconds
falko@falko-virtual-machine:~/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-virtual-machine:~/tweetme/tweetme_android/bin$ ls -l
total 808
drwxr-xr-x 3 falko falko   4096 2011-06-21 14:32 classes
-rw-r--r-- 1 falko falko 155652 2011-06-21 14:32 classes.dex
-rw-r--r-- 1 falko falko 171877 2011-06-21 14:32 tweetme.ap_
-rw-r--r-- 1 falko falko 244900 2011-06-21 14:32 tweetme-debug.apk
-rw-r--r-- 1 falko falko 244846 2011-06-21 14:32 tweetme-debug-unaligned.apk
falko@falko-virtual-machine:~/tweetme/tweetme_android/bin$
To install it to the first running emulator, we can run
adb -e install -r tweetme-debug.apk
falko@falko-virtual-machine:~/tweetme/tweetme_android/bin$ adb -e install -r tweetme-debug.apk
411 KB/s (244900 bytes in 0.581s)
        pkg: /data/local/tmp/tweetme-debug.apk
Success
falko@falko-virtual-machine:~/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:


This is what the app looks like:






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_x86/tools:$HOME/android-sdk-linux_x86/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-virtual-machine:~/tweetme/tweetme_android$ ls -l
total 44
-rw-r--r-- 1 falko falko 2241 2011-06-21 14:25 AndroidManifest.xml
drwxr-xr-x 3 falko falko 4096 2011-06-21 14:25 assets
drwxr-xr-x 2 falko falko 4096 2011-06-21 14:25 bin
-rw-r--r-- 1 falko falko  696 2011-06-21 14:25 build.properties
-rw-r--r-- 1 falko falko 2891 2011-06-21 14:25 build.xml
-rw-r--r-- 1 falko falko  363 2011-06-21 14:25 default.properties
drwxr-xr-x 2 falko falko 4096 2011-06-21 14:25 libs
-rw-r--r-- 1 falko falko  425 2011-06-21 14:25 local.properties
-rw-r--r-- 1 falko falko 1159 2011-06-21 14:25 proguard.cfg
drwxr-xr-x 7 falko falko 4096 2011-06-21 14:25 res
drwxr-xr-x 3 falko falko 4096 2011-06-21 14:25 src
falko@falko-virtual-machine:~/tweetme/tweetme_android$
ls -l assets/www/
falko@falko-virtual-machine:~/tweetme/tweetme_android$ ls -l assets/www/
total 228
-rw-r--r-- 1 falko falko   4233 2011-06-21 14:25 index.html
drwxr-xr-x 2 falko falko   4096 2011-06-21 14:25 jqtouch
-rw-r--r-- 1 falko falko  78601 2011-06-21 14:25 jquery.js
-rw-r--r-- 1 falko falko 132955 2011-06-21 14:25 phonegap.0.9.5.js
drwxr-xr-x 4 falko falko   4096 2011-06-21 14:25 themes
falko@falko-virtual-machine:~/tweetme/tweetme_android$
Important: I found a problem with the phonegap.0.9.5.js file - it contains several lines with a prompt() function that asks the user some questions (it asks for getPort, getToken, getServer, restartServer, usePolling), and this is clearly not what you want inside your app - see the following screenshots:










As a solution for this problem, you can either edit phonegap.0.9.5.js and comment out all lines that contain the prompt() function (there are six lines), or you download PhoneGap 0.9.4 from http://phonegap.googlecode.com/files/phonegap-0.9.4.zip (PhoneGap 0.9.4 doesn't use the prompt() function), extract the phonegap.0.9.4.js file from it, delete phonegap.0.9.5.js from the assets/www/ directory and place phonegap.0.9.4.js in the assets/www/ directory instead.
If you prefer to comment out all lines that contain the prompt() function in phonegap.0.9.5.js, but don't want to edit the file manually, you can use the following command which comments out all six lines automatically (the command works fine for phonegap.0.9.5.js; however, it might not work for future versions, so please keep this in mind!):
sed -i '/prompt/s;^;//;' assets/www/phonegap.0.9.5.js
The libs/ directory contains the file phonegap..jar:
ls -l libs/
falko@falko-virtual-machine:~/tweetme/tweetme_android$ ls -l libs/
total 136
-rw-r--r-- 1 falko falko 139004 2011-06-21 14:25 phonegap.0.9.5.jar
falko@falko-virtual-machine:~/tweetme/tweetme_android$
Now open Eclipse and go to File > New > Project...:


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


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:


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


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


You should now see the source tree of your app in the left panel in Android. Right-click the assets/www/index.html file and select Open With > Text Editor:

Add the phonegap..js file to the section (before all other JavaScript files/JavaScript code).
Let's assume the file starts as follows: 

    

    
    

    
[...]
Add the line before all other JavaScript so that it looks as follows (if you have replaced phonegap.0.9.5.js with phonegap.0.9.4.js, please use the line instead ): 

    
    
    

    
    

    
[...]
Now save the file.


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


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


This will open our emulator and automatically start our app:



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-virtual-machine:~$ adb devices
List of devices attached
????????????    no permissions

falko@falko-virtual-machine:~$
... 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-virtual-machine:~$ adb devices
List of devices attached
SH0ARPL12791    device

falko@falko-virtual-machine:~$
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.)

9 Links


Posted by at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)