There will be some examples given, that represent common use cases.
Example 1: Getting started with Ant and yGuard (for Ant newbies)
Following are the contents of a complete build.xml file. Just copy the following lines to a new document named build.xml, put the file into your project's root directory and edit the file to suit your needs.
classpath="yguard.jar"/>
methods="protected" fields="protected">
methods="protected" fields="protected">
destdir="${classDir}">
basedir="${classDir}"
includes="com/mycompany/**">
Example 2: A Public API
An alternative yguard section could look like this:
logfile="shrinklog.xml">
methods="protected"
fields="protected"/>
logfile="obflog.xml">
methods="protected"
fields="protected"/>
This case is especially useful when you want to provide and expose a public API. All the classes, methods and fields, that can be seen in a javadoc generated API will be excluded from the shrinking and renaming tasks. Package friendly and private classes, methods and fields will be shrinked or obfuscated whenever possible.
This example also displays the use of the "attribute" element. In this case it prevents the yguard task from removing the "Deprecated" flag from the entities in the .class files.
Example 3: A Demo Program
methods="public" fields="none"/>
methods="public" fields="none"/>
This example demonstrates the common use case of a demo program. The keep sections of both the shrink and rename elements contain code entities that will often have to be excluded from the shrinking and renaming process. These are the main code entrypoints (the main method), classes that are loaded per reflection and fields and methods needed for serialization. Note how the same patternsets can be reused using the id and refid attributes.
Example 4: A Program Using an External Library
This example demonstrates full method and field obfuscation for a program, that has external dependencies. The dependencies are specified in the externalclasses element using standard Ant path specification mechanisms. Classes residing in lib/external.jar and underneath the lib/additional/classes/ directory (note the trailing slash), will be used to resolve external dependencies during the obfuscation run. This is necessary if external classes want to access obfuscated classes directly using an externally defined interface or superclass. yGuard automatically detects externally declared methods and prevents renaming and shrinking of these items. As a result, the shrinked and obfuscated jar file can be used together with unmodified versions of external libraries without causing any problems.
This example also demonstrates the use of the error-checking property. In this case the Ant target fails if any problem is detected during the obfuscation run.
Example 5: A Program with .properties Files and Other Resource Files
This example, too, demonstrates full method and field obfuscation for a program, that uses .properties files and other resources files. Some configuration files are used that contain fully qualified classnames for plugins that are going to be obfuscated. Therefore yGuard is instructed to automatically replace the plain-text entries in those files with the obfuscated name versions.
Additionally some resources are hardcoded into the classes (image locations and html files, e.g.). yGuard gets instructed not to move these resource files even if they reside in a package structure that is obfuscated.
Since the property files have been created with the same name as the classes that make use of them and they are being loaded using this.getClass().getName(), yGuard is configured to rename the .properties files according to the obfuscated names of the corresponding .class files.
Example 6: A Program Linked Against a Library That Needs to be Obfuscated
This example demonstrates almost no method, class, and field obfuscation for a program, that has external dependencies and additionally depends on a third party library jar which has to be obfuscated before deployment. Only those parts that actually interface with the third party jar in the mylibconnector package are being obfuscated. Nothing in the third party library jar will be exposed in the final application, everything will be obfuscated and the code in the open application that makes use of the third party jar will be adjusted. Note that the public part of the application will still be debuggable since all of the crucial attributes will be exposed for the open application part.
The dependencies are specified in the externalclasses element using standard Ant path specification mechanisms. Classes residing in lib/external.jar will be used to resolve external dependencies during the obfuscation run. This is not strictly necessary in this case since the public API will be fully exposed, i.e. no methods which have been declared by interfaces or super class in external classes will be renamed.
Example 7: Using the extends and implements attributes (Serializable exclusion)
This example demonstrates the usage of the new implements and extends attributes of the class element. All Serializable classes are excluded from shrinking by using the implements attribute of the class element. Additionally, all classes that extend the base class for menu items, org.myorg.myapp.MyMenuItem, are defined as entrypoints for the shrinking engine using the extends attribute of the class element. The readObject and writeObject methods and the field serialVersionUID needed for serialization are excluded from name obfuscation as well.