Chapter 3

Setting Up Your Development Environment

In This Chapter

Getting familiar with the Eclipse development tool

Using the Android SDK

Running your first Android app

The tools for developing Android are freely available for download and use. Even if you’ve never used an IDE (integrated development environment) like Eclipse, it won’t take long for you to get your feet wet.

Starting at the Beginning

Android and all its associated tools run on Java, so the first thing you’ll need to do is make sure your development machine meets the supported system requirement. Then you’ll need to install the Java Development Kit (JDK).

The following operating systems are currently supported:

Windows XP (32-bit)

Windows Vista (32- or 64-bit)

Windows 7 (32- or 64-bit)

Mac OS X 10.5.8 or later (x86 only)

Linux (tested on Ubuntu Linux and Lucid Lynx)

• Gnu C Library (glibc) 2.7 or later is required

• For Ubuntu Linux, version 8.04 or later is required

• 64-bit distributions must be able to run 32-bit applications

After you’ve verified that your machine is up to snuff, the next order of business is to install the latest version of the JDK.

Follow these steps:

1. Point your browser to www.oracle.com/technetwork/java/javase/downloads/index.html

You should see something like the page in Figure 3-1.

2. Click the download icon for Java Platform (JDK).

The page listing downloads for specific platforms appears (See Figure 3-2).

3. Click the Accept License Agreement radio button and then click the specific download link for your operating system.

For example, the download for Windows 32-bit systems is jdk-7u3-windows-i586.exe.

4. When the file has downloaded, double-click the file to begin the installation process.

On Windows, you’re prompted by a message such as Do you want to allow the following program to make changes to your computer?

Click the Yes button to continue with the installation and follow any instructions provided by the installer.

That’s it! After the JDK is installed, you can run all the tools required to start building Android games.

The next step is to install Eclipse.

Downloading and Installing Eclipse

Eclipse is an integrated development environment (IDE), but what is that exactly? If you’ve never used an IDE before, it’s a piece of software that makes software development a whole lot easier and enjoyable.

If you’re an ace programmer with a photographic memory and robotic concentration, all you really need to write code is a simple text editor. Coding in a high-level language like Java is just writing text in a file. But an IDE provides an interface to your projects that makes carrying out simple, repetitive tasks much easier, as well as helping with debugging and troubleshooting.

Android Development Tools (ADT) is a plug-in that integrates with Eclipse to enable Android app development.

Android Development Tools have not always been compatible with the latest version of Eclipse. Double-check here for compatibility before installing Eclipse: http://developer.android.com/sdk/eclipse-adt.html.

The recommended version of Eclipse to use with the ADT is Classic. To install Eclipse Classic, follow these steps:

1. Point your browser to www.eclipse.org/downloads.

You should see something like the page in Figure 3-3.

2. If you are using Windows, click the appropriate download link (such as “Windows 32-Bit” next to Eclipse Classic 3.7.2).

If you are using an OS other than Windows, click the name of the package (such as Eclipse Classic 3.7.2) directly, which opens a page with downloads for other operating systems.

Eclipse is downloaded as a compressed .zip file.

3. After the file has downloaded, extract the .zip file into your desired directory (for example, c:Program FilesEclipse in Windows).

4. Launch Eclipse by double-clicking the eclipse.exe icon.

You probably also want to create a shortcut on your desktop or Start menu.

When you launch Eclipse on Windows, you may be prompted by a message such as Do you want to allow the following program to make changes to your computer?

Click the Yes button to continue with the installation and follow any instructions provided by the installer.

Java is required for Eclipse, so if Java is not properly installed, Eclipse won’t work. When Eclipse starts for the first time, you’re prompted to select a workspace.

This is the location on your computer where the working files for your project are stored.

Check the “Use this as the default and do not ask again” check box (Figure 3-4) after selecting the location for your desired workspace.

When you’ve selected a workspace, the Eclipse welcome screen appears, as shown in Figure 3-5.

Click the arrow icon on the right to launch the workbench view, which should look something like Figure 3-6.

Eclipse is extremely customizable, so you can move views around to organize your workbench however you like. If you’re new to Eclipse, though, you’ll probably want to leave the default organization in place. This screen is where you’ll spend most of your time:

The Package Explorer on the left displays the directory structure for your projects.

At this point, you don’t have any projects yet, so there’s nothing to display.

The views at the bottom are typically used to analyze problems and output related to your project.

The outline view shows an ordered list of the elements in the currently-selected file.

It can be very useful for navigating the structure of a given file.

The big gray space in the middle is the code view, which is where you’ll be entering all your brilliant code!

Make line numbers visible in the Eclipse code view:

1. Select Window⇒Preferences.

2. Select General⇒Editors⇒Text Editors.

3. Check the Show line numbers check box.

The Android SDK and ADT still need to be installed before you can develop for Android in Eclipse. Read on to find out how.

Installing the Software

You have to have the Android SDK, which consists of libraries, documentation, and other code, in order to develop Android apps and games.

Note that the Android development tools are updated frequently, so the installation process may vary.

Installing the SDK

Follow these steps to download and install the SDK:

1. Point your browser to http://developer.android.com/sdk/index.html.

You should see something like the page in Figure 3-7.

2. Click the download link for your platform.

For Windows, Google recommends the installer (.exe) download.

3. Double-click the downloaded .exe file.

Follow the installation wizard instructions.

• If you use the self-extracting installer, at some point during the installation process it will prompt you for a path in which to extract the files.

• If you are not using the installer, but a compression tool to extract the files, you will need to choose a location.

In either case, use c:android (or whatever the root directory on your hard drive is, if you’re on another operating system). This will be the default location used throughout this book.

4. Start the SDK Manager.

Upon completing the SDK installation, the final screen of the wizard has a check box which reads “Start SDK Manager”.

Leave it checked and click Finish.

5. Install the latest Android API (application programming interface).

By default, the SDK Manager will select the packages you need to begin developing with the latest available version of Android. I recommend that you leave the defaults checked, then click Install. A license window will appear.

6. Review the packages to install and their licenses, make sure the Accept radio button is selected, then click Install.

It may take a while to install all the necessary packages.

When the SDK Manager has finished downloading the packages, you may close it.

Installing the ADT

Follow these steps to install the Android Development Tools (ADT) plug-in.

1. Start Eclipse, then select Help⇒Install New Software.

The Install window appears.

2. Click the Add button.

The Add Repository dialog box will appear.

3. Enter “ADT Plugin” for the name and https://dl-ssl.google.com/android/eclipse/ for the location.

The dialog box should look like Figure 3-8. Click OK.

4. In the Install dialog box, click the check box next to Developer Tools.

The dialog box should look something like Figure 3-9.

5. Click Next.

A list of the tools you selected for download appears on the next screen.

6. Click Next.

You’re prompted to review the licenses for the software to be installed. You may select the license on the left to read its text in the box on the right.

7. To accept the license and continue, click the radio button that says I accept the terms of the license agreement and then click Finish.

Upon completion of the installation, you may see a Security Warning dialog box, indicating that you are about to install unsigned content. This sounds scary, though it’s perfectly fine. Click OK.

8. When the installation is complete, you’ll need to restart Eclipse.

Upon re-launching Eclipse, you should see two new icons in your toolbar, if the ADT was successfully installed in Eclipse. Figure 3-10 shows an example.

The two new icons launch these parts of the development environment:

Android SDK Manager (the icon with the down arrow).

The Android SDK manager is what you use to update the SDK.

Android Virtual Device Manager (AVD).

New versions of the Android SDK are released periodically. These updates may include

Bug fixes

Enhanced performance for Android tools

New functionality

It’s a good idea to read blogs or forums related to Android development to stay up to date. Things move fast in the world of Android! These venues usually indicate when any new development tools are available for update. Otherwise you can just launch the tools from within Eclipse every couple of months and check manually.

Connecting Eclipse to the SDK

As it happens, you’re not done integrating Android into Eclipse yet. You need to tell Eclipse where you installed the SDK. To do so, follow these steps.

1. In Eclipse, select Window⇒Preferences.

The Preferences window appears.

2. Select Android from the list in the left panel.

Your Android preferences appear, including a text box labeled SDK Location, which should be empty.

3. For the SDK Location, enter c:android or click Browse and navigate to the location of the SDK.

4. Click Apply, then OK.

Now the Android tools should be successfully integrated into Eclipse. You’re ready to create your first virtual device.

The Android Virtual Device (AVD) Manager

This tool allows you to create one or more virtual Android devices that will run on your desktop and behave like actual Android devices.

There are a couple of drawbacks to emulation:

Virtual Android devices are very slow, even though Google has put effort into increasing the performance on emulated devices.

Speed is the major difference between an emulated device and a real one. Performance is worse as the size of the display increases. Trying to test apps or games for devices with very large displays is very difficult.

Invest in a hardware device if you intend to target tablets.

Emulation is a poor test for certain input features.

• Interacting with a virtual device by using a mouse is almost nothing like interacting with the same device using your fingers and/or thumbs. On more than one occasion, I’ve initially tested an interface on a virtual device, only to realize that UI elements needed to be larger and better-spaced after I loaded the UI onto a hardware device.

• If your game uses the accelerometer or some other form of input that is difficult or impossible to emulate, you’re better off testing on hardware.

That said, the emulator can come in handy if you’re on a budget and can’t afford a wide array of test devices.

An AVD is a good first-cut at testing your game. Nothing beats play-testing on an actual device, but if you’re testing the initial look and feel of the game, early use of an AVD can be very helpful.

Creating a virtual device

To create a virtual device, follow these steps:

1. In Eclipse, click the Android Virtual Device Manager icon, or select Window⇒AVD Manager.

The Android Virtual Device window appears, as shown in Figure 3-11

2. Click New.

The Create new Android Virtual Device (AVD) window appears, as shown in Figure 3-12.

3. Enter a name for your new virtual device.

Since you may have a lot of virtual devices, you’ll want to use a descriptive name (“AVD1” is a bad idea!). Let’s create a device that runs Android 2.1 with an HVGA screen. A good descriptive name for such a device would be “2.1HVGA”.

Android naming conventions usually only allow

• Letters a through z (upper- or lowercase)

• Numbers 0 through 9

• Symbols period (.), dash (–), or underscore (_).

These limitations also apply not only for the names of virtual devices, but also for many names you use throughout Android projects (such as names for resources).

4. Select an Android version to target from the Target drop-down menu.

The versions you selected when installing the SDK will be visible.

In this case, select Android 2.1 – API Level 7.

5. Enter a size for the virtual SD card in the Size field.

Your game may or may not use the SD card on a device in order to store information like saved games and high scores. There are a number of ways to store information, and not all require the SD card.

This is optional on virtual devices, but it’s a good idea to always implement a virtual SD just in case you need one.

A good size for a virtual SD card is 1 gigabyte (GB). Enter “1000” in the Size field.

6. Select a resolution.

• Most of the time you’ll want to test on the built-in resolutions, available from the Built-in drop-down menu.

• Occasionally you may want to test for a device with a non-standard display. In that case, you can enter whatever custom values you want.

In this case, select HVGA. This was the standard resolution for most early Android devices.

Many devices are being released with higher resolution, but you should still test for HVGA as a baseline.

Review your settings. They should look like those in Figure 3-13.

The hardware fields allow you to

• Further customize the attributes of the devices you’re using (such as virtual memory).

• Provide support for other hardware such as an accelerometer or GPS device.

Okay, relax. No need to make any adjustments to these settings just now, but as you can see, virtual devices are highly customizable.

7. Click Create AVD.

Your new virtual device will now show up in your list of available virtual devices, as shown in Figure 3-14

You’re ready to launch your first virtual device and see it in action!

Launching a virtual device

To launch a virtual device, from the AVD Manager, follow these steps:

1. Highlight the virtual device in the list by clicking the entry, then click Start.

You’ll see the Launch Options window (Figure 3-15).

Give it some time. A virtual device typically takes several minutes to completely start up. When the virtual device is finished loading, you should see a home screen similar to that of a hardware device (see Figure 3-16).

If your virtual device has an extremely large display, or you are developing on a smaller screen (like a laptop), you may want to select the Scale display to real size check box and enter the display size, in inches, that the virtual device will show you on your monitor.

From this option window, you may also select Wipe user data, which clears any saved information related to your game. This is handy and important to use in testing, as you will want to test your game with a clean install, just as if a user were installing the game for the first time.

2. Click Launch.

You don’t need to re-launch a virtual device every time you run your app. Launching a virtual device usually takes several minutes. When you launch one, leave it running for as long as you intend to test. This is a common mistake of beginning Android developers.

The look and feel of a virtual device will depend on the Android version. The one shown in Figure 3-16 is for Android 2.1. Take some time to get familiar with the virtual device by launching sample apps and navigating through the various screens and menus. You’ll notice that the interface will probably be slow and laggy compared to what you’d get from the real thing.

Just be patient, and remember: It’s a free Android device running on your PC!

Creating an Android Project

When Eclipse is up and running with the Android SDK installed (you’ll know it’s correctly installed if you’ve been able to create and run a virtual Android device), you’re ready to create your first Android project.

Follow these steps:

1. In Eclipse, select File⇒New⇒Android Project, or right-click the Package Explorer and select New⇒Android Project.

The New Android Project window appears, as shown in Figure 3-17

2. Enter a name for your project in the Project Name field.

For your first project name, enter “Hello World.”

3. Click Next.

The New Android Project window prompts you to select a build target, as shown in Figure 3-18.

The build target refers to the version of the SDK used to develop the app, not the version of target devices. You’ll usually want to select the highest available build target.

If there are no build targets showing in your list of available build targets, try closing and restarting Eclipse before starting another Android project.

4. Click Next.

The New Android Project window prompts you to enter application info, as shown in Figure 3-19.

The application name is populated by default with the project name. Just leave that the way it is. You’ll need to enter a new package name, though.

A package name is a unique identifier with hierarchical structure, typically like a domain name for a website, only in reverse. Package names are always in lowercase to avoid collisions with class names. Throughout this book you’ll find it uses the domain agpfd (Android Game Programming for Dummies) — so, for this example, enter com.agpfd.helloworld.

This window also allows you to create an activity by default. Don’t make any changes there.

The Minimum SDK drop-down menu allows you to specify the oldest version of Android you want your app to target. Select 4 (Android 1.6) for this example.

5. Click Finish.

Your newly created project should appear in the Package Explorer.

Use the arrows next to each project element to expand or collapse the hierarchy. Your project should look like Figure 3-20, and you should be able to expand the package to see the default activity, HelloWorldActivity.

Running an Android App

Before you run the app, you’ll want to set up your run configurations, which are options for how the app launches.

Your run configuration for a given project can determine whether the app is launched automatically, finding a best match among available devices, or whether you may manually choose a device for launch.

If you leave the default configuration, when you run an app the Android tools will try to find the best match from either your virtual devices or physical devices attached to your computer. If no virtual devices are open, it will launch one.

Manual launch control

I like more fine-grained control over what launches and when, especially since I often have more than one available device that can run the app.

To set up manual launching, follow these steps:

1. In Eclipse, select Run⇒Run Configurations.

The Run Configurations window appears.

2. Select Android Application, then click the New Launch Configurations button.

Configuration options for an Android project appear, as shown in Figure 3-21.

3. Click Browse, select your Hello World project, then click OK.

You should now see the name of your project in the Project field.

You can enter a custom name for this run configuration if you like, but leaving the default name New_configuration is fine.

4. Select the Target tab.

The Automatic option is selected by default. Click the Manual radio button.

Your window should look something like Figure 3-22.

5. Click Apply, then Close.

Your run configuration is now set up to let you manually select which device you want to upload and launch your game to when you choose to run it.

Starting apps

When you’ve got a sample project and you’ve set up the run configuration for that project, you’re finally ready to start an app and run it.

Launching an app on a physical device is similar to running one on the emulator. The rest of this chapter shows how to start apps on virtual devices and real devices.

Virtual devices

If you don’t have a virtual device running, launch one now by following these steps:

1. Click the AVD button.

2. Select the device, then click Start.

3. Click the Launch button.

When your virtual device is running, follow these steps to launch your Hello World app:

1. Select the project to run, then the Run button in the Eclipse toolbar, or right-click the project name in the Package Explorer and select Run as⇒Android Application.

The Android Device Chooser window appears, as shown in Figure 3-23.

2. Select your virtual device from the list and click OK.

Your app should be running on the virtual device, as shown in Figure 3-24.

Real devices

Testing with a real device requires connection to your device to your development machine; most commonly that’s done via USB.

Depending on the device model and your operating system, you may need to install additional drivers. The Android SDK provides a large number of drivers, but there is such a wide array of devices that you may find it necessary to seek out specific drivers for your device. Even with some popular device models, I’ve had to install additional drivers to get them to work with my development machine.

The installation process for drivers can vary widely depending on your Android device and your development operating system:

In a best-case scenario, you’d just plug your Android device into your development machine via USB and the drivers would be automatically installed.

If the best case is not an option, you might need to visit your Android device manufacturer’s website, download the drivers, and follow their installation process.

Apps and games are typically meant to be downloaded and installed from Google Play — so most Android devices are not configured by default to allow apps to be installed from anywhere else. This is a security measure to keep malware from being installed on your Android device without your knowledge. As a developer, you’ll want to change this default setting to allow you to install the games you develop from your development machine to your Android device.

To install non-market apps on your device, you’ll need to open Settings⇒Application Settings. Two settings are required:

Check the Unknown sources check box.

Click Development, then check the USB debugging check box.

This allows your computer to read the log output of your device when connected, rather than enabling file transfer by default.

When your device is connected and ready, you can launch your app. The steps to launch your app on a real device are similar to the steps for launching your app on a virtual device:

1. Click the Run button in the Eclipse toolbar, or right-click the project name in the Package Explorer and select Run as⇒Android Application.

When the Android Device Chooser window appears, you should see your device listed, as shown in Figure 3-25.

If your device doesn’t show up in the list of available devices, you could have a problem with the connection or with the drivers.

2. Select your device from the list and click OK.

Your app should be running on the device, as shown in Figure 3-24.

If you tried your app on an emulator, you should see the same output on your device.

You can view the log output of your device from a view within Eclipse, but I prefer to launch a separate command-line window (Windows key + R in Windows). Type adb logcat from the command line. Doing so enables the Android Debug Bridge (ADB) and displays the log output from either your virtual or physical device. When debugging, analyzing the log output can be crucial in finding and fixing problems.