A couple weeks ago, I started fiddling about with Android in hopes of write some cross-platform code (Android + iOS) for a game engine project I’ve been tossing around. Today, I’m finally getting things making sense, so I’ll be creating a series of posts chronicling all the stuff I’m learning as I go, which will hopefully help others in the future.
In this first post, I’m going to simply walk through my setting up of the Android SDK and NDK. This is a topic that’s been done to death, and is explained quite well in Google’s own documentation. However, I found Google’s documentation lacking in many of the pitfalls that can be encountered when adding the NDK to the SDK. If setting this stuff up were an adventure game, there would be several dead ends right in the middle that force you to start from the beginning.
I’d hate to drop a link on you right away, but here are the official instructions for setting up the Android SDK: http://developer.android.com/sdk/installing.html. This is a great, clear reference for doing initial Eclipse/SDK setup.
Step 1: The PreReqs
Android doesn’t have many prereqs. You need Windows, Mac (Intel), or Linux, for one. Second, be sure to grab a copy of the JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html) and install it. The JDK page has a lot going on, but just hit the big “Java” button and then you can get out of there!
A secret prereq: if you plan on using the NDK extensively, you’ll want to avoid using file paths with spaces in them. I wasted a lot of time initially on some cryptic errors that ended up being caused by my Windows account name being “Clark Kromenaker”. To avoid this grief, I’d suggest doing your work in an account that doesn’t have spaces – in my case, I created a new account called “Clark”.
Step 2: Get the SDKs
Next, head over to the SDK download page and download the SDK for your platform of choice. You can install the SDK any place you’d like BUT it is best to install the SDK to a location with no spaces, despite Windows suggesting you put it in the “Program Files (x86)” directory. I put mine at “C:\Android\android-sdk”. Nesting it in the “Android” folder allows me to group other Android stuff that I’ll be downloading in a bit – stick with me, I’m not crazy.
Android’s SDK Manager will be installed in that directory. The SDK manager is a cool concept: it is a self-updating piece of software that allows you to download the SDKs for each Android platform and manage what is and isn’t installed. There are many Android platforms, with Google releasing new ones from time to time to update the Android operating system (and they all have dessert code-names like Froyo, Gingerbread, and Ice Cream Sandwich). When you start developing apps, you’ll need to decide which platform to support; supporting an older platform will likely give you a larger audience, but it will also require you to take into account the limitations of those older platforms when you write your code.
The SDK Manager for your edification and to provide a visual in this wall of text:
You need to install several packages to make the SDK operational:
- Select both “SDK Tools” and “SDK Platform Tools” under “Tools”. Both are required to do any development.
- If on Windows, select the “Google USB Driver Package” under “Extras”. These drivers are already available on Mac and Linux (lucky ducks).
- You can install all or none of the Android API levels, but you’ll probably want at least one. I chose to install 2.1 as a minimum spec, as well as 4.0.3 to have the latest release available.
Step 3: Get the NDK
While we’re stocking up on SDKs, we may as well grab the NDK. You can get the NDK here: http://developer.android.com/sdk/ndk/index.html. Simply unzip the NDK to the location of your choice. I put it at “C:\Android\android-ndk”, right next to my SDK.
I chose to put the NDK in a generic ndk folder instead of the default “android-ndk-r7″ because if I update my NDK install in the future, I don’t want to have to update my path variables endlessly (which we’ll get to in a bit).
Pretty easy, right?
Step 4: Eclipse and ADT
When it comes to editing code and deploying apps to devices or emulators, you’ve got two choices: Eclipse with the ADT plugin, or your personal favorite text editor and the command line tools. While there are certainly pros to command line compilation (I hope to untangle that mystery in the future to enable easier cross-platform development), I’ll stick with Eclipse and ADT for now.
Download the latest Eclipse release at http://www.eclipse.org/downloads/. The documentation suggests going with “Eclipse Classic,” which I did with no regrets thus far. Eclipse doesn’t really have an install location; it’s just a zip file. I unzipped Eclipse to “C:\eclipse” for ease of access.
With Eclipse, you have an excellent Java editor, but Eclipse actually has no sense of what an Android project is, how to deploy it to a device, or what header files are available! Cue the ADT plugin to solve all these problems. The ADT plugin makes it very easy to create Android applications, launch them, and debug them through Eclipse. Rather than give a full rehash of the install process, I suggest you just follow the instructions at http://developer.android.com/sdk/eclipse-adt.html#installing. You just need to install some files through Eclipse’s internal package manager, and there aren’t any gotchas or issues you should encounter.
When ADT is installed and configured correctly, you’ll see two new links under Window for AVD Manager and SDK Manager. These are shortcuts to their respective SDK tools. AVD Manager allows you to create/modify virtual Android devices (which we’ll setup in a bit), and the SDK Manager is the tool we used earlier to download Android platforms.
Step 5: Cygwin and the Terminal
If you are using Mac or Linux, you are fortunate since the majority of the NDK tools are linux-based and have need of the Terminal. While you can get away with normal SDK development without using the terminal, you’ll need it for the NDK. Mac and Linux users can just open their terminals, which are built into the OS, and skip ahead to step 6.
On Windows, there is a “Command Line”, but it is not compatible with linux-based tools. You’ll need to install Cygwin to use most of the NDK toolset.
Cygwin emulates the linux terminal on a Windows machine with relatively little hassle. Just grab setup.exe from http://cygwin.com/install.html and run it. Cygwin should install to “C:\cygwin”.
During the installation, you will have the opportunity to install packages, which are basically applications and libraries that you may want/need. There is a subset of packages that are installed by default, but you will also need a number of packages from the “Devel” group, particularly C/C++/Java compilers. To be on the safe side, it is perfectly reasonable to select the entire “Devel” branch and install it all. If you ever need to install additional packages, you can simply run setup.exe again and select more from the list.
Once installed, you can run the Cygwin Terminal (available as a Start Menu shortcut) and use all your favorite linux commands to navigate around. Cygwin emulates a unix-y hard drive by pretending that the root of the hard drive is actually your “C:\cygwin” folder, which contains “usr, tmp, etc” folders that are common on unix-based operating systems. When in the Cygwin Terminal, you can access your hard drive contents through “/cygdrive/c” (or whatever your drive letter is).
- <drive letter>
- <drive contents>
A full tutorial on navigating in the terminal is a bit outside the scope of this tutorial. I found this to be a pretty helpful tutorial: http://linux.org.mt/article/terminal.
Step 6: Adding to the PATH
There are several folder paths you’ll need to append to your PATH environment variable for ease of use in the terminal. The PATH variable represents a list of folder locations that the system will search when you issue a command. If the command isn’t found in any of those folders, you get a “command not found” error.
For example, if a program called “testexec” is located at “/tmp/exec” and that folder is not on the PATH, you would have to type “/tmp/exec/testexec” everytime you want to call the program – quite cumbersome after awhile. If you add “/tmp/exec” to the PATH, you will only need to type “testexec” and the OS will figure out which folder the program resides in and fill in the rest of the path for you.
Adding folders to the path is a bit different in different environments:
You can type echo $PATH to see your current path and then use the command PATH=<newFolderPath>:$PATH to add a new directory to the path. You’ll then want to say export $PATH to apply the changes – if your changes are valid, they will be on the path.
This is how you add to the PATH, but the changes are not permanent. To make the changes permanent, open the .bashrc file in your home directory and add the new path lines, along with the export statement. The commands in the .bashrc file will be called every time you use the terminal, effectively making them permanent.
To ensure that these changes are saved, simply restart the Terminal and reissue echo $PATH to see if your new directories are included.
As a linux emulator, Cygwin can handle all the commands listed above for seeing and modifying the path. An added benefit of Cygwin is that you can also use environment variables set in Windows. Cygwin handles transferring the variables into the Linux environment (like turning backslashes into frontslashes). And these variables will always be available in Cygwin.
To add a variable to the Window’s environment, go to “Control Panel > System > Advanced System Settings > Environment Variables”. Under “System Variables,” you can add new variables or modify existing ones. In this case, you’d want to find the PATH variable and add new folder paths onto it. This will all show up on the Cygwin side with no extra work, as long as the paths are valid.
You should add the following paths to your PATH for ease of access to SDK and NDK tools:
Step 7: Setup Devices to Run Apps
You have two options for testing apps that you develop: run them on a real device or run them in the emulator.
Running apps on a device will obviously give you the most concrete data as to whether your app is working correctly. On Mac/Linux, this is straightforward, since most android devices are recognized immediately when connected via USB (notable exceptions include the Nook and Kindle Fire tablets). On Windows, you’ll need the USB add-on pack available through the Android SDK manager, which has a lot of common device drivers. Even still, you may need to hunt down the specific driver for your device from a manufacturer’s website in some cases (had to do this for the Motorola Droid Pro, for example). You can check whether your device is connected successfully using ADB, which I discuss here.
If you don’t have the resources to collect an array of actual testing devices, you can use an Android emulator to great effect. An “Android Virtual Device,” as they are called, is an emulator that runs on your machine to mimic the functionality of an actual device. The upside to this is that you can test against a variety of device configurations easily. Another benefit is being able to simulate OS events such as phone calls, text messages, etc. without buying two Android devices and phone plans (or bugging your friends, which you’ll want to do anyway for better testing coverage).
The downside of virtual devices is that they don’t represent an actual device, so you have to take it with a grain of salt. Second, the emulation is slower than an actual device. Third, some apps don’t support the emulator – for example, the Unity game engine does not support the emulator when testing apps, so you need an actual device on hand.
Creating a Virtual Device is quite simple. You must open the AVD Manager, which is located at “android-sdk/AVD Manager,” or there is also a link to it in the “Window” menu in Eclipse after the ADT plugin is installed.
A window will open that lists the Virtual Devices you have created. It will be empty at first, but you can create one by clicking the “New” button. Give the device a name and select a target (API level) for the phone to support. Later on when you are creating projects, you’ll have to decide what API level will be the minimum for your app, based on the features needed. You will not be able to test an app on a Virtual Device if the app’s minimum API level is greater than the device’s API level.
In my case, I created a couple devices, each representing a different API level. You can also specify the hardware properties of the device. Adding an SD card can be particularly helpful if your app can save data there – you’ll want to test the effects of having an SD card, removing it, etc.
Running an app on the Virtual Device can then be done using either ADB or through Eclipse. In the AVD Manager, you can also manually start an emulated device using the “Start” button.
So, that about wraps it up for setting up the environment. What you have now is a fully-stocked Android installation with the tools to create either SDK or NDK projects. Upcoming posts will discuss the tools in more depth and get into actually creating SDK/NDK projects.