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 properties 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 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.
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.

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