Thursday, November 18, 2010

Building the Android IDE Tools

Do you want to try bleeding edge builds of the Android IDE tooling? No problem. We do all the tool development directly in a public git repository. Just build it, run it, and you can see all daily progress in our review tool.

Andy Rubin recently tweeted how to build Android - and as you can see, it's easy and the instructions fit within the 140 twitter character limit. However, if you want to work on the IDE tooling itself, there are many other tips and tricks to know about. The purpose of this blog entry is to document how you can set up an environment to build the Android SDK, including the IDE support, and have everything configured such that you can run and debug the Android support directly from within the IDE.

My hope is that some of you, once you have the Android tooling up and running, will decide to look under the covers, tinker with the bits, and hopefully find and fix bugs, or even contribute features! I'll talk more about contributions in a later blog post; today the focus is on building and running the bits even if you have no intention of contributing. Even bug reports from you on newly developed features would be useful.

Setup

First, you'll need to install the prerequisites for your platform. This means you'll have git, a C compiler, etc. There are quite a few steps here, and it's all platform dependent, so I'll just point you to the official build instructions where we have detailed instructions:  http://source.android.com/source/download.html .  If you're on a Mac, pay particular attention to the instructions on creating a case sensitive filesystem image. When I started I glossed over that part and hurried down to the git checkout command, only to discover later that I had to start over.

One other Mac specific tip, which isn't in the main Android page yet, is that Apple's recent JDK update "broke" the Android build on Snow Leopard since the build uses JNI. The location of the JNI header file changed or disappeared with the JDK update, so you now need to go to Apple and get the developer SDK, JavaDeveloper.pkg from http://connect.apple.com.

NOTE NOTE NOTE: Xavier tells me that building on Windows is more difficult because the SDK itself doesn't build on Windows, so you may have to download a system image and then build the tools components themselves manually. Hopefully I'll be able to provide more details on this soon.

Once you have everything configured, check out the source code using the first half of Andy Rubin's tweet:

$ mkdir android
$ cd android
$ repo init -u git://android.git.kernel.org/platform/manifest.git
$ repo sync


During the repo init command, it will ask you for your name and e-mail address; these will be used later if you decide to check in changesets and upload them for review.

Build

Now you are ready to build. While you could just type "make", this is where our SDK build instructions diverge a bit.

In a bash shell, run these commands

$ . build/envsetup.sh
$ lunch sdk-eng
$ make sdk
$ ./sdk/eclipse/scripts/create_all_symlinks.sh
That will run for quite a while and build everything. It will also create a lot of symlinks to help you edit and compile files within Eclipse.

Next, configure Eclipse. We support Eclipse 3.4 and up, but we're currently using Eclipse 3.5.2 for development. Make sure you get a version with RCP support, such as the "Eclipse for RCP and RAP Developers" distribution. I'm using eclipse-rcp-galileo-SR2-macosx-cocoa. (You can use Eclipse 3.6.1 - I just tried it. However, the test project won't compile. You won't need that project to run the Eclipse support. If you're going to be making changes you'll want to have it, but for now, if you're just wanting to try the new support and don't want to install an older Eclipse, go right ahead, and skip the "tests" project in the projects-to-import list below.)

To configure Eclipse, right click in the Workspace and choose "Import...", then select "Existing Projects into Workspace".  You want to import precisely these projects:
  • sdk/eclipse/plugins/com.android.ide.eclipse.adt
  • sdk/eclipse/plugins/com.android.ide.eclipse.tests
  • sdk/eclipse/plugins/com.android.ide.eclipse.ddms
  • sdk/ddms (import all 3 projects - ddmlib, ddms-plugin, ddmuilib)
  • sdk/ide_common
  • sdk/androidprefs
  • sdk/sdkstats
  • sdk/layoutlib_api

Things won't compile yet, until we finish the configuration.

Go to the Preferences panel, search for Classpath Variables, and define ANDROID_SRC pointing to the top of your source tree (e.g. the "android" dir in the tweet instructions).

Then right click on the ddmuilib project and open its properties. Go to Java > Build Path, and open the User Libraries tab. You should see ANDROID_JFREECHART and ANDROID_SWT as libraries there. These will need to be configured. For ANDROID_JFREECHART, select the library and click on Add Jars, then point to prebuilt/common/jfreechart and add all 3 jars. For ANDROID_SWT, add the 3 jars under prebuilt/common/eclipse, as well as the architecture specific version - for my Mac it's prebuilt/darwin-x86/swt/swt.jar but this will depend on your OS and architecture. (When I used Eclipse 3.6 I couldn't just add the jars from this dialog, I had to go and open the User Libraries panel and there I could define libraries named ANDROID_JFREECHART and ANDROID_SWT.)

Voila -- now all the errors in the Problems view should disappear! (There are still quite a few warnings.)

Run and Debug

The next step is to add a run configuration so you can run and debug the ADT. Hit the Run button. When it asks you what to run it as, choose "Eclipse Application".

Important: Open the Configurations panel and edit the new configuration. In particular, go to the "Plug-ins" panel, and uncheck the third or so item,  "com.android.ide.eclipse.tests". If you enable it you can run into some very subtle bugs where jars from the test module's classpath are accidentally conflicting with different versions of jars in the tools plugin. I wasted nearly a day on that issue...

If you're on Mac and you get "java.lang.UnsatisfiedLinkError: Cannot load 32-bit SWT libraries on 64-bit JVM", you need to add "-d32" as an argument to the VM.

You should now be able to run the ADT - it will invoke a second instance of Eclipse, where all the Android tooling is baked in. The first thing you need to do is point the tool to a version of the SDK. Open the Preferences panel, and in the Android panel go to the text field where you can point to an SDK root. If you have downloaded versions of Android in the past, you can point to the root containing all of the different platforms here. However, you don't have to -- when you ran "make sdk" earlier you built a trunk version of the Android SDK (from here on referred to as "AOSP", which I think stands for Android Open Source Project).  Therefore, you can point to your build output here -- and as you continue pulling down new changes and rebuilding the SDK, your Eclipse target will also use the latest and greatest.

To point to it, use <your tree>/out/host/darwin-x86/sdk/android-sdk_eng.tnorbye_mac-x86/

That exact path will not work for you, since it has various architecture and user names in it. So open the file chooser and drill down, first to out, then host, then your os and architecture, then sdk, and then some directory which contains "android-sdk_eng", your username and your platform.  Hit OK.

After a brief pause you should now see a platform listed in the listbox in the Android panel, and it will identify itself as version "AOSP". If you instead point to officially released versions of Android, you'll see versions like "5", "6" and "7". The reason we don't use a number for the trunk version is to prevent you from accidentally building an app compiled against this trunk version, and then releasing it on the market.

Now that you have your Android versions configured, you can create a new Android project. Do New > Android Project, and in the New project dialog, you need to go and choose the AOSP platform in the platform listbox.  Fill out the dialog. The only trick is that it asks you for a "Min SDK Version", and here you should again type "AOSP".  You can now go and try for example the Layout Editor, by opening res > layout > main.xml.

We're working actively on the layout editor, but as you can see we could use help in lots of areas, from feature development, to icon work, to bug fixing, to bug reporting! (Again, I'll talk more about contributions in a follow-up post.)

To stay up to date, just go to the command line, type "repo sync", wait for a while, and then redo the make steps (source build/envsetup.sh, lunch sdk-eng, make sdk, create_symlinks), and reopen Eclipse and rebuild all. If you get a build error, you can wipe out the entire out folder to build from scratch, but I rarely have to do that.

You can add additional Android platforms, such that you can choose which platform to use for WYSIWYG rendering (just like you can already switch theme, orientation, etc):



This is a new feature added just in the last couple of days. It lets you target older platforms but visually work with newer platforms, and quickly switch between them to see how your layout looks on different platforms.  Of course, to use this you need to point your root Android tree to an install containing multiple platforms. If you do add additional platforms, make sure you copy older platforms (android-6, android-7, etc) into the platforms/ folder of the newly built SDK, rather than the other way around. This is necessary because the directory structure changed recently.

Edit

Now that you can build and run, let's take a look at the source code. The main Eclipse project to look at is the "adt" project, which is the Eclipse plugin.

First, you can configure your editor to use our custom dictionary to help the spell checker recognize words that are in our comments but are not in the default Eclipse English dictionary.  Search for Spelling in the options dialog, and add sdk/eclipse/dictionary.txt as the "User Defined Dictionary" path.

Second, if you will be doing any editing of the source code, make sure you configure your editor to use our formatting preferences and our import order. Open the Java Code Style dialog, and for the formatter, import development/ide/eclipse/android-formatting.xml . For Organize Import, import development/ide/eclipse/android.importorder . The code style for the Android source code base is document in http://source.android.com/source/code-style.html.

***

That's it! You should now be able to get the source code, build, edit, run and debug the Android IDE tools!