Android: On using Android Support Package

As Android keeps improving and Google comes up with new versions of Android SDK, new features get introduced into Android (some call it the "Fragmentation" issue in Android SDK). As a developer, soon or late you will come across features in newer versions of SDK which you wish you could have used in your old code developed based on older versions of Android.


To make it possible for developers to use the new features of Android and still be able to run on older versions of Android, the Android "Support Package" has been introduced. Below some of typical examples on how this package can be used:

• You have written your Android application based on API level 4 (Android 1.6) but want to rewrite your code to start using Fragments (Introduced since API level 11, Andorid 3.0), and at the same time make sure your application keeps running on old Android devices running on Android 1.6. Using Android Support Package you can go ahead and rewrite your application using Fragments.
• You want to use some of those nifty UI patterns that were introduced later in Android (like NavUtils) . You can achieve this by adding the Support package into your existing code.
• You want to start managing some of your processes (which consume more time and are long-running actions) using the new Android utilities. You can integrate LoaderManager in combination with your Activities/Fragments by using the Support package.

Luckily Google has extensive details and sample code on how to integrate Android Support Package into your project. Check out the Support Package page on Android developers site for explanation and sample code.
Just to add some more useful hints on how to get the package and how to debug it with its own source code, below is a brief illustration together with screenshot.

How to get it

Easiest way is to use the Android SDK Manager. In Eclipse you can use the Android plugin to trigger the Android SDK Manager. Once Android SDK Manager is started, go to Extras, select "Android Support package", and install it.

How to get the Android Support Package from SDK Manager

Once installation is done, Support package is installed on your machine, together with sources and examples. At the current state Support package includes two versions; version 4 and version 13.

Available Support Packages, v4 and v13

See Support Package page on Android developers site for more details on differences between these two versions and when to choose what version.

How to include Android Support package as a user library

One alternative way to include the Support package to your project is to add it as a "user library" in your project. Screen shots below illustrate this.

Define a new user library

• Select the proper jar file to user library:

Assign the proper jar to user library

• After assigning the jar file, in order to make sure during debugging you will be able to debug in the source from Support package as well, we need to set the "Source attachement" property for this user library.

Added JAR, but source is not set yet

• Select "Source attachment:(None)" and click on "Edit" button on the right. In "Source Attachment Configuration" window, select "External Folder"

Assign source folder to user library for better debugging

• Once "Folder Selection" is opened. Browse to where SDK source is installed. Normally this can be found within android SDK installation directory, and in a folder called "extras/android/support/v13/src/". select the folder and click OK. click OK again.

Setting up the source attachment

This should do the trick. You can start refactoring your existing code to use new set of Android features. Happy hacking into it. 
Again, check out the Support Package page on Android developers site for more details and sample code to make life easier.

Android : On better debugging of your Android applications in Eclipse

One of the things I like when debugging code, let say in conventional Java applications, is the ability to debug into the external libraries with full "source code" visibility. Being able to look into source code of external libraries during debugging has it's own advantages:

1. I can set breakpoints on those code which are not mine, with full visibility to the actual source.
2. I can see the actual (external) code implementation, and verify values/variables during debugging (at runtime).
3. Learn more about other peoples code (most important one for me :) ).

Normally you need to do some pre-configuration in your project before you can have this "full code visibility" to external libraries. This pre-configuration includes:

1. Downloading the source code of external libraries. Most of the time the "source code" is available for download or already packaged in the library. A good example is JDK, which includes the source code already once you have it installed.
2. Configuring your project so it knows where to find the "source code" of these external libraries when debugging.

With Android, specially for folks working on Windows platform, having this setup and configured has not been that easy; for the following reasons:

1. Downloading Android source code has been pretty easy (using Git) for Apple and Linux users, but not that easy for developers using Windows platform.
2. Until Android 4.0 (API level 14), the source code was not included in Android package, e.g.  Android SDK source code could not be downloaded when using SDK Manager.

Below is a brief illustration on how to add Android source code in your project for better debugging and visibility. I have  added screenshots whenever possible (a picture is worth 1000 words), and hope this has made it easier.


Before starting, following assumptions has been made:

1. You already have an IDE/Development tool (in my case Eclipse) installed and running on your machine.
2. You have some basic knowledge of Android, such as how to install Android SDK, and how to setup an Android project.

I the following example, I have already created a simple Android project based on SDK 4.0.3 (API Level 15).

• Make sure you have already downloaded the Android SDK source code on your machine. Following screenshot illustrates the SDK Manager whereby "Sources for Android SDK" is checked. This makes sure source code is downloaded. 

Downloading SDK source code using Android SDK Manager

• From Eclipse main menu, select Project -> Properties
• On left pane, select "Java Build Path"

Project Build path and Libraries

• On the right pane select "Libraries" tab. Open the "Android 4.0.3".

Android SDK library and reference to the corresponding jar file

This is the SDK library your project is dependent on. You will see the android.jar and its settings once you open the android.jar property. As it can be seen, the property "Source attachment" is set to "None". Even though you have downloaded the source, project is not able to access it since by default the source is not attached to the external library.

• Select "Source attachment:(None)" and click on "Edit" button on the right. In "Source Attachment Configuration" window, select "External Folder".

Selecting the path where SDK source code is installed.

"Folder Selection" is opened. Browse to where SDK source is installed. Normally this can be found within android SDK installation directory, and in a folder called "sources". select the folder (in my case android-15) and click OK. click OK again.

Setting the proper Source Attachment

Back in the first panel, you should now see the property "Source Attachment" referring to the path where SDK source can be found.

This should be it. Now, you are able to browse Android SDK source when running in debug mode, or even just when browsing in your editor. Below a simple example where I am using the android.widget.Button class in my code. After clicking on class name mentioned in my code, I can right click it and select "Open Declaration" (shortcut F3 in Eclipse under Windows).

Navigating to Source (Open Declaration) of "android.widget.Button"

"android.widget.Button"  source class is displayed. 

Source of android.widget.Button

Happy debugging :). Feel free to drop me an email or leave a comment.

In the next post, I will focus on how to use "Android Compatibility Package" in your projects. This is used to introduce features of newer versions of Android SDK into older versions of Android.