Configuration

To use this plugin you must add it to your project and then configure it to your environment.

Adding the Plugin

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

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

buildscript {
    repositories {
        flatDir dirs: "{DashO's Installation Directory}/gradle"
    }
    dependencies {
        classpath "com.preemptive:dasho:3.1.+"
    }
}
apply plugin: 'com.preemptive.dasho' //or 'com.preemptive.dashoJar', or 'com.preemptive.dashoCustom'

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

buildscript {
    repositories {
        flatDir dirs: "{DashO's Installation Directory}/gradle"
        jcenter()
    }
    dependencies {
        classpath "com.preemptive:dasho:3.1.+"  //This must be before the Android tools
        classpath "com.android.tools.build:gradle:3.1.0"
    }
}
apply plugin: 'com.android.application' //or 'com.android.library'

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

Configuring the Plugin

Configuration for DashO's tasks is done via the dashOConfig closure. All these settings are optional, but some are only used with the Android integration.

• General Settings
  • dashOHome - The path to the directory where DashO is installed. If not configured here, this information must be provided via an environment variable named DASHO_HOME.
  • doxFilename - The name of the DashO configuration (.dox) file. It defaults to "project.dox" or a name based on the flavor of an Android build.
  • includeAsInputs - The names of support libraries which should be included as inputs and not support libraries. This setting is a list of .jar files. The files listed here must already be part of the Gradle compile classpath or an error will occur. If used with an Android project, .aar files can also be listed. When specifying an .aar file the plugin will pass the corresponding classes.jar file to DashO. See the Android Configuration section for more details.
  • maxHeap - Allows setting the max heap size to use when running DashO. Valid units are G, M, K, and B for gibibytes, mebibytes, kibibytes, and bytes respectively. If no unit is specified, mebibytes is assumed. This setting is only available in versions 1.7 and later of this plugin. If you are using an older version, see the OutOfMemory troubleshooting solution.
  • verbose - Tells the plugin to run DashO with the --verbose and --printStackTraces arguments (defaults to false). This setting is only available in versions 2.3.4 and later of this plugin. This also enables SHOW_DASHO_CMD in versions 3.1.2 and later of this plugin.
  • debug - Tells the plugin to run DashO with the --debug argument (defaults to false). This setting is only available in versions 3.2.0 and later of this plugin. Enabling debug also enables the verbose option.
• Android Specific Settings
  • dexExcluded - DashO's com.android.application plugin will detect 3rd party libraries which were included as inputs to DashO and will exclude the original jars from dex. This setting overrides the plugin's detection and supplies the list of 3rd party libraries (.jar or .aar) to be excluded from dex. Use the --info option, when running Gradle, to print out the detected exclusions.

    Note: If configuring both dexExcluded and includeAsInputs, you should include the entries from includeAsInputs in the dexExcluded setting. Since version 3.0.1, the includeAsInputs and dexExcluded configurations utilize the names of the inputs provided by the Transform API. If custom transforms do not pass along that name, the DashO plugin may not be able to properly identify the resources. The build cache may also prevent the lookups. You may need to disable caching.

  • disabledForBuildVariants - (Only supported in v3.0.2 and v3.0.3. Use minifyEnabled in v3.1.+.) This setting allows protection to be skipped for specific build variants. It can include the names of build types (e.g. debug), product flavors (e.g. free), or a combination of both (e.g. freeDebug).
  • disabledForBuildTypes - (Only supported prior to v3.1.0. Use minifyEnabled in v3.1.+.) Equivalent to disabledForBuildVariants, but available in version 3.0.1 and earlier.
  • generateProGuardMap - Tells the plugin to create a mapping.txt file with renaming changes (defaults to true). Some 3rd party analytics tools expect this file. This setting is available in versions 3.0.3 and later of this plugin.
  • skipManifestProcessing - Tells the plugin to skip processing the AndroidManifest.xml (defaults to false). This setting can help if you have complex manifest merges in your android build. This setting is only available in versions 2.3.1 and later of this plugin.

    Note: If setting skipManifestProcessing to true you must also configure the DashO project to not rename the classes listed in AndroidManifest.xml.

  • transformName - Allows configuration of the name used for the transform which can help in rare situations where other (third-party) plugins expect a specific name. This setting is only available in versions 2.2.1 and later of this plugin.

Example

dashOConfig {
    dashOHome = '{DashO's Installation Directory}'
    doxFilename = 'project.dox'
    includeAsInputs = ['support-2.3.aar', 'myLibrary.jar']
    maxHeap = '512M'
    verbose = true
    debug = false
    dexExcluded = ['support-2.3.aar', 'myLibrary.jar', 'myOtherLibrary.jar']
    generateProGuardMap = true
    skipManifestProcessing = false
    transformName = 'PreEmptiveProtectionDashO'
}

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 - Your output in DashO must be configured to be a merged directory.

Note: With this plugin, the contents of DashO's output directory will be deleted before DashO runs.

• com.preemptive.dashoJar - Your output in DashO must configured to be a jar.

• com.preemptive.dashoCustom - Your output in DashO must match the output required by whichever custom task you use.

• com.android.application or com.android.library- Please see Android Configuration.

Note: The DashO Gradle Plugin will use the same version of Java as configured for Gradle when running DashO. This can be configured with the org.gradle.java.home setting.

Enabling Protection

When you apply the DashO Gradle Plugin, it integrates into your Gradle build process differently based on which plugin is applied.

com.preemptive.dasho

When you apply plugin: 'com.preemptive.dasho' to a project that has apply plugin: 'java', an obfuscate task is added which will run before Gradle creates a jar file. The jar file will contain the protected classes. If you run gradlew jar or gradlew build the obfuscate task will be run because those tasks depend on it.

com.preemptive.dashoJar

When you apply plugin: 'com.preemptive.dashoJar' to a project that has apply plugin: 'java', an obfuscateJar task is added which will run after Gradle creates a jar file. The protected jar file will be placed in the obfuscated_libs directory in the build output. You can run gradlew obfuscateJar directly, but it will also be run as part of a gradlew build.

Note: If you just run gradlew jar the obfuscateJar task will not be run because it is not required by the jar task.

com.preemptive.dashoCustom

When you apply plugin: 'com.preemptive.dashoCustom' to a project that has apply plugin: 'java', no tasks are added. You need to define your own. See the Customization page for more details.

com.android.application and com.android.library

The integration with the Android plugin is updated as improvements and changes are made to Google's Android Gradle plugin. You must use the appropriate version of the DashO plugin based on which Android Gradle plugin you are using.

Prior to v1.8.0

If integrating with a version before v1.8, the plugin adds an obfuscate[BuildFlavor][BuildType] task for application (APK) projects and an obfuscate[BuildFlavor][BuildType]Library task for library (AAR) projects. These tasks are added for builds not excluded by disabledForBuildTypes.

From v1.8.0 to v3.0.x

From v1.8 to v3.0.x, the plugin adds transforms to the Android build process. It creates these transforms for all build types and build flavors that are not excluded by disabledForBuildTypes or disabledForBuildVariants. Here are some examples:

• disabledForBuildTypes = ['debug'] //Do not protect debug builds

• disabledForBuildTypes = ['release'] //Do not protect release builds

• disabledForBuildTypes = ['debug', 'release'] //Do not protect debug or release builds

• disabledForBuildTypes = [] //Protect all builds (This is the default behavior when disabledForBuildTypes is not set.)

• disabledForBuildTypes = ['free'] //Do not protect builds with the "free" flavor

• disabledForBuildTypes = ['freeDebug'] //Do not protect debug builds with the "free" flavor

Notes:
disabledForBuildVariants is only available in v3.0.2 and v3.0.3, but it works the same as disabledForBuildTypes.

If you want to disable DashO for a specific project, add dashOConfig {disabledForBuildTypes=['debug', 'release']} or dashOConfig {disabledForBuildVariants=['debug', 'release']} inside the build.gradle file of that project.

v3.1.+

Starting with v3.1, the standard minifyEnabled setting is used to determine if DashO should be run. The disabledForBuildTypes or disabledForBuildVariants settings are no longer supported. If upgrading from an earlier version, make sure to set minifyEnabled true in build.gradle for the builds you want protected.

android {
    buildTypes {
        release {
            minifyEnabled true
        }
    }
}

Verifying DashO is Running

Regardless of which plugin is applied, you should see PreEmptive Protection - DashO(tm) vX.Y.Z in the console when those tasks get run. If you are not seeing that, consult the Troubleshooting section.