Upgrading

PreEmptive Protection™ DashO™ for Android & Java v10.0 adds new major features, changes existing features, and removes some previously-deprecated features. Your DashO project configurations may need to be updated. The details below will help you understand the changes, and how to update your project configurations accordingly. See the change log for a list of the changes.

Android Support

In DashO 10, we are introducing a new Android build integration with the new DashO Gradle Plugin for Android which uses Android Mode and works with R8. The older Android build integration via the DashO Gradle Plugin (now called the DashO Gradle Plugins for Java) has been deprecated. DashO can still be run via this legacy integration, but you will be limited to specific versions of the Android Gradle Plugin.

Switch to the New Android Build Integration

You can switch to the new DashO Gradle Plugin for Android integration either by using the new Migration Wizard, or by manually editing your Gradle build scripts (e.g., build.gradle and dasho.gradle files) and DashO configuration.

Migration Wizard

The wizard examines your build environment in order to migrate your build to use the new integration, and will update your Gradle build scripts, your DashO configuration file, your gradle.properties file, and/or your .gitignore file(s) as appropriate.

You can start the wizard by going to File > Project Wizard. Select Upgrade Android Gradle project to DashO 10.

Select the DashO config file that you would like to migrate and click Next. Then, click Finish to allow the wizard to modify your files.

The DashO GUI will load the project file, and you may be prompted to build (e.g., gradlew assembleRelease). Once the build is complete, you can reload the project's classes by going to Project > Reload Class List.

Next Steps (If Needed)

We expect that the changes made by the wizard will be sufficient for most projects to start using the new integration. However, if you run into issues, you may need to manually migrate DashO settings to R8. The wizard will open your DashO configuration in a text editor so that you can perform these migrations if necessary.

Migrating Manually

Migrating Manually

Your existing Gradle build scripts can be migrated to use this new plugin in a few steps.

Apply the New Plugin

Replace the following lines in your build.gradle files.

Add a new line to apply the plugin:

// After these lines (you should have only one):
apply plugin: 'com.android.application'
apply plugin: 'com.android.library'

// Add this line:
apply plugin: 'com.preemptive.dasho.android'

// But add it before this line (if you have it):
apply from: 'dasho.gradle'

Update the Plugin Configuration

The prior plugin used a dashOConfig closure for configuration. The new plugin uses a dasho closure for configuration. Your existing closure may be located in dasho.gradle.

Rename the dashOConfig closure to dasho, and then update or remove the settings it contains based on the following table:

Note:
If you used minifyEnabled with earlier versions of DashO to obfuscate non-release build types, you will need to specify enabledBuildVariants with a pattern that matches those build types.

Enable R8

As mentioned in Getting Started, the DashO Gradle Plugin for Android delegates renaming and removal to R8. Follow these instructions to enable R8 in your build.

Update the DashO Configuration

Your project must be updated to use Android Mode. Repeat these steps for all the .dox files related to your project:

1. Open the .dox file in the DashO GUI. DashO will automatically upgrade file to the new version.
2. Save the upgraded version.
3. Open the .dox file in a text editor, and replace the opening dasho tag with: <dasho mode="android" version="10.0.0">.
4. Reload the file in the GUI when prompted (it should notice the change and prompt you to reload). You will see several warnings about ignored elements and options.
5. Click OK on the prompt regarding running a build.
6. Run a full build with gradlew clean build. DashO may emit warnings about ignored config settings during the build. After building, the DashO GUI should prompt you to reload your classes.

Next Steps (If Needed)

We expect that these steps will be sufficient for most projects to start using the new integration. However, if you run into issues, you may need to manually migrate DashO settings to R8.

String Encryption and Reflection in Android Mode

String Encryption may prevent R8 from detecting that certain classes are loaded via reflection. See this section for details.

Migrate Specific DashO Settings (If Needed)

If you had any hand-configured exclusions in your .dox file, you may or may not need to migrate these exclusions to rules for R8. The Android Gradle Plugin automatically generates exclusions for things that it knows will cause issues, and this may cover some or all of your exclusions. After running a full build (gradlew clean build), review the file containing the generated rules at:

build/intermediates/proguard-rules/{flavorName}/{buildType}/aapt_rules.txt

You will need to add rules for any exclusions not covered by this file.

Note:
The DashO GUI will not show configuration settings that are ignored in Android Mode, so you will need to open your configuration file in a text editor to determine what needs to be migrated.

To get started, make sure R8 is enabled, create an empty migrated-rules.pro file, and add the following after minifyEnabled true:

proguardFiles getDefaultProguardFile('proguard-android.txt'), 'migrated-rules.pro'

The rules contained in the files specified as proguardFiles combine with the rules generated by the Android Gradle Plugin and any rules embedded in the libraries (AAR) used by your project.

Note:
The proguardFiles configuration should be repeated for every build type where minifyEnabled is set to true.

Resolve Warnings about Ignored Config Settings

As mentioned above, many sections of the .dox file do not apply to Android Mode. Warnings will be produced for all the ignored elements, attributes, and values.

Some may require migration:

The majority of ignored warnings deal with features which are either not applicable to Android or are automatically handled by Android Mode or R8. They can be removed:

• <classpath>
• <includenonclassfiles>
• <inputpath>
• <make-synthetic>
• <output>
• <premark>
• <preverifier>
• <report>
• <seInput>
• <seOutput>
• <signjar>
• Many <global> <option>s
  • force
  • fornamedetection
  • ignorebrokencalls
  • ignorenotfoundclasses
  • makepublic
  • nomakepublic

Note:
<exclude> (nested under <global>) allowed the explicit removal of classes. It is not supported in Android Mode and there is no similar functionality in R8.

Clean Up Unnecessary Properties

There may be many Properties from your existing project that were used by the previous integration with Android. If these properties are not referenced by the remaining settings, they can be removed:

• AndroidManifestFile
• AndroidManifestOutput
• build.dir
• buildType
• buildVariant
• dasho.results.dir
• gradleInput
• gradleOutput
• gradleSupport
• key.store
• KEY_ALIAS
• KEY_ALIAS_PASSWORD
• KEYSTORE
• KEYSTORE_PASSWORD
• manifest.package
• projectname
• sdk.dir
• sdk.target

Migrate Removal and Renaming Settings

DashO's renaming and removal are configured in the <entrypoints>, <renaming>, and <removal> elements. Most of the entry points will be located at runtime by the Android Gradle Plugin when it generates aapt_rules.txt. If your specific case was not automatically handled you will need to add any necessary rules. Some basic Removal and Renaming rules are shown below. Add any necessary rules to migrated-rules.pro.

Note:
The functionality to explicitly remove classes is not supported by DashO, in Android Mode, and there is no corresponding functionality in R8.

Migrate Removal Settings

The removal of unused classes, methods, and fields, is delegated to R8. By default, R8 will remove any of these which are not used by those it was told to keep. Below are some basic rules to configure the R8's removal settings.

Note:
The ,allowobfuscation part in some of the rules below can be removed if you want the names kept as well.

To turn off removal:

-dontshrink

To keep all public classes:

-keep,allowobfuscation class public *

To keep all public members:

-keep,allowobfuscation class * {
    public <methods>;
    public <fields>;
}

To preserve a specific class or method:

-keep,allowobfuscation class com.example.ClassName { <init>(); }

To keep certain attributes:

-keepattributes "{attribute names}"

Notes:

DashO configures which attributes to remove, while R8 configures which attributes to keep.

The default settings for R8 are very similar to the default settings for DashO. The main difference is DashO will remove the annotations which are not visible at runtime, while R8 keeps them.

Migrate Renaming Settings

DashO and R8 have different ways of determining the new names. R8 does not have a feature that directly corresponds with DashO's alphabet settings. It generates names using a hardcoded alphabet but can be configured to use a dictionary of pre-generated names with the -obfuscationdictionary {filename}, -classobfuscationdictionary {filename}, and -packageobfuscationdictionary {filename} options.

To turn off renaming:

-keepnames class ** { *; }

To flatten the hierarchy:

-allowaccessmodification
-repackageclasses "com.example.package"

Note:
-allowaccessmodification is already enabled in the optimize configuration.

To keep all public member names:

-keepclassmembernames class * {
    public <methods>;
    public <fields>;
}

To preserve a specific class, method, or field name:

-keepnames class com.example.ClassName

-keepclassmembernames class com.example.ClassName {
    int method(...);
    boolean field;
}

Note:
The R8 renaming map file can be found at build/outputs/mapping/r8/{flavorName}/{buildType}/mapping.txt.

Migrate Method Call Removal

If you have configured DashO to remove method calls, you will need to convert those rules. Your project's .dox file will have an entry with all the overloaded signatures for the method call:

<methodCallRemoval>
    <method className="android.util.Log" methodName="v"
        signature="java.lang.String, java.lang.String"/>
    <method className="android.util.Log" methodName="v"
        signature="java.lang.String, java.lang.String, java.lang.Throwable"/>
</methodCallRemoval>

To migrate this, add the following to migrated-rules.pro:

-assumenosideeffects class android.util.Log {
    public static int v(...);
}

Note:
Call removal only works with the optimize configuration.

Migrate Optimization

There are two different built-in R8 Android configurations: proguard-android.txt and proguard-android-optimize.txt. These two configuration files are distributed by the Android Gradle Plugin and can be found in the build/intermediates/proguard-files directory within your application or library module's directory after running a build. The configuration which will be used is configured with proguardFiles getDefaultProguardFile('proguard-android[-optimize].txt'). Do not include any version number from the actual file's name in build/intermediates/proguard-files when configuring.

Reflection

If you are using reflection to load classes, you will want to exclude the classes (or methods) which reference the class names from String Encryption and add the -adaptclassstrings option to migrated-rules.pro.

Removal of Deprecated Support Classpath Options

The "Append current Java runtime" and "Use Classpath from Environment" options on the Input - Supporting Classpath screen were deprecated in DashO 9.0, and have now been removed. Projects that were using these options will need to be updated to instead use Include JDK.

Note:
Historically, the "Append current Java runtime" option was enabled by default. The DashO build will terminate with an error for projects that were using this deprecated feature and are not modified to use Include JDK.

Method Call Removal Changes

Wildcard class matching support for method call removal has been removed. If you used ** to indicate a method in any class, you must change the configuration to match specific classes.

Removal of Legacy Facilities

DashO's public get*Version*() methods have been removed.

The diagnostic tool JVMInfo has been removed.

The DashO Eclipse Plugin has been removed.

The deprecated properties ${dasho.java.version}, ${jce.jar}, and ${jsse.jar} have been removed and will no longer automatically resolve.

Changes to Proxy Configuration

Proxy configuration within the DashO GUI has been removed. If you use DashO in an environment that requires use of a proxy to access the internet, you will need to configure your proxy settings.