Overview

The PreEmptive Solutions DashO Gradle Plugin allows you to integrate DashO's obfuscation and instrumentation into your existing Gradle build process. You may use one of our integrated plugins or create your own task. The DashO plugins support Gradle's UP-TO-DATE checking, so if your classes and configuration do not change between runs, the DashO tasks will be skipped, saving build time.

Plugins

Five plugins are provided:

Requirements

  1. Gradle 2.14.1
  2. Java 1.8
  3. DashO 7.5 (or later)
  4. If using the com.android.application or com.android.library plugin, see Version Compatibility.

Configuration

The plugin jar must be made available to your Gradle script.

If using com.preemptive.dasho, com.preemptive.dashoJar, or com.preemptive.dashoCustom, add the following to your build script:

buildscript {
    repositories {
        flatDir dirs: "{DashO's Installation Directory}/gradle"
    }
    dependencies {
        classpath "com.preemptive:dasho:2.2.+"
    }
}

If using DashO's com.android.application or com.android.library you will also need the core Android plugin in the mix (See Version Compatibility):

buildscript {
    repositories {
        flatDir dirs: "{DashO's Installation Directory}/gradle"
        jcenter()
    }
    dependencies {
        classpath "com.preemptive:dasho:2.2.+"  //This must be before the Android tools
        classpath "com.android.tools.build:gradle:2.2.0" 
    }
}

Note: Use forward slashes when replacing {DashO's Installation Directory} with the actual path (E.G. "C:/Program Files/..." instead of "C:\Program Files\...").

Configuration for DashO's tasks is done via the dashOConfig closure. This closure takes six properties:

Example

dashOConfig {
    dashOHome = '{DashO's Installation Directory}'
    doxFilename = 'project.dox'
    includeAsInputs = ['support.aar', 'myLibrary.jar']
    disabledForBuildTypes = ['debug']
    dexExcluded = ['support.aar', 'myLibrary.jar', 'myOtherLibrary.jar']
    maxHeap = '512M'
}

Note: If configuring both dexExcluded and includeAsInputs, you should include the entries from includeAsInputs in the dexExcluded setting.

Note: includeAsInputs and dexExcluded may not be able work properly with the new Transform API, introduced in version 1.5.0 of the Android Gradle Plugin, due to limitations in that system. The plugin will not be able to properly identify resources if they have been updated by other transforms. You may need to remove any custom transforms.

The plugins will pass the inputs and outputs as User Properties to DashO, your project file should use ${gradleInput} and ${gradleOutput} as the input and output locations. They will also pass the required support jars in ${gradleSupport}. See the DashO User's Guide for information concerning User Properties. If you use the DashO Android wizard, it will set up these properties automatically. The configured output type needs to match the plugin you are using:

com.preemptive.dasho

If using the com.preemptive.dasho plugin your output in DashO must be configured to be a merged directory.

Note: The contents of DashO's output directory will be deleted before DashO runs.

com.preemptive.dashoJar

If using the com.preemptive.dashoJar plugin, your output in DashO must configured to be a jar.

com.preemptive.dashoCustom

If using the com.preemptive.dashoCustom plugin, your output in DashO must match the task type being used.

DashO's Android Configuration

If using DashO's com.android.application or com.android.library plugin, your output in DashO must be configured to be a jar. In addition to configuring ${gradleInput} and ${gradleOutput}, a non-class file must be configured for the AndroidManifest.xml. Use ${AndroidManifestFile} as the source file and ${AndroidManifestOutput} as the relative destination. You will also need to add the correct android.jar file to the supporting classpath section of your .dox file and use your package name as the renaming prefix. If you are obfuscating a library, you should also configure DashO to remove the compiled {package name}.R* classes and make sure the classes which will be referenced by applications are configured as entry points.

DashO has a project wizard that will configure most of these settings for you, if you use it for initial DashO project setup.

Note: If you have a setup with multiple Gradle projects built at the same time, you will need to disable DashO on the other projects. You can quickly do this by adding dashOConfig {disabledForBuildTypes=['debug', 'release']} inside build.gradle of the other projects until you have configured them to use DashO.

The following User Properties can also be used if needed:

Note: The signing information is only passed when it is configured in the Android build.

Build Flavors

If you are working with different build flavors in your Android configuration and need different DashO configurations for the different flavors, you will need to create multiple DashO configuration files, name them based on the flavor, and remove any doxFilename setting from the dashOConfig closure. For Example: If you have two flavors: personal and pro, you would create a personal.dox and pro.dox configuration. When the DashO task runs, and does not find any configured doxFilename, it will search for a file based on the flavor/build type (E.G. proDebug.dox, pro.dox, or debug.dox) If it can't find one, then it will assume project.dox.

Note: If you use flavor dimensions, the final name for each combined flavor should be used to name the .dox file.

Advanced functionality

APK Splitting

The DashO Gradle plugin supports the APK Splitting functionality provided by the base Android Gradle plugin.

Multidex

The DashO Gradle plugin supports, on Lollipop (and later) devices, the multidex functionality provided by the base Android Gradle plugin. For older devices you will need to make the following changes to your .dox file.

  1. Add the multidex library to your inputs. It will probably be located in build/intermediates/exploded-aar/com.android.support/multidex/1.0.1/jars/classes.jar.
  2. Add the android.support.multidex.MultiDexApplication class with its <init>() method as an Entry Point.

Resource Shrinking

The DashO Gradle plugin supports the resource shrinking functionality provided by the base Android Gradle plugin. It is recommended DashO be configured to remove all non-used classes and methods as resource shrinking relies on checking the compiled code for references to the resources.

Instant Run

Instant Run is not supported by DashO. If Instant Run is enabled, the DashO Transform will automatically be turned off. This should not affect your release builds. If you want to disable Instant Run, view the instructions at http://developer.android.com/studio/run/index.html#disable-ir

Built-in Shrinker

If you want to use the Android's experimental non-obfuscating built-in shrinker, follow the instructions at http://tools.android.com/tech-docs/new-build-system/built-in-shrinker. Then add that build type to the disabledForBuildTypes in the dashOConfig configuration.

Jack and Jill

DashO is not currently compatible with the experimental Jack and Jill build tools. You will need to use the standard build tools.

Customization

If the integrated plugins do not work for you, we allow you to create your own Gradle task leveraging DashO by using the com.preemptive.dashoCustom plugin and extending a provided task type.

Task Types

The plugin defines two task types:

The DashO project should be configured with the correct output type based on the task type being used.

These tasks can utilize the same dashOConfig or those properties may be configured in your custom task. When defining your custom task you will need to specify the input and output file (or directory). Simply calling the from and to methods will configure the ${gradleInput} and ${gradleOutput} properties for DashO. The setSupportClasspath(classpath) method can be used to set ${gradleSupport}. The string should be formatted like a standard Java classpath; utilizing the path delimiter specific to your OS. If you have a need for your custom task to pass additional user properties to DashO, you can specify them by using the addUserProperty(name, value) method.

Example

task myCustomDashOTask (type:DashODirTask) {
    from("$MyInputDirectory")
    to("$MyOutputDirectory")
    setSupportClasspath("$MyClasspath")
    addUserProperty("MyPropertyName", "MyValue")
    addUserProperty("MyOtherPropertyName, "MyOtherValue")
}

Version Compatibility

You will need to select the appropriate version of the DashO Gradle Plugin based on the Android Gradle Plugin you use:

Android Gradle Plugin DashO Gradle Plugin
0.14.3, 0.14.4,
1.0.0-rc*,
1.0.x
1.4.x
1.1.x 1.5.0
1.2.x 1.6.0
1.3.0, 1.3.1 1.7.0
1.5.0 1.8.x
2.0.0 2.0.0
2.1.0 2.1.0
2.2.0 2.2.0

Troubleshooting

Verifying the plugin is available.

Run gradlew tasks

If you applied the com.preemptive.dasho or com.preemptive.dashoJar plugin, you should see tasks like obfuscate or obfuscateJar listed in the build section.

If you applied the com.android.application or com.android.library plugin the tasks differ based on the version of the plugin you are using. If you are using the 1.7 (or earlier) plugin, you should see tasks like obfuscate[Flavor]Release or obfuscate[Flavor]LibraryRelease listed in the build section. If you are using the 1.8 (or later) plugin, you should see a dashOPluginVersion task listed in the other section.

If you do not encounter an error and do not see one of those tasks listed, make sure you have applied the plugin in your script.

If you encounter an error, first double-check the versions being used. See Version Compatibility.

Here are some common errors and solutions:

Error: Unexpected char '\' ... flatDir dirs: {The Path to the DashO Installation}

Make sure you use forward slashes ('/') when specifying the path.

Error: Could not find method dashOConfig() for arguments...

Make sure you apply one of the plugins: com.preemptive.dasho, com.preemptive.dashoJar, com.android.application, com.android.library, or com.preemptive.dashoCustom. If you applied com.android.application or com.android.library double check the order of the dependencies. Also make sure that dashOConfig is not inside any other closure.

Error: Plugin with id 'com.preemptive.dasho*' not found.

Make sure you have referenced the plugin in the dependencies closure.

Error: Could not find any version that matches com.preemptive:dasho:X.Y+.

Make sure you have referenced the directory containing the dasho-x.y.z jar file in the repositories closure.

Error: Could not create plugin of type 'AppPlugin' (or 'LibraryPlugin').

Make sure you are using compatible versions of the Android and DashO plugins. See Version Compatibility.

Error: Failed to notify project evaluation listener.

Make sure you are using compatible versions of the Android and DashO plugins. See Version Compatibility.

Error: unable to resolve class com.android.build.OutputFile (or some other com.android... class)

Make sure you are using compatible versions of the Android and DashO plugins. See Version Compatibility.

Error: A problem occurred evaluating [root] project ...

Make sure you are using compatible versions of the Android and DashO plugins. See Version Compatibility.

Verifying the configuration is correct.

Run gradlew build

If you applied and configured the plugin correctly, DashO will obfuscate your code.

If you encounter an error, here are some common errors and solutions:

Error: File '{project path}/project.dox' specified for property 'doxFile' does not exist.

Solution 1: Make sure you have specified the doxFilename in the dashOConfig closure. It defaults to look for project.dox or a name based on the flavor of an Android build.

Solution 2: You are using DashO's com.android.application or com.android.library plugin and have other Android projects which are compiled in the same Gradle build which are not yet configured to use DashO. Add dashOConfig {disabledForBuildTypes=['debug', 'release']} inside build.gradle of the other projects until you have configured them to use DashO.

Error: DashOHome is not configured.

Make sure you either specify the dashOHome in the dashOConfig closure or in the DASHO_HOME environment variable.

Error: tried to access method org.gradle.api.tasks.JavaExec.exec()V...

You are using an old version of Gradle, please upgrade to a later version.

Errors during obfuscation

If an error occurs during obfuscation the information should be listed in the output. Double check that you used ${gradleInput} and ${gradleOutput} in your DashO configuration.

Error: java.lang.OutOfMemory: Java heap space or java.lang.OutOfMemory: GC overhead limit exceeded

Increase (or set) the maxHeap (see the configuration section). If you are using a version earlier than 1.7 try the following:

  1. Add a new task to the gradle build script. Make sure you define it with the proper obfuscation task name(s) you see when running gradlew tasks.

     task setMaxMem << {
         project.tasks['obfuscateDebug'].maxHeapSize=536870912 //bytes
         project.tasks['obfuscateRelease'].maxHeapSize=536870912 //bytes
     }
    
  2. Call it manually before your build task (E.G. gradlew setMaxMem build)

Gradle issues after obfuscation

Some errors can occur from misconfiguration of the project .dox file.

Error: {BUILD_DIR}\manifests\debug\..\dasho-debug\AndroidManifest.xml: error: Unable to open file for read: No such file or directory.

Solution 1: Make sure you have specified ${AndroidManifestFile} and ${AndroidManifestOutput} in the Non-Class Files section of the .dox file.

Solution 2: Make sure you are using DashO version 7.5 (or later).

Issue: I am using the com.preemptive.dasho plugin and there are no classes in the jar file created by Gradle.

Make sure you have used ${gradleOutput} as the output location the .dox file (and that it is a merged directory).

Issue: I am using the com.preemptive.dashoJar plugin and do not see the obfuscated_libs directory in my build folder.

Make sure you have used ${gradleOutput} as the output location the .dox file (and that it is a jar file).

Temporarily Disabling DashO Integration

If you would like to run a build without the tasks added by DashO, you can disable them by adding -DDISABLE_DASHO=true to the command line when you run gradlew.

Note: The DISABLE_DASHO=true setting will have no impact if you are using the com.preemptive.dashoCustom plugin as it does not add any tasks.

Troubleshooting Parameters

If you would like to see all the parameters passed to DashO, add -DSHOW_DASHO_CMD=true to the command line when you run gradlew. Note: This is only supported in versions 1.7 and later.


DashO Gradle Plugin Version 2.2.0. Copyright © 2016 PreEmptive Solutions, LLC