Gradle Plugins for Java Configuration – Preemptive Support Center

To use any of the DashO™ Gradle Plugins for Java, you must add the artifact that contains them to your Gradle build script's classpath, apply the plugin that you want to use, and then configure the plugin for your environment.

Applying a Plugin

All three plugins are packaged together in a single jar, which must be made available to your Gradle build script. Add the following to your build script:

buildscript {
    repositories {
        flatDir dirs: "<DashO Home>/gradle"
    }
    dependencies {
        classpath "com.preemptive:dasho:X.y.+"
    }
}
apply plugin: 'com.preemptive.dasho' //or 'com.preemptive.dashoJar', or 'com.preemptive.dashoCustom'

Replace <DashO Home> with the DashO Home path, or reference an environment variable or a Gradle project property that contains the path. DashO Home will vary by platform.

Note: Use forward slashes when replacing <DashO Home> with the actual path on Windows (e.g. "C:/Program Files/..." instead of "C:\Program Files\...").

Configuring the Plugins

You can configure any of the DashO Gradle Plugins for Java with a dashOConfig closure. All of these settings are optional.

dashOHome - This tells the applied plugin where to find DashO Home. If not configured here, this information must be provided via an environment variable or Java Property named DASHO_HOME.
doxFilename - The name of the DashO configuration (.dox) file. It defaults to "project.dox".
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.
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 the plugins. If you are using an older version, see the OutOfMemory troubleshooting solution.
verbose - Tells the applied 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 the plugins. This also enables SHOW_DASHO_CMD in versions 3.1.2 and later of the plugins.
debug - Tells the applied plugin to run DashO with the --debug argument (defaults to false). This setting is only available in versions 3.2.0 and later of the plugins. Enabling debug also enables the verbose option.
Example
```
dashOConfig {
  dashOHome = '<DashO Home>'
  doxFilename = 'project.dox'
  includeAsInputs = ['myLibrary.jar']
  maxHeap = '512M'
  verbose = true
  debug = false
}
```
The applied plugin 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 User Properties section for details.

The configured output type needs to match the plugin you have applied:

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.

Note: The DashO Gradle Plugins for Java 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 a DashO Gradle Plugin for Java, 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

If the integrated plugins do not work for you, you can create your own Gradle task leveraging DashO by using the com.preemptive.dashoCustom plugin and extending a provided task type. When you apply plugin: 'com.preemptive.dashoCustom' to a project that has apply plugin: 'java', no tasks are added. You must define your own.

Task Types

This custom plugin defines two task types:

DashODirTask - Takes a directory as input and outputs to a directory.

Note: The contents of DashO's output directory will be deleted before DashO runs.
DashOFileTask - Takes a jar (or APK) file as input and outputs to a jar (or APK) file.

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

You can configure these tasks using dashOConfig or directly in your custom task's definition.

The custom task must specify the input and output file (or directory). Calling from and to will configure the ${gradleInput} and ${gradleOutput} for DashO.

Calling setSupportClasspath(classpath) will configure ${gradleSupport} for DashO. Format the classpath string like a standard Java classpath, using the path delimiter appropriate for your operating system.

Additional user properties can be passed to DashO, by calling addUserProperty(name, value).

Example

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

Verifying DashO is Running

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

License Configuration

If you need to configure the license to be used by DashO, you can specify the license string via a DASHO_LICENSE Gradle project property, a Java system property, or an environment variable. This is supported in DashO Gradle Plugin v5.0.0 and later.

A Gradle project property can be set in a gradle.properties file, on the command line as a -P argument (e.g. -PDASHO_LICENSE={key[:email]}) or in a system environment variable prefixed with ORG_GRADLE_PROJECT_ (e.g. ORG_GRADLE_PROJECT_DASHO_LICENSE={key[:email]}). A Java property can be set on the command line as a -D argument (e.g. -DDASHO_LICENSE={key[:email]}).