Zelix KlassMaster - Documentation
 

Executing a ZKM Script File

ZKM Scripts are scripts that have been written in the ZKM Script language that automate the process of using Zelix KlassMaster. They allow you to integrate the use of Zelix KlassMaster into your development procedures. Basic ZKM Scripts can be created interactively using the ZKM Script Helper tool. More advanced scripts can be produced by using a basic text editor to modify basic ZKM Scripts.

The remainder of this page is organized into the following sections.

Basic Usage

The basic usage is: java -jar ZKM.jar [[-options] <scriptFileName>]

If no options or script file name are present then the GUI interface will be started. To execute a ZKM Script you simply pass the name of the ZKM Script file to Zelix KlassMaster.

For example java ZKM MyScript.txt will execute the MyScript.txt ZKM Script file. Informative messages are written to standard out and the log file. Error messages are written to the standard error stream and the log file.

The options

-? Show the usage
-p Parse the ZKM Script file and display any errors but don't execute the script. This option is handy for syntax checking a long and complicated script.
-v Verbose. Display extra information in the log file.
-l <logFileName> Use the specified file as the log file to which messages should be written. May be relative or absolute. If the path is relative, then the file will be written to the default directory. By default the file "ZKM_log.txt" in the default directory will be used.
-tl <trimLogFileName> Use the specified file as the trim log file. May be relative or absolute. If the path is relative, then the file will be written to the default directory. By default the file "ZKM_TrimLog.txt" in the default directory will be used.
-de <defaultExcludeFileName> Specifies the path name of the file containing the default name exclusions. May be relative or absolute. If the path is relative, Zelix KlassMaster™ will look in the default directory. By default Zelix KlassMaster™ will look in the default directory for the file "defaultExclude.txt".
-dte <defaultTrimExcludeFileName> Specifies the path name of the file containing the default trim exclusions. May be relative or absolute. If the path is relative, Zelix KlassMaster™ will look in the default directory. By default Zelix KlassMaster™ will look in the default directory for the file "defaultTrimExclude.txt".
-dd <defaultDirectoryName> Specifies the path name of the directory which will be used as the default directory. May be relative or absolute. If the path is relative, then it will be relative to the current working directory. By default, the default directory will be the current working directory.
-ro <fileName> Redirect stdout to the specified file. Redirects messages and warnings. Errors will still be written to stderr.
<ZKMScriptFileName> The name of the ZKM Script file to execute. May be relative or absolute. If the path is relative, then it will be relative to the current working directory.

Special Configuration Options

There are a number of special configuration options which can be either
  • passed to Zelix KlassMaster™ using the JVM's -D<key>=<value> syntax. (-D"<key>=<value>" in Windows)
  • set as environmental variables provided the special ZKM_LOAD_ENV_VARIABLES=true environmental variable has also been set so that Zelix KlassMaster™ will load ALL environmental variables into System properties,
  • placed as properties in a file named "ZKM_System.properties" in the working directory (i.e. "user.dir").
The special configuration options are as follows.

Option Description
ZKM_SCRIPT_ENCODING Can be set to indicate the character encoding of any ZKM Scripts. (e.g. ISO-8859-1)
ZKM_NEW_CHANGE_LOG_ENCODING Can be set to indicate the character encoding to be used when writing change logs. (e.g. ISO-8859-1)
ZKM_JAD_ENCODING Can be set to indicate the character encoding to be used when reading or writing a MIDP JAD file. (UTF-8 by default)
ZKM_FIXED_TOTALLY_UNCHANGED Set to true to copy across any classes that you have specified as "fixed" completely unchanged.
ZKM_REFLECTION_WARNINGS Set to false to supress Java Reflection API warnings in the Zelix KlassMaster™ log.
ZKM_TEST_HIERARCHY Set to false to stop Zelix KlassMaster™ from testing for gaps in the inheritance hierarchy. Gaps in the inheritance hierarchy are likely to cause problems in the Trim function so you should not use this option if you are using that function. Gaps in the inheritance hierarchy can also cause problems when name obfuscating if package, class or non-private field and method names are changed.
ZKM_CREATE_BACKUP Set to false to prevent overwritten JAR files being backed up with the .BACKUP extension.
ZKM_DELETE_EMPTY_DIRECTORIES Set to true to prevent empty directories from being written to the obfuscated archive file.
ZKM_RANDOMIZE_OBFUSCATION Set to true to increase the randomness of Zelix KlassMaster's obfuscation across builds. By default, Zelix KlassMaster™ will obfuscate an unchanged set of classes in largely the same way across builds.
ZKM_TREAT_EXCEPTION_OBFUSCATION_AS_FLOW_OBFUSCATION Set to true to tell Zelix KlassMaster™ to treat Exception Obfuscation as if it were Flow Obfuscation for the purposes of the ZKM Script obfuscateFlowExclude statement.
ZKM_IGNORE_MISSING_MEMBERS Set to true to tell Zelix KlassMaster™ to ignore missing fields and methods in classes in the classpath. This option should only be used if it is necessary because it bypasses useful validation. However, it is sometimes necessary if there are clashing versions of 3rd party classes in the classpath. Generally this option is superceded by the ZKM Script ignoreMissingReferences statement.
ZKM_OBFUSCATE_REFERENCES_INDY Set to false to tell Zelix KlassMaster™ to not use the invokedynamic instruction when obfuscating field or method references.
ZKM_STRING_ENCRYPT_INDY Set to false to tell Zelix KlassMaster™ to not use the invokedynamic instruction or DES encryption when when encrypting Strings. Currently only relevant if you have specified "enhanced" String Encryption and you are allowing method parameter changing.
ZKM_STRING_ENCRYPT_DES Set to false to tell Zelix KlassMaster™ to not use DES encryption when when encrypting Strings. Currently only relevant if you have specified "enhanced" String Encryption and you are allowing method parameter changing.
ZKM_DEFAULT_DIR Can be set to specify the path name of the directory which will be used as the default directory. Exactly the same as the -dd command line option described above which takes precedence if it is present.
ZKM_METHOD_PARAM_CHANGING_LOOKUP Can be set to false to switch off a part of the Method Parameter Change functionality which could cause an unreasonable delay in the obfuscated application's start up time in the case of very large applications. This would be at the cost of reduced protection.
ZKM_MATCH_ON_ORIGINAL Can be set to true to tell Zelix KlassMaster™'s ZKM Script exclusion statements to match on original package, class, field and method names rather than their possibly obfuscated names. This option is only relevant if ZKM Script exclusion statements follow an obfuscate statement in the one ZKM Script.
ZKM_METHOD_PARAM_SYNCH Can be set to false to tell Zelix KlassMaster™ to not use extra synchronization in the Method Parameter Changing functionality.
ZKM_EXTRA_XML_FILE_TYPES Can be used to specify additional file types in a semicolon delimited list that Zelix KlassMaster should treat as generic XML files.
(E.g. *.foo;*.bar)
ZKM_USE_PARALLEL Can be set to false to tell Zelix KlassMaster™ to never use parallel processing. Defaults to true.
ZKM_RANDOM_SEED Can be set to true to set the seed for the random number generators Zelix KlassMaster™ uses.
ZKM_REPRODUCIBLE_RANDOM Can be set to true to tell Zelix KlassMaster™ to use random number generators that produce reproducible values for a given ZKM_RANDOM_SEED value.
ZKM_INTEGER_ENCRYPT_INDY Set to false to tell Zelix KlassMaster™ to not use the invokedynamic instruction or DES encryption when when encrypting integer constants. Currently only relevant if you are allowing method parameter changing.
ZKM_INTEGER_ENCRYPT_DES Set to false to tell Zelix KlassMaster™ to not use DES encryption when when encrypting integer constants. Currently only relevant if you are allowing method parameter changing.
ZKM_INTEGER_ENCRYPT_LOW_VALUE_FIELDS Set to true to tell Zelix KlassMaster™ to include fields with the values -1, 0 and 1 when integer constant encrypting.
ZKM_LONG_ENCRYPT_INDY Set to false to tell Zelix KlassMaster™ to not use the invokedynamic instruction or DES encryption when when encrypting long constants. Currently only relevant if you are allowing method parameter changing.
ZKM_LONG_ENCRYPT_DES Set to false to tell Zelix KlassMaster™ to not use DES encryption when when encrypting long constants. Currently only relevant if you are allowing method parameter changing.
ZKM_LONG_ENCRYPT_LOW_VALUE_FIELDS Set to true to tell Zelix KlassMaster™ to include long fields with the values 0L and 1L when long constant encrypting.

Examples

java -DZKM_SCRIPT_ENCODING=ISO-8859-1 -jar ZKM.jar myScript.txt

In the Windows environment you use quotes as follows.
java -D"ZKM_SCRIPT_ENCODING=ISO-8859-1" -jar ZKM.jar myScript.txt

 
Documentation Table of Contents
Zelix KlassMaster - Java Obfuscator