Run ProGuard as an Ant task. ProGuard is a free Java class file shrinker and obfuscator.
Before you are able to use the proguard
task, you have to tell
Ant about this new task. This is done through:
<taskdef name="proguard" classname="proguard.ant.ProGuardTask" classpath="/usr/local/java/proguard/lib/proguard.jar" />
where you obviously have to replace the latter path by the path where you've installed ProGuard.
There are three ways to configure the ProGuard task: using an external configuration file, using embedded ProGuard configuration options, and using the equivalent XML configuration tags. These three ways can be combined, depending on practical circumstances and personal preference.
The simplest way to use the ProGuard task in an Ant build file is to keep
your ProGuard configuration file, and include it from Ant. You can include
your ProGuard configuration file by setting the configuration attribute of your
proguard
task. Your ant build file will then look like this:
<taskdef name="proguard" classname="proguard.ant.ProGuardTask" /> <proguard configuration="myconfigfile.pro"/>
This is a convenient option if you prefer ProGuard's configuration style over XML, if you want to keep your build file small, or if you have to share your configuration with developers who don't use Ant.
Instead of keeping an external ProGuard configuration file, you can also copy
the contents of the file into the nested text of the proguard
task
(the PCDATA area). Your Ant build file will then look like this:
<taskdef name="proguard" classname="proguard.ant.ProGuardTask" /> <proguard> -libraryjars ${java.home}/lib/rt.jar -injars in.jar -outjar out.jar -keepclasseswithmembers public class * { public static void main(java.lang.String[]); } </proguard>
Some minor syntactical changes are required in order to conform with the XML standard.
Firstly, the #
chararacter cannot be used for comments in an XML
file. Comments must be enclosed by an opening <!--
and a
closing -->
. All occurrences of the #
chararacter
can be removed.
Secondly, the use of <
and >
characters to
mark environment variables would upset the structure of the XML build file.
Environment variables are now enclosed by an opening ${
and a
closing }
. This syntax is in line with Ant traditions. It also
allows you to use Ant properties within the ProGuard configuration.
Then there are some other keywords, <init>
,
<methods>
and <fields>
. All occurrences
of the these keywords have to be replaced with ${proguard.init}
,
${proguard.methods}
, and ${proguard.fields}
,
respectively.
If you prefer a full-blown XML configuration, you can replace the ProGuard configuration options by the equivalent XML configuration tags. The remainder of this page presents the supported tags.
Attribute | Description | Required |
configuration |
Name of a proguard configuration file. The settings of the configuration file are merged with the ant settings. For single value attributes the ant settings override the settings of the config file. All values can also be set through the configuration file or a nested configuration task. |
No |
outjar | Specifies the name of the output jar (or directory). It must be different from the input jars (and directories). | No |
renamesourcefileattribute |
Specifies a constant string to be put in the SourceFile attributes of the
class files. Note that the attribute also has to be preserved explicitly
using the keepattributes directive, or it
will be removed anyway. For example, you may want to have your processed libraries and applications produce useful obfuscated stack traces. Only applicable when obfuscating. |
No |
printseeds | Specifies to exhaustively list classes and class members matched by the various -keep commands. The list is printed to the standard output or to the given file. The list can be useful to verify if the intended class members are really found, especially if you're using wildcards. For example, you may want to list all the applications or all the applets that you are keeping. | No |
printusage |
Specifies to list dead code of the input class files. The list is printed
to the standard output or to the given file. For example, you can list
the unused code of an application. Specify the name of the file or yes , on or
true to print to the standard output.Defaults to off . Only applicable when shrinking.
|
No |
printmapping | Specifies to print the mapping from old names to new names for classes and class members that have been renamed. The mapping is printed to the standard output or to the given file. It is required if you ever want to make sense again of obfuscated stack traces. Only applicable when obfuscating. | No |
applymapping | Specifies to reuse the given name mapping that was printed out in a previous obfuscation run of ProGuard. Classes and class members that are listed in the mapping file receive the names specified along with them. Classes and class members that are not mentioned receive new names. This option can be useful for incremental obfuscation, i.e. processing add-ons or small patches to an existing piece of code. Only applicable when obfuscating. | No |
verbose |
Specifies to write out some more information during processing. If the
program terminates with an exception, this option will print out the
entire stack trace, instead of just the exception message. Defaults to off .
|
No |
dump | Specifies to write out the internal structure of the class files, after any processing. The structure is printed to the standard output or to the given file. For example, you may want to write out the contents of a given jar file, without shrinking or obfuscating it first. | No |
ignorewarnings |
Specifies to print any warnings about unresolved references to
superclasses, interfaces, or class members, but to continue processing in
any case. If the classes or class members are indeed required for
processing, the output jar will not function properly. Only use this
option if you know what you're doing! Defaults to off .
|
No |
warn |
Specifies to warn about unresolved references at all. Again, if the
unresolved classes or class members are indeed required for processing,
the output jar will not function properly. Only use this option if you
know what you're doing! Defaults to on .
|
No |
note |
Specifies to print notes about class casts of variable dynamically
created objects. These notes provide hints about classes that may have to
be kept. Defaults to on .
|
No |
shrink |
Specifies to shrink the input class files. By default, shrinking is
applied: all classes and class members are removed, except for the ones
listed by the various -keep commands, and the ones they depend on,
recursively. Defaults to on .
|
No |
obfuscate |
Specifies to obfuscate the input class files. By default, obfuscation is
applied: classes and class members receive new short random names, except
for the ones listed by the various -keep commands. Internal attributes
that are useful for debugging, such as source files names, variable
names, and line numbers are removed. Defaults to on .
|
No |
usemixedclassnames |
Specifies to generate mixed-case class names while obfuscating. By default,
obfuscated class names can contain a mix of upper-case characters and
lower-case characters. This creates perfectly acceptable and usable jars.
Only if a jar is unpacked on a platform with a case-insensitive filing
system (say, Windows), the unpacking tool may let similarly named class
files overwrite each other. Code that self-destructs when it's unpacked!
Developers who really want to unpack their jars on Windows and who are
unable to switch to another development platform can use this option to
switch off this behavior. Note that the obfuscated jars will become larger
as a result. Only applicable when obfuscating. Defaults to on .
|
No |
overloadaggressively |
Specifies to apply aggressive overloading while obfuscating. Multiple
fields and methods can then get the same names, as long as their arguments
and return types are different (not just their arguments, in the case of
methods). This option can make the output jar even smaller (and less
comprehensible). Only applicable when obfuscating. Defaults to off .
|
No |
defaultpackage | Specifies to repackage all class files that are renamed into the single given package. Without argument or with an empty string (''), the package is removed completely. This option can make the output jar even smaller (and less comprehensible). Only applicable when obfuscating. | No |
skipnonpubliclibraryclasses |
Specifies to ignore non-public library classes. By default, non-public
library classes are skipped while parsing library jars. The classes are
typically not relevant during processing, since they don't affect the
actual program code in the input jars. Ignoring them reduces memory usage
and processing time. Occasionally, a badly designed library may contain a
non-public library class that is extended/implemented by a public library
class. If the latter library class in turn is extended/implemented by a
program class, ProGuard will complain that it can't find the non-public
library class, which it had ignored during parsing. This option will
overcome that problem, at the cost of greater memory usage and longer
processing time. Defaults to on .
|
No |
Specifies the library jars (or directories) of the application to be processed. The class files in these jars will not be included in the output jar. The specified library jars should at least contain the class files that are extended by application class files. Library class files that are only called needn't be present.
Attribute | Description | Required |
name |
Name of the library jar or name of a directory. Jar files can be specified via a nested fileset, too. Note that this does not work for files in a directory. |
Yes |
refid | Reference to a path like structure or a fileset. Using a refid excludes specifying a name. | No |
Exclude files from a jar (or directory). The exclude parameter affects subsequent include parameters; it has no effect without the latter. File filters are discussed in some more detail in ProGuard Usage.
This nested subtask is unsupported for fileset or path like structures. Use Ant's filtering methods instead.
Attribute | Description | Required |
name | Name or Pattern for the files to be excluded. | Yes |
Include files of a jar (or directory). This nested subtask is unsupported for fileset or path like structures. Use Ant's filtering methods instead.
Attribute | Description | Required |
name | Name or Pattern for the files to be included. | Yes |
Specifies any resource jars (or directories) to be copied into the output jar. Only non-class files in these jars will be copied. If this option isn't specified, the resource files from the injar (or directories) will be copied.
Attribute | Description | Required |
name |
Name of the jar or name of a directory. Jar files can be specified via a nested fileset, too. Note that this does not work for files in a directory. |
Yes |
refid | Reference to a path like structure or a fileset. Using a refid excludes specifying a name. | No |
Specifies the program jars (or directories) of the application to be processed. The class files in these jars will be processed and merged in the output jar.
Attribute | Description | Required |
name |
Name of the jar or directory. Jar files can be specified via a nested fileset, too. Note that this does not work for files in a directory. |
Yes |
refid | Reference to a path like structure or a fileset. Using a refid excludes specifying a name. | No |
Specifies classes and class members (fields and methods) to be preserved. They will be preserved with their original names. This is typically the required seed for recursively determining which other classes and class members need to be preserved. For example, in order to keep an application, you can specify the main class along with its main method. In order to process a library, you should specify all publicly accessible items.
Attribute | Description | Required |
access |
List of access flags to the class separated by a space. Must be one of
! to specify the
attributes that are not set.
|
No |
type |
Type of the class. Must be one of
class .
|
No |
name |
Full name of the class. Wildcards are allowed. A description of the usage
and limitations of wildcards can be found in
ProGuard Usage. Defaults to *
|
No |
extends | Full name of the class this class extends. | No |
implements | Full name of the interface this class implements. | No |
As an alternative to the access attribute it is possible to use the nested access tag.
Attribute | Description | Required |
name | Name of the access attribute. | Yes |
With the fields tag you can specify the fields to be kept.
Attribute | Description | Required |
access |
List of access flags to the field, separated by spaces. Must be one of
! to specify the
attributes that are not set.The access attributes may be set using the nested access tag. |
No |
type | Full name of the type of the field. | No |
name |
Name of the field. Wildcards are allowed. A description of the usage
and limitations of wildcards can be found in
ProGuard usage. The <fields> keyword must not be used. Use
* or ${proguard.fields} instead.Defaults to *
|
No |
With the method tag you can specify the methods to be kept.
Attribute | Description | Required |
access |
List of access flags to the method separated by spaces. Must be one of
! to specify the
attributes that are not set.The access attributes may be set using the nested access tag. |
No |
type |
Full name of the return type of the method. Defaults to void
|
No |
name |
Name of the method. Wildcards are allowed. A description of the usage
and limitations of wildcards can be found in
ProGuard usage. The <methods> keyword must not be used. Use
* or ${proguard.fields} instead.Defaults to *
|
No |
param | Parameters of the method without brackets, separated by commas. Parameters can also be specified in the name attribute enclosed in brackets. | No |
With the constructor tag you can specify the constructors to be kept.
Attribute | Description | Required |
access |
List of access flags to the constructor separated by spaces. Must be one of
! to specify the
attributes that are not set.The access attributes may be set using the nested access tag. |
No |
param | Parameters of the constructor, separated by commas. | No |
Specifies class members to be preserved, if their classes are preserved as well. For example, you may want to keep all serialization fields and methods of classes that implement the Serializable interface.
Parameters are the same as the parameters of the keep nested tag.
Specifies classes and class members to be preserved, on the condition that all of the specified class members are present. For example, you may want to keep all applications that have a main method, without having to list them explicitly.
Parameters are the same as the parameters of the keep nested tag.
Specifies classes and class members whose names are to be preserved, if they aren't removed in the shrinking phase. For example, you may want to keep all class names of classes that implement the Serializable interface, so that the processed code remains compatible with any originally serialized classes. Classes that aren't used at all can still be removed.
Parameters are the same as the parameters of the keep nested tag.
Specifies class members whose names are to be preserved, if they aren't removed in the shrinking phase. For example, you may want to preserve the name of the synthetic class$ methods when processing a library, so ProGuard can detect it again when processing an application that uses the processed library.
Parameters are the same as the parameters of the keep nested tag.
Specifies classes and class members whose names are to be preserved, on the condition that all of the specified class members are present after the shrinking phase. For example, you may want to keep all native method names and the names of their classes, so that the processed code can still link with the native library code. Native methods that aren't used at all can still be removed. If a class file is used, but none of its native methods are, its name will still be obfuscated.
Parameters are the same as the parameters of the keep nested tag.
Specifies any optional attributes to be preserved. Only applicable when obfuscating.
With the nested configuration task it is possible to include configuration settings from a file or a configuration defined somewhere else in this build script. The configuration task is described in the document Ant Configuration Task. Nested configuration tasks are evaluated in the order they appear.
Attribute | Description | Required |
name |
Name of the attribute to keep. * preserves all attributes.
Typical optional attributes are
|
No |