Zelix KlassMaster - Documentation

Getting Started

Overview.

This document consists of the following sections.
  1. Introduction,
  2. The Processing Sequence,
  3. Using the GUI,
  4. Creating your first ZKM Script,
  5. Executing your first ZKM Script and
  6. Which obfuscation options to use.

Introduction.

This document assumes that you have Zelix KlassMaster™ installed successfully. If you do not yet have Zelix KlassMaster™ running then see the Installation document.

Zelix KlassMaster™ has two interfaces - the GUI interface and the command line ZKM Script interface. The GUI interface is provided as a way of quickly becoming familiar with the basic concepts of obfuscation and as a way of creating a simple ZKM Script. The ZKM Script interface is ultimately the preferred interface because it
  1. is more suited to the task of repeated obfuscation than is the GUI interface,
  2. is less prone to human error,
  3. provides extra functionality that is not available through the GUI interface,
  4. allows you to integrate the obfuscation step into an automated build process and
  5. allows us to exchange ZKM Scripts with you which makes the support process much, much easier.

The Processing Sequence.

The basic Zelix KlassMaster™ processing sequence is as follows.
  1. Set the classpath that Zelix KlassMaster™ should use, (GUI | ZKM Script)
  2. Open the classes that you wish to obfuscate, (GUI | ZKM Script)
  3. Set your Trim exclusions, (GUI | ZKM Script)
  4. Set your Trim options and perform the trimming, (GUI | ZKM Script)
  5. Set your name obfuscation exclusions, (GUI | ZKM Script)
  6. Set your obfuscation options and obfuscate, (GUI | ZKM Script)
  7. Save your obfuscated classes. (GUI | ZKM Script)

Using the GUI.

You start the Zelix KlassMaster™ GUI by executing the Zelix KlassMaster™ JAR file without specifying a ZKM Script as the final command line option. As mentioned above, the GUI interface is provided as a way of quickly becoming familiar with the basic concepts of obfuscation and as a way of creating a simple ZKM Script.

When you are getting started, it is recommended that you use the Build Helper tool which is in the "Tools" menu. The Build Helper will guide you through the basic steps of trimming and/or obfuscating your classes.

It is highly recommended that you do not use the Trim function until you have your obfuscated application working. The Trim function can be more difficult to understand than obfuscation so it can help if you use it only when everything else is working. In the Build Helper, you can postpone the use of the Trim function by clicking on the "Skip" button on the Trim Exclusions and Trim Options windows.

Creating your first ZKM Script.

You can create a basic ZKM Script by using the GUI Build Helper or the ZKM Script Helper tools. (The difference between the two is that the Build Helper actually performs the class processing in the background before giving you the opportunity to save the corresponding ZKM Script.) At the end of the Build Helper process you will see the "ZKM Script" button which will allow you to view and then save the equivalent ZKM Script.

Once your ZKM Script is saved as a text file, you are free to then edit it using any simple text editor. Note that you cannot open a saved ZKM Script within the GUI Build Helper or the ZKM Script Helper tools. This is because ZKM Scripts can become arbitrarily complex and because they can contain functionality which is not supported by the GUI.

First time users are sometimes initially puzzled by the ZKM Script exclusion syntax. This is because ZKM Script gives you very fine control over what is or isn't excluded. Therefore, it is highly recommended that you at least read the basic exclusions part of the ZKM Script Exclusions Tutorial before modifying your first ZKM Scripts. It actually isn't that complicated so it could save you a lot of trial and error.

Executing your first ZKM Script.

You can execute your saved ZKM Script from the command line or from within a build tool.

If you find yourself needing to debug your ZKM Script then you may find it helpful to run Zelix KlassMaster™ using the "-v" (ie. verbose) command line option. This will result in a great deal of extra information being written to the Zelix KlassMaster™ log file which is named ZKM_log.txt by default. This extra information will include
  • the effective exclude parameters (including the default exclusions) and
  • which classes, fields or methods were directly matched by a particular exclusion parameter.

Which obfuscation options to use.

See the answer to FAQ question 14.