Building Backbone

While Gradle has the benefit of being very powerful and flexible, it isn’t easy to understand right away. This is a guide to help you get Backbone running and building on your machine, no matter what OS and IDE you’re using.

First Steps

Before you get started, it would probably be a good idea to take a look at the first few chapters of the Gradle user guide. While you’re reading, you can begin downloading the Gradle 1.3 release (make sure it’s version 1.3!). Once the download is finished, pick a directory to unpack your installation to. We suggest putting it in the same directory as your Android SDK installation for the sake of simplicity.

Environment variables

For running Gradle, add GRADLE_HOME/bin to your PATH environment variable. Usually, this is sufficient to run Gradle.

Running and testing your installation

To check if Gradle is properly installed just type gradle -v. The output shows Gradle version and also local environment configuration (groovy and jvm version, etc.). The displayed gradle version should match the distribution you have downloaded.

Once you have finished installing Gradle, you will have some additional setup work to do. The Android plugin for Gradle must be told the location of the Android SDK. For obvious reasons, the location of our android SDK installation may or may not be the same as yours, and so that information has not been checked into the Backbone repository with the rest of the code. Therefore, you must fill it in yourself. To do this, create (or edit) the local.properties file in the root of the project and add the sdk.dir property, referring to the location of your Android SDK installation:

sdk.dir = /path/to/android/sdk

Remember not to check this file into source control when sending us pull requests. Alternatively, you can use the ANDROID_HOME environment variable instead. Once you’ve performed these steps you can build your Android application by invoking the tasks described below.

Gradle Tasks

As explained in the user guide, everything in Gradle sits on top of two basic concepts: projects and tasks.

Every Gradle build is made up of one or more projects. A project represents some component of your software which can be built. What this means exactly depends on what it is that you are building. For example, a project might represent a library JAR or a web application. It might represent a distribution ZIP assembled from the JARs produced by other projects. A project does not necessarily represent a thing to be built. It might represent a thing to be done, such as deploying your application to staging or production environments. Don’t worry if this seems a little vague for now. Gradle’s build-by-convention support adds a more concrete definition for what a project is.

Each project is made up of one or more tasks. A task represents some atomic piece of work which a build performs. This might be compiling some classes, creating a JAR, generating javadoc, or publishing some archives to a repository.

By including the Android plugin, we get access to the following predefined tasks and dependencies:

Task	Description	Depends On	Dependents
androidProcessResources	Generate R.java source file from Android resource XML files		compileJava
proguard	Process classes and JARs with ProGuard (by default, this task is disabled, more on this below)	jar
androidPackage	Creates the Android application apk package	proguard
androidSignAndAlign	Signs (with a debug or provided key; more on this below) and zipaligns the application apk package	androidPackage	assemble
androidInstall	Installs the debug package onto a running emulator or device	assemble
androidUninstall	Uninstalls the application from a running emulator or device
androidEmulatorStart	Starts the android emulator
androidInstrumentationTests	Runs an instrumentation test suite on a running emulator or device	androidInstall

Using Eclipse as your IDE

You can use Gradle to generate an Eclipse project from the gradle.build file. The Android plugin enhances this process by setting up the Eclipse project correctly for Android, which includes establishing the correct class path and inserting the Android builders into the build process.

As you will see, Eclipse integration has been included in the Backbone Project via the inclusion of the following line of the build.gradle script:

apply plugin: 'eclipse'

After downloading the Backbone source, you can generate the Eclipse project files by running the following task:

gradle eclipse

Using Intellij as your IDE

More to follow…