Ant Task

Description

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.

1. An external ProGuard configuration file

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.

2. Embedded ProGuard configuration options

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.

3. XML configuration tags

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.

Parameters

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

Parameters specified as nested elements

libraryjar

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.

Parameters

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

Parameters specified as nested elements

exclude

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.

Parameters

Attribute Description Required
name Name or Pattern for the files to be excluded. Yes

include

Include files of a jar (or directory). This nested subtask is unsupported for fileset or path like structures. Use Ant's filtering methods instead.

Parameters

Attribute Description Required
name Name or Pattern for the files to be included. Yes

resourcejar

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.

Parameters

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

Parameters specified as nested elements

Parameters are the same as the parameters of the libraryjars nested tag.

injar

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.

Parameters

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

Parameters specified as nested elements

Parameters are the same as the parameters of the libraryjars nested tag.

keep

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.

Parameters

Attribute Description Required
access List of access flags to the class separated by a space. Must be one of
  • public
  • final
  • abstract
All access attributes may have a leading ! to specify the attributes that are not set.
No
type Type of the class. Must be one of
  • class
  • interface
  • !interface
Defaults to 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

Parameters specified as nested elements

access

As an alternative to the access attribute it is possible to use the nested access tag.

Parameters

Attribute Description Required
name Name of the access attribute. Yes

field

With the fields tag you can specify the fields to be kept.

Parameters

Attribute Description Required
access List of access flags to the field, separated by spaces. Must be one of
  • public
  • protected
  • private
  • static
  • volatile
  • transient
All access attributes may have a leading ! 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

method

With the method tag you can specify the methods to be kept.

Parameters

Attribute Description Required
access List of access flags to the method separated by spaces. Must be one of
  • public
  • protected
  • private
  • static
  • synchronized
  • native
  • abstract
  • strictfp
All access attributes may have a leading ! 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

constructor

With the constructor tag you can specify the constructors to be kept.

Parameters

Attribute Description Required
access List of access flags to the constructor separated by spaces. Must be one of
  • public
  • protected
  • private
  • static
  • synchronized
  • native
  • abstract
  • strictfp
All access attributes may have a leading ! 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

keepclasssmembers

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

Parameters are the same as the parameters of the keep nested tag.

keepclasseswithmembers

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

Parameters are the same as the parameters of the keep nested tag.

keepnames

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

Parameters are the same as the parameters of the keep nested tag.

keepclassmembernames

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

Parameters are the same as the parameters of the keep nested tag.

keepclasseswithmembernames

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

Parameters are the same as the parameters of the keep nested tag.

keepattribute

Specifies any optional attributes to be preserved. Only applicable when obfuscating.

configuration

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.

Parameters

Attribute Description Required
name Name of the attribute to keep. * preserves all attributes. Typical optional attributes are
  • LineNumberTable
  • LocalVariableTable
  • SourceFile
  • Deprecated
  • Synthetic
The InnerClasses attribute name can be specified as well, referring to the source name part of this attribute. For example, you could keep the Deprecated attribute when processing a library.
No

Copyright © 2003 Dirk Schnelle.