Gradle Build Environment

This section will walk you through setting up an existing Android application (APK) or library (AAR) project to use PreEmptive Protection - DashO. The setup process differs if you use Gradle for your build environment or you are working directly with an APK file. DashO can integrate into the Android Gradle build process.

When integrated into the Gradle build script, DashO takes in the Java class files and protects them. In an application project, the build script then takes the obfuscated version to create the classes.dex file which is packaged inside the APK file. In a library project, the build script then takes the obfuscated version and packages it inside the AAR file.

Note: You can use the DashO-GameOfLife sample to walk through the process.

Prerequisites

You will need to have an Android application (APK) or library (AAR) project, which you can create either through Eclipse, Android Studio, or manually. If you create it in Eclipse or Android Studio you should still know the physical location of the project. Eclipse and Android Studio know where the Android SDK is located and create the appropriate references for you.

DashO will need to have access to the locations of the Android SDK and the Android project. They don't all have to physically be on the same machine as long as the file system has access to them. If they are not all on the same machine, you can map network drives to provide access.

Stage your Android project for PreEmptive Protection - DashO

If you setup your project with Android Studio, you already have a Gradle build. If you are using Eclipse and do not have a Gradle build, follow Android's instructions to migrate.

After you have created the build.gradle file, compile your project:

gradlew build

This will download Gradle and build your android project.

Create a PreEmptive Protection - DashO project with the wizard

The New Project Wizard may start automatically when you start DashO. If DashO is already running, you can start the wizard from File > Project Wizard. Choose “An Android application or library” in the “Select Application Type” Wizard screen, and then select the “Gradle” build environment and enter your Android project directory in the “Select Android Project” screen.

The Wizard will perform most of its work automatically. The Wizard will attempt to discover references to support JARs automatically, but in some cases you may have to add them manually. One of the Wizard screens gives you the opportunity to add additional JARs. It will also allow you to change the version of android.jar (the main Android API library), but under most circumstances you shouldn't change this.

The Wizard saves a file called project.dox in the root of the Android project folder. This file contains all of the DashO configurations for this project. It also creates a dasho.gradle and updates the build.gradle allowing DashO to obfuscate the code. Quickly test it by running gradlew assembleRelease from the command prompt. By default, the wizard turns off obfuscation for debug builds.

A full walkthrough of the wizard can be found in the Android Applications and Libraries section.

Configure obfuscation with the PreEmptive Protection - DashO GUI

Now that you have your staged Android project loaded into DashO, you can use the DashO GUI to make the desired configurations. Remember to save your project, which will update the project.dox file. To change the configuration settings later, run DashO, open your project.dox file, make your changes, and save.

See the User Interface Reference section for a walkthrough of the DashO GUI.

You can test your configurations to see if they build correctly by building the project within the GUI.

Make a full build with Gradle

To run a full build, navigate to the Android project folder on the command line and run gradlew build. Any errors or warnings will be output to the screen.

If your environment is setup to build multiple Android projects from the same gradle script, you may get an error regarding missing a project.dox file for any project that is not yet configured to use DashO. To fix this, you can turn off obfuscation in those projects until you create the configuration files.

Note: If your build compiles an Android library (AAR) which is only used as part of your application, you should not obfuscate the library directly. Instead, include the library as an input to the application project.

Install your obfuscated APK to an emulator

The Gradle build, for an application project, will create a folder called build\outputs\apk which may contain different versions of the APK. By default, the debug version is not obfuscated, so the one you want is {project name}-release-unaligned.apk. Double check the time stamp, but this should be the one which was just created by the Grade build.

With the emulator running, type adb install {project name}-release-unaligned.apk. This will install the APK to the running emulator. You can then access the application by using the emulator and navigating to the applications list. The installed application will appear just like any other Android app installed on a device.

Note:
You can also enable obfuscation on the debug build, by editing dasho.gradle, and then just run gradlew installDebug to install on an emulator.

Make and sign a release build

To make a release build, which is required for installing to a physical device, you have to create a signing key and provide this information to the Android Gradle plugin. You provide this information inside build.gradle.

android {
    ...
    signingConfigs {
        release {
            storeFile file("android.keystore")
            storePassword "password"
            keyAlias "alias"
            keyPassword "password"
        }
    }
}

Once the signing information is added, gradlew build will produce a signed release APK. Running gradlew installRelease will compile and install a release build on an emulator.

Note:
Please consult the Android Gradle Plugin User Guide and DashO Gradle Plugin User Guide for additional information.

Run on another machine

Copying the project directory from one machine to another and then running gradlew build should work as long as DashO and the Android SDK are available to the other machine. You may need to update dasho.gradle to point to the new location of DashO and update build.gradle to point to the directory containing the DashO Gradle plugin.

Your best solution will be to prepare an environment ahead of time in such a way that one build machine has access to the different tools mentioned above. If you have already created your Android project or otherwise can't create a new project after having setup your environment, you may find that you need to edit the build.gradle, dasho.gradle and/or one or more of the *.properties files to reflect the correct locations. You will know this when you get an error message that claims that something can't be found. If that happens, note the location that the build is looking for, find the similar location in your build environment and update the reference.