Installing/Developing Android (especially on OS X)

UPDATE: updated August 2011, with more detailed / idiot-proof instructions – and a couple of shortcuts. NB: when you’ve done this install once, and checked the relevant bits into your Source Control, it becomes *very* fast/easy to re-install – it’s only long-winded the first time.

I thought I’d blogged this before – the install process from Google is appalling, and I wrote up detailed instructions for colleagues about a year ago. Sadly, looks like I never published the post. I just did a fresh install on OS X (January 2011) and the process *still* is riddled with flaws. I get the impression Google won’t fix it anytime soon.

NB: the biggest single problem here is: Version Control. Someone at Google appears to believe that version control is “unimportant” and that developers should “not be expected to make reproducible builds of their software”.

But … even if you’re a sloppy programmer who doesn’t do proper version control, you probably STILL don’t want to use Google’s auto-installer. It can’t cope with basic stuff like “internet connection drops for a few seconds while ADSL re-dials” – things that your web-browser deals with perfectly. e.g. as of Jan 2011, the Android auto-installer managed to crash Eclipse just because of a blip in net connection. Pathetic, really.

(not to mention the hassle of re-downloading hundreds of meg of data over and over again for every PC in your office … this document will let you download most of it once only, and install it multiple times)

I don’t have a perfect solution, but here’s a guide for how to (mostly) un-**** the installation process for Android development.

Developing for Android: Essentials

The main IDE for Android is the (mostly excellent) Eclipse – with some custom plugins built by Google/Android folks. Once it’s up and running, it’s definitely the best free solution. To make this work, you need:

1. Eclipse IDE … *any* flavour
2. Android plugin for Eclipse (called “ADT”)
3. The version-independent Android SDK (called “android-sdk”)
4. A specific OS-version of Android (e.g. current latest is v2.3)
   • NB: plus you need a “platform tools”, which you download/install in the same way, but is an extra file/feature

FYI: the first item is from Eclipse, the last 3 are all from Google. Although Google keeps trying to kick you in the teeth, you can workaround their foolishness relatively easily for the middle two items. The big problem is the last item. More on that later.

Installing Eclipse on OS X

What follows comes mostly from: http://eclipse.org

Once a year, I call-out Eclipse.org for the appalling user-experience of downloading and installing their software. They’ve had a decade to get this right, and they still get it so wrong.

As of Jan 2011: there’s been a big improvement recently – you can now find the download link quite easily. At http://eclipse.org/ there is an enormous “DOWNLOAD ECLIPSE” button in the top right of the page, in bright yellow. This is excellent.

Sadly, the download link DOES NOT DOWNLOAD ECLIPSE … instead it takes you to a screen that demands you choose the “correct” version out of 12 offered to you, with literally no help at all. The majority of users want one of only 3 versions from that screen. In fact, I suspect 99% of people that come via the front page only want one version.

Furthermore, there is *still* no download for OS X. There is *part of* a version for OS X, but no-one has done the 5-10 minutes of setup that would make it install correctly on OS X forever more. Instead, you have to manually muck about with your computer, your administrator account etc. FAIL.

1 of 4: download the “Eclipse IDE for Java Developers” file.

Unzip it. Unzip it *again*, because they decided to use archaic Unix compression instead of ZIP.

Now you have a new folder, called “eclipse”. You have to put this somewhere. There is (officially) no official location for this … good luck getting support if you put it in a “bad” place.

Most people drag/drop this folder to their Applications folder in Finder. This kind-of works, but again because the Eclipse team haven’t spent a few minutes making an OS X manifest (could have done this any time in the past few years!), the “Eclipse.app” file is broken. If you drag/drop that file to anywhere, it will stop working.

Instead, you have to manually create a shell script to run Eclipse. I’m not even going to go into it – if you want an Eclipse.app icon in the right place on OS X, Google for tutorials on how to make a working Alias specifically for this app (working around the broken one from Eclipse.org). Or … just live with the fact you have to navigate to the “eclipse” folder before you can start the application.

Download the necessary plugins for Android

What follows comes mostly from: http://developer.android.com

Immediate FAIL from Google: the download page lists *ONE* download file, out of the *FOUR* that are absolutely required in order to do Android development. There is no mention of the others :(. How am I supposed to install the software if you won’t give me the links? Your crummy auto-installer is no subsitute.

2 of 4: At least it will get you the SDK, so download that directly

… from the main download page

If you dig around the site, read through 3 sets of instructions that all tell you not to download anything, and keep bullying you into using the crappy auto-downloader instead, you’ll eventually find a file something like:

3 of 4: ADT ZIP file

(Jan 2011:) ADT-8.0.1.zip (if you google for “ADT-8” or “ADT-9” you might find future versions on the site, since Google refuses to put them in a sensible place anywhere). Alternatively, the latest version should always appear at the “magic URL”: http://dl-ssl.google.com/android/eclipse/site.xml.

(Aug 2011:) currently it’s on version 12 …

(usually, this download link is hidden in the section “Troubleshooting ADT Installation”. The Magic URL … I’ve never seen anywhere. You have to know how Eclipse works in order to deduce it. For the record, other companies (including Eclipse’s maintainers) put a webpage at the parent of that URL, to help normal users. This one just does a 404 Not Found)

Finally, you need the bit that Google *really* doesn’t want to give you: a specific version of Android OS to develop against. You need to find the URL for a “repository.xml”. In this case, you can see it flash up briefly when the auto-installer is refreshing the repository (the part that does this is called “the Android SDK and AVD Managers”). You can try that URL:

4 of 4: http://dl-ssl.google.com/android/repository/repository.xml

Google could easily have provided this URL in the docs, since it is the “official” index for downloading the other files you need, but for some reason they chose not to.

There’s 2 ways to avoid Google’s broken auto-installer (which you shouldn’t be using anyway, unless you don’t care about updating your own Android apps in future).

1. Create a local “fake” repository by manually reading an XML file and downloading each file by hand.

This used to work – in 2010, I used this successfully. In 2011, it refused to work. Something critical has changed in Eclipse so that it doesn’t recognize fake repositories – or I just couldn’t reverse-engineer the format correctly any more

2. OR: … download the files you want, and later manually copy them into the folder where Google requires them to be copied.

NB: the auto-installer often fails / timesout / dies when trying to do this. This is all it needs to do, but it’s rubbish. I’ve found that doing it by hand is usually less error-prone, tragically.

To download the files, you need the URL’s of each version of Android you want to support. Google refuses to put these in a webpage (why? Who knows?), but it’s not hard: open the XML link above – your browser should be able to view it directly:

http://dl-ssl.google.com/android/repository/repository.xml (opens fine in Firefox)

Scroll down – it’s a human-readable file – skipping the huge license. You’ll see a lot of “sdk-platform” sections – each of these is a single verison of Android, and contains one URL for you. e.g.:

<sdk:platform>
<sdk:version>1.1</sdk:version>
<sdk:api-level>2</sdk:api-level>
<sdk:revision>1</sdk:revision>
<sdk:description>Android SDK Platform 1.1_r1</sdk:description>
<sdk:desc-url>http://developer.android.com/sdk/android-1.1.html</sdk:desc-url>
<sdk:obsolete/>
<sdk:archives>
<sdk:archive os="windows" arch="any">
<sdk:size>46828615</sdk:size>
<sdk:checksum type="sha1">a4060f29ed39fc929c302836d488998c53c3002e</sdk:checksum>
<sdk:url>android-1.1_r1-windows.zip</sdk:url></sdk:archive>
<sdk:archive os="macosx" arch="any"><sdk:size>45584305</sdk:size>
<sdk:checksum type="sha1">e21dbcff45b7356657449ebb3c7e941be2bb5ebe</sdk:checksum>
<sdk:url>android-1.1_r1-macosx.zip</sdk:url>
</sdk:archive>
<sdk:archive os="linux" arch="any">
<sdk:size>45476658</sdk:size>
<sdk:checksum type="sha1">c054d25c9b4c6251fa49c2f9c54336998679d3fe</sdk:checksum>
<sdk:url>android-1.1_r1-linux.zip</sdk:url>
</sdk:archive>
</sdk:archives>
</sdk:platform>

For each one you want to download, look for the highlighted bit above. That gives you a filename – if there’s no OS X section, take the linux section instead.

You then append that filename to the URL you used to get the repository, i.e.:

“http://dl-ssl.google.com/android/repository/” + “[filename you picked above]”

I’m afraid you have to do this for each version of Android you want to build against – but for most people, that means “just the most recent few versions”.

5 of 4: another ZIP you need: “Platform tools”

You will *ALSO* need – while you’re at it – to grab an “Android SDK Platform-tools”. Google doesn’t mention this as a separate stage, because their auto-installer treats it as part of the 4-of-4 items above.

It’s another file with the URL stored in the same repository.xml from the above step.

However, it lives right at the bottom of the XML file, in a section that looks like this (there’s only one of them – no choices to make – just grab it):

<sdk:platform-tool>
<sdk:revision>06</sdk:revision>
<sdk:description>Android SDK Platform-tools, revision 6</sdk:description>
<sdk:desc-url>http://developer.android.com/sdk/</sdk:desc-url>
<sdk:archives>
<sdk:archive os="linux" arch="any">
<sdk:size>15398275</sdk:size>
<sdk:checksum type="sha1">292732c6a86971b95ca61ba8bf84cd9d6c2285c3</sdk:checksum>
<sdk:url>platform-tools_r06-linux.zip</sdk:url>
</sdk:archive>
<sdk:archive os="macosx" arch="any"><sdk:size>15127727</sdk:size>
<sdk:checksum type="sha1">86c958b461b6244e74b4e0489ea7cef9a681d882</sdk:checksum>
<sdk:url>platform-tools_r06-macosx.zip</sdk:url>
</sdk:archive>
<sdk:archive os="windows" arch="any">
<sdk:size>16589948</sdk:size>
<sdk:checksum type="sha1">14acb6271c71dce94bba879496cd66e09ae144af</sdk:checksum>
<sdk:url>platform-tools_r06-windows.zip</sdk:url>
</sdk:archive>
</sdk:archives>
</sdk:platform-tool>

Installing ADT (the “eclipse plugin for Android”)

If you downloaded this directly, as detailed above, then Google’s post-install instructions are weak. The download ZIP also has no install instructions with it. Here’s a short version:

1. Unzip the ADT file (Google is happy with ZIP, unlike Eclipse)
2. Create a “magic” folder for Eclipse somewhere, which is where you’ll store all your Android SDK’s, ADT plugins, etc. Create a sub-folder “local repositories”
3. Move the ADT folder into “local repositories” (you will probably want to upgrade this later, so you need to be able to find it easily)
4. (NB: sad design flaw of the auto-updater – it’s hardcoded that you MUST give each repository a unique “name”, even when this makes no sense to the developer)
5. … NB: as of August 2011 … what follows is pieced together from Google’s incoherent documentation – you won’t find these steps written clearly + correctly anywhere on the developer.android.com website :(
6. [aug 2011]: “Start Eclipse, then select Help > Install New Software….”
7. [aug 2011]: “Click Add, in the top-right corner.”
8. [aug 2011]: In the Add Site dialog, click Local (not “Archive”, as per Google’s instructions – Archive causes other problems later on)
9. [aug 2011]: Browse and select the folder you unzipped/created/moved in step 3
10. [aug 2011]: “Enter a name for the local update site (e.g., “ADT Plugin”) in the “Name” field.”
11. [aug 2011]: “Click OK”
12. [aug 2011]: “In the Available Software dialog, select the checkbox next to Developer Tools and click Next.”
13. [aug 2011]: “In the next window, you’ll see a list of the tools to be downloaded. Click Next.”
14. [aug 2011]: “Read and accept the license agreements, then click Finish. ”
15. [aug 2011]: …Google doesn’t admit this, but some of the ADT components aren’t signed, which is a security hole. Eclipse rightly says: “Dude, are you sure you want to install unsafe software?”. You have no alternative, though – until Google re-builds the plugin to be properly signed, you just have to accept it.
16. [aug 2011]: “When the installation completes, restart Eclipse.”

Jan 2011: Bizarrely, at this point the auto-updater hangs for a few minutes, randomly contacting internet sites for stuff that I expressly did NOT attempt to install. I’m not sure if this is a bug in the current Eclipse, that it “hi-jacks” the plugin-install process and tries to update the rest of Eclipse, or if it’s a “feature” of the Android plugin – that it secretly triggers additional installs from the internet.

Installing the SDK

In Google’s docs, there’s a whole page for installing the SDK.

It does not – at any point – tell you how to install the SDK.

Instead, that information is inside the page for installing the ADT plugin for Eclipse.

Genius!

To save you navigating their bizarre instructions, I’ll copy/paste them here. First, however, you need to create a local install directory for the SDK (they forget this step, of course). Put it somewhere that you’ll never accidentally modify or delete – if you do, Android apps will stop building in Eclipse until you manually fix everything again. Given how tortuous the main instructions are, I’ve seen smart people diagnose the problem but have massive trouble figuring out exactly how to rectify it.

Anyway, once you’ve picked a location, unzip your SDK zip file into that folder, and proceed with Google’s instructions:

1. Select Window > Preferences… to open the Preferences panel (Mac OS X: Eclipse > Preferences).
2. Select Android from the left panel.
3. For the SDK Location in the main panel, click Browse… and locate the directory that was created when you unzipped (Google words this badly – it MUST be the folder that came out of the ZIP – Eclipse will check the contents of the folder, and reject if you select its parent folder, or one of its children)

4. Click Apply, then OK.

Installing the “Android Platform versions”

This is the install part that matches the “4 of 4” download part above.

Take each ZIP file you downloaded, and unzip it.

e.g.:

• android-3.2_r01-linux.zip

This will give you an *incorrectly named* folder, e.g:

• android-3.2_r01/

…you *may* need to manually rename this using the “<sdk:api-level>13</sdk:api-level>” tag that was in the original repository.xml where you got the download URL from. Each downloadable ZIP file had a different – unique – api-level tag.

The new format (I’m not sure this is required, but it’s what the installer does, so I recommend doing it):

• android-13/

Finally (!) … find the folder where you unzipped the SDK earlier. That will have files/folders very similar to the following:

• add-ons/
• platforms/
• tools/
• SDK Readme.txt

Take your (possibly renamed) folder – in my case “android-13/” – and move it into the “platforms” subfolder.

The ADT Eclipse plugin will automatically discover this when you restart.

…go through the same process for each Android Platform version you downloaded.

Shortcut: if you’ve done this before, with a previous version of Eclipse / ADT / Android … you can just take the sub-folders of “platforms/” from your previous install, and copy/paste them into the “platforms/” sub-folder of your nw SDK version. Easy.

Installing the “Android Platform Tools”

…this works in exactly the same way as the “Android Platform versions” above, except it goes in a different folder.

In this case, you need to take the zip file, unzip it, and rename the output folder to precisely:

• platform-tools/

…then copy/paste it directly into the SDK folder. There shouldn’t be a “platform-tools/” folder to start with – this is how Eclipse/ADT knows whether or not you’ve “installed” it: it just looks for a folder with that name.

OPTIONAL: Downloading + Installing the Android SDK documentation

UPDATE: sorry, I missed this out originally.

Again, just like with the “Android Platform Tools”, you have to manually grab the URL for this from the repository.xml

The piece of XML in the repository.xml you need is:

<sdk:doc>
<sdk:api-level>13</sdk:api-level>
<sdk:codename/>
<sdk:revision>01</sdk:revision>
<sdk:description>Android SDK Docs for Android API 13, revision 1</sdk:description>
<sdk:desc-url>http://developer.android.com/sdk/</sdk:desc-url>
<sdk:archives>
<sdk:archive os="any" arch="any">
<sdk:size>103791308</sdk:size>
<sdk:checksum type="sha1">5dadb3b30e1f837716f8a5ef840e31abddf69b38</sdk:checksum>
<sdk:url>docs-3.2_r01-linux.zip</sdk:url>
</sdk:archive>
</sdk:archives>
</sdk:doc>

…then take the zip file, unzip it, and rename the output folder to precisely:

• docs/

…then copy/paste it directly into the SDK folder.

Done!

Phew! Finally! You should now be set for Android development!