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 namedDASHO_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 correspondingclasses.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 areG
,M
,K
, andB
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 tofalse
). This setting is only available in versions 2.3.4 and later of this plugin.
- Android Specific Settings
dexExcluded
- DashO'scom.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
andincludeAsInputs
, you should include the entries fromincludeAsInputs
in thedexExcluded
setting. Since version 3.0.1, theincludeAsInputs
anddexExcluded
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. UseminifyEnabled
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. UseminifyEnabled
in v3.1.+.) Equivalent todisabledForBuildVariants
, but available in version 3.0.1 and earlier.generateProGuardMap
- Tells the plugin to create amapping.txt
file with renaming changes (defaults totrue
). 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 theAndroidManifest.xml
(defaults tofalse
). 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
totrue
you must also configure the DashO project to not rename the classes listed inAndroidManifest.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
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
orcom.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
theobfuscateJar
task will not be run because it is not required by thejar
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 whendisabledForBuildTypes
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 asdisabledForBuildTypes
.
If you want to disable DashO for a specific project, adddashOConfig {disabledForBuildTypes=['debug', 'release']}
ordashOConfig {disabledForBuildVariants=['debug', 'release']}
inside thebuild.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.