From f062b94cc2c2dc440cb4869b36e88a959aab6e5b Mon Sep 17 00:00:00 2001 From: Rich Slogar Date: Tue, 3 Mar 2015 12:27:16 -0800 Subject: docs: proguard help update b/19383794 b/19417644 Change-Id: I454015fb85601dbd31d3cb364eaa6d0adee0c764 --- docs/html/tools/building/configuring-gradle.jd | 8 +- docs/html/tools/help/proguard.jd | 145 ++++++++++++++++++------- 2 files changed, 108 insertions(+), 45 deletions(-) diff --git a/docs/html/tools/building/configuring-gradle.jd b/docs/html/tools/building/configuring-gradle.jd index 5af20969612c..83795085572c 100644 --- a/docs/html/tools/building/configuring-gradle.jd +++ b/docs/html/tools/building/configuring-gradle.jd @@ -59,8 +59,7 @@ android { buildTypes { release { minifyEnabled true - proguardFiles getDefaultProguardFile('proguard-android.txt'), \ - 'proguard-rules.txt' + proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } } } @@ -187,8 +186,7 @@ android { buildTypes { release { minifyEnabled true - proguardFiles getDefaultProguardFile('proguard-android.txt'), \ - 'proguard-rules.txt' + proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' } } } @@ -197,7 +195,7 @@ android {

getDefaultProguardFile('proguard-android.txt') obtains the default ProGuard settings from the Android SDK installation. Android Studio adds the module-specific rules file -proguard-rules.txt at the root of the module, where you can add custom ProGuard +proguard-rules.pro at the root of the module, where you can add custom ProGuard rules.

Configure signing settings

diff --git a/docs/html/tools/help/proguard.jd b/docs/html/tools/help/proguard.jd index aa9a0bc60fc9..b5d84ed85259 100644 --- a/docs/html/tools/help/proguard.jd +++ b/docs/html/tools/help/proguard.jd @@ -8,7 +8,9 @@ parent.link=index.html

In this document

    -
  1. Enabling ProGuard
    2. +
  2. Enabling ProGuard (Gradle Builds)
    3. + +
  3. Enabling ProGuard (Ant Builds)
  4. Configuring ProGuard
    5. @@ -37,7 +39,10 @@ parent.link=index.html -

    The ProGuard tool shrinks, optimizes, and obfuscates your code by removing unused code and + + +

    The ProGuard tool shrinks, optimizes, and + obfuscates your code by removing unused code and renaming classes, fields, and methods with semantically obscure names. The result is a smaller sized .apk file that is more difficult to reverse engineer. Because ProGuard makes your application harder to reverse engineer, it is important that you use it @@ -45,44 +50,102 @@ parent.link=index.html Licensing Your Applications.

    ProGuard is integrated into the Android build system, so you do not have to invoke it - manually. ProGuard runs only when you build your application in release mode, so you do not - have to deal with obfuscated code when you build your application in debug mode. + manually. ProGuard runs only when you build your application in release mode, so you do not + have to deal with obfuscated code when you build your application in debug mode. Having ProGuard run is completely optional, but highly recommended.

    - +

    This document describes how to enable and configure ProGuard as well as use the retrace tool to decode obfuscated stack traces.

    -

    Enabling ProGuard

    + +

    Enabling ProGuard (Gradle Builds)

    +

    When you create a project in Android Studio or with the Gradle build system, the + minifyEnabled property in the build.gradle file enables and disables + ProGuard for release builds. The minifyEnabled property is part of the + buildTypes release block that controls the settings applied to + release builds. Set the minifyEnabled property to true to enable + ProGuard, as shown in this example.

    + + 
    +  android {
+   ...
+ 
+    buildTypes {
+        release {
+            minifyEnabled true
+            proguardFiles getDefaultProguardFile('proguard-android.txt'),
+            'proguard-rules.pro'
+        }
+    }
+  }
+
    + +

    The getDefaultProguardFile('proguard-android.txt') method obtains the default + ProGuard settings from the Android SDK tools/proguard/ folder. The + proguard-android-optimize.txt file is also available in this Android SDK + folder with the same rules but with optimizations enabled. ProGuard optimizations perform + analysis at the bytecode level, inside and across methods to help make your app smaller and run + faster. Android Studio adds the proguard-rules.pro file at the root of the module, + so you can also easily add custom ProGuard rules specific to the current module.

    + +

    You can also add ProGuard files to the getDefaultProguardFile + directive for all release builds or as part of the productFlavor settings in the + build.gradle file to customize the settings applied to build variants. This example + adds the proguard-rules-new.pro to the proguardFiles + directive and the other-rules.pro file to the flavor2 product flavor.

    + +
    +    android {
+   ...
+ 
+    buildTypes {
+        release {
+            minifyEnabled true
+            proguardFiles getDefaultProguardFile('proguard-android.txt'),
+            'proguard-rules.pro', 'proguard-rules-new.pro'
+        }
+    }
+ 
+   productFlavors {
+        flavor1 {
+        }
+        flavor2 {
+            proguardFile 'other-rules.pro'
+        }
+    }
+ }
+
    + + + +

    Enabling ProGuard (Ant Builds)

    When you create an Android project, a proguard.cfg file is automatically generated in the root directory of the project. This file defines how ProGuard optimizes and obfuscates your code, so it is very important that you understand how to customize it for your needs. The default configuration file only covers general cases, so you most likely have to edit - it for your own needs. See the following section about Configuring ProGuard for information on - customizing the ProGuard configuration file.

    + it for your own needs. See the following section about Configuring + ProGuard for information on customizing the ProGuard configuration file.

    To enable ProGuard so that it runs as part of an Ant or Eclipse build, set the proguard.config property in the <project_root>/project.properties file. The path can be an absolute path or a path relative to the project's root.

    -

    Note: When using Android Studio, you must add Proguard -to your gradle.build file's build types. For more information, see the -Gradle Plugin User Guide. +

    If you left the proguard.cfg file in its default location (the project's root + directory), you can specify its location like this:

    -

    If you left the proguard.cfg file in its default location (the project's root directory), -you can specify its location like this:

     proguard.config=proguard.cfg
    +

    You can also move the the file to anywhere you want, and specify the absolute path to it:

    + 
     proguard.config=/path/to/proguard.cfg
    -

    When you build your application in release mode, either by running ant release or by using the Export Wizard in Eclipse, the build system automatically checks to see if the proguard.config property is set. If it is, ProGuard automatically processes @@ -116,19 +179,19 @@ proguard.config=/path/to/proguard.cfg

  5. <project_root>/proguard if you are using Eclipse.
    6. - +

    Caution: Every time you run a build in release mode, these files are overwritten with the latest files generated by ProGuard. Save a copy of them each time you release your - application in order to de-obfuscate bug reports from your release builds. - For more information on why saving these files is important, see + application in order to de-obfuscate bug reports from your release builds. + For more information on why saving these files is important, see Debugging considerations for published applications.

    Configuring ProGuard

    -

    For some situations, the default configurations in the proguard.cfg file will - suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove code - that it thinks is not used, but your application actually needs. Some examples include:

    +

    For some situations, the default configurations in the ProGuard configuration file will + suffice. However, many situations are hard for ProGuard to analyze correctly and it might remove + code that it thinks is not used, but your application actually needs. Some examples include:

    -

    The default proguard.cfg file tries to cover general cases, but you might +

    The default ProGuard configuration file tries to cover general cases, but you might encounter exceptions such as ClassNotFoundException, which happens when ProGuard strips away an entire class that your application calls.

    You can fix errors when ProGuard strips away your code by adding a -keep line in - the proguard.cfg file. For example:

    + the ProGuard configuration file. For example:

     -keep public class <MyClass>

    There are many options and considerations when using the -keep option, so it is - highly recommended that you read the + highly recommended that you read the ProGuard - Manual for more information about customizing your configuration file. The - Overview of Keep options and Examples sections are particularly helpful. + Manual for more information about customizing your configuration file. The + Overview of Keep options and Examples sections are particularly helpful. The Troubleshooting - section of the ProGuard Manual outlines other common problems you might encounter + section of the ProGuard Manual outlines other common problems you might encounter when your code gets stripped away.

    Decoding Obfuscated Stack Traces

    When your obfuscated code outputs a stack trace, the method names are obfuscated, which makes debugging hard, if not impossible. Fortunately, whenever ProGuard runs, it outputs a - <project_root>/bin/proguard/mapping.txt file, which shows you the original - class, method, and field names mapped to their obfuscated names.

    + mapping.txt file, which shows you the original class, method, and field names + mapped to their obfuscated names.

    The retrace.bat script on Windows or the retrace.sh script on Linux - or Mac OS X can convert an obfuscated stack trace to a readable one. It is located in the - <sdk_root>/tools/proguard/ directory. The syntax for executing the + or Mac OS X can convert an obfuscated stack trace to a readable one. It is located + in the <sdk_root>/tools/proguard/ directory. The syntax for executing the retrace tool is:

    retrace.bat|retrace.sh [-verbose] mapping.txt [<stacktrace_file>]

    For example:

    - + 
    retrace.bat -verbose mapping.txt obfuscated_trace.txt
    - +

    If you do not specify a value for <stacktrace_file>, the retrace tool reads from standard input.

    Debugging considerations for published applications

    -

    Save the mapping.txt file for every release that you publish to your users. - By retaining a copy of the mapping.txt file for each release build, +

    Save the mapping.txt file for every release that you publish to your users. + By retaining a copy of the mapping.txt file for each release build, you ensure that you can debug a problem if a user encounters a bug and submits an obfuscated stack trace. A project's mapping.txt file is overwritten every time you do a release build, so you must be - careful about saving the versions that you need.

    + careful about saving the versions that you need. For Eclipse, this file is stored in + <project_root>/bin/proguard/. For Android Studio, this file is stored in + the app build/outs/ folder.

    For example, say you publish an application and continue developing new features of the application for a new version. You then do a release build using ProGuard soon after. The build overwrites the previous mapping.txt file. A user submits a bug report - containing a stack trace from the application that is currently published. You no longer have a way + containing a stack trace from the application that is currently published. You no longer have a way of debugging the user's stack trace, because the mapping.txt file associated with the version on the user's device is gone. There are other situations where your mapping.txt file can be overwritten, so ensure that you save a copy for every release that you anticipate you have to debug.

    -

    How you save the mapping.txt file is your decision. For example, you can rename them to - include a version or build number, or you can version control them along with your source - code.

    +

    How you save the mapping.txt files is your decision. For example, you can rename + the files to include a version or build number, or you can version control them along with your + source code.

    -- cgit v1.2.3-59-g8ed1b