Application Development Kit (ADK)

Macro expressions of the form $(VAR) are replaced by the value of the variable VAR during the preprocessing step. Preprocessor variables are defined by a preprocessor statement or passed as commandline arguments to the installer script interpreter. To define a preprocessor variable in an installer script, use the statement

$VAR value

Undefined variables are not replaced and generate a warning. Environment variables can be read by adding an ENV_ prefix to the variable name.

	Note
	Exception: The environment variables BUILDDATE, BUILDVERSION, some other variables that are used internally, and all variables that start with MLAB_ or INSTALLER_ are accessible without the ENV_ prefix.

The following special variables are also supported:

$(INPUT) and $(OUTPUT) can be switched anywhere in the script. Collect statements always use the currently defined $(INPUT)/$(OUTPUT) pair for input scanning and the output target directory.

The statement

INCLUDE file

is equivalent to replacing this statement by the contents of the specified file. INCLUDE statements are processed recursively. If the file is not specified using an absolute path, it is searched

INCLUDE_IF_EXISTING file

IF(N)DEF VAR
ELIF(N)DEF VAR
ELSE
ENDIF

IF(N)SET VAR
ELIF(N)SET VAR
ELSE
ENDIF

IF [VAR|"String"] [==|!=|=~|!~] [VAR|"String"]
ELIF [VAR|"String"] [==|!=|=~|!~] [VAR|"String"]
ELSE
ENDIF

IF [EXISTS|ISFILE|ISDIR] [VAR|"String"]
ELIF [EXISTS|ISFILE|ISDIR] [VAR|"String"]
ELSE
ENDIF

	Note
	VAR stands for a variable name. $(VAR) evaluates to the value of the variable.

The (EL)IFDEF directives evaluate to true if the specified variable is defined and its value is neither 0 nor an empty string.

(EL)IFNDEF evaluates as above, but negated.

(EL)IF(N)SET directives test whether the specified variable is defined (or undefined in the case of IFNSET); the variable's value is not considered.

The operators == and != perform a string comparison, while =~ and !~ perform a regular expression search of the second argument within the first.

The versions that contain ! are always the negation of their counterparts with =.

The syntax for regular expressions is that of the Python re package.

The EXISTS, ISFILE, and ISDIR operators check for the existence of files or directories in the file system. To concatenate path fragments, enclose the argument in quotes, e.g., IF EXISTS "$(LOCAL)/someFile.txt".

The statement

PRECOMPRESS_COMPRESSION_LEVEL level

defines the compression level used in pre-compression. Pre-compression is used on Windows if either precompressCurrentDirectory.mli or precompressPackages.mli is included and DISABLE_INSTALLER_PRECOMPRESSION is not defined.

In this case, the files to be added to the installer are first packaged into one or more zip files (using 7zip), which are then added to the installer. This ensures support for long file paths and better compression than the default method.

Valid values for level range from 1 (lowest compression rate) to 9 (highest compression rate); the default is 9.

This setting allows trading compression ratio for compression speed.

The statement

PRECOMPRESS_COMPRESSION_NUM_THREADS numThreads

defines the number of threads (numThreads) used in pre-compression (see PRECOMPRESS_COMPRESSION_LEVEL for details).

Valid values for numThreads are positive integers; the default is 8.

	Note
	The memory consumption increases with the number of threads, so avoid setting the value too high on systems with limited RAM.

The statement

PREPROCESS_EXECUTE command

executes the specified command early while parsing the .mli and .mlinstall files. This allows to create .mli files or other files that are later included with INCLUDE or read with READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE in the same run of assembleInstaller.

The statement

PREPROCESS_CHECK_EXECUTE command

is a variant of PREPROCESS_EXECUTE that does not report an error if the command exits with a nonzero code. Instead, the exit code is written as a string to the variable LAST_EXIT_CODE, which should always be checked in an IF statement afterward, as there is no reason to use this directive otherwise.

The statement

PREPROCESS_MKDIR path

is a variant of MKDIR executed while parsing the .mli and .mlinstall files. It is useful when a directory must be created before running another command with PREPROCESS_EXECUTE.

The statement

PRINT       string1 string2 ...
PRINT_ERROR string1 string2 ...

can be used to print information or non-fatal error messages to the console output.

The statement

[REGEX_]REPLACE_STRING_IN_VARIABLE varname string1 string2

replaces all occurrences of string1 in the variable varname with string2. The variable name can contain * characters, allowing the replacement to occur in multiple variables.

Example:

REPLACE_STRING_IN_VARIABLE INSTALLER_* "/" "\"

replaces all slashes with backslashes in all variables that start with INSTALLER_.The statement is executed immediately, so variables assigned afterward already use the replaced values.

The REGEX_REPLACE_STRING_IN_VARIABLE statement enables the use of regular expressions.

The statement

REGEX_CAPTURE_IN_VARIABLE sourceVarName targetVarName regExp captureGroup

searches for the given regular expression in the value of the sourceVarName variable. The specified captureGroup is extracted from the result and assigned to targetVarName.

Example:

# First read into a variable
READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE TMP_VERSION_FILE
  $(MLAB_MeVis_Foundation)/Configuration/MeVisLabVersion.pri

# Now capture the version number using a regular expression
REGEX_CAPTURE_IN_VARIABLE TMP_VERSION_FILE MEVISLAB_VERSION
  "^\s*MEVISLAB_VERSION_STRING\s*=\s*([^\s]+)\s*$" 1

This code loads the content of the specified file into a temporary variable and searches it for a line containing MEVISLAB_VERSION_STRING = xxx. The version is then captured by the regular expression and stored in MEVISLAB_VERSION.

The statement

HTML_ESCAPE_IN_VARIABLE varName

replaces all special characters in varName with HTML entities and stores the result back to varName.

The statement

(TOUPPER|TOLOWER)_IN_VARIABLE varName

converts the string in varName to either all uppercase or all lowercase characters.

The statement

READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE varName pathToFile

loads the content of the specified file at pathToFile into the variable varName.

The statement

MKDIR path

creates the directory and all required parent directories. If path is not absolute, it is interpreted as relative to the $(OUTPUT) directory.

The statement

CD path

changes the current directory to path. The path can be relative to the script or absolute.

The statement

COPY source target [exclude-pattern]

copies files from source to target. The source can be a single file, a directory, or a path with wildcards.

If source is not an absolute path, it is interpreted relative to the directory containing the installer script.

If target is not an absolute path, it is interpreted relative to the $(OUTPUT) directory.

If target ends in an / or \, it is interpreted as a directory.

The following cases are handled:

An optional third argument can be provided to specify an exclude pattern. The pattern syntax follows the Python re package.

Any file path that matches this pattern, even partially, will not be copied.

The statement

MOVE source destination

moves files or directories from source to a new destination.

Example:

>MOVE $(OUTPUT_ROOT)/SomeFile.txt $(OUTPUT_ROOT)/SomeOtherFile.txt

The statement

LINK source target

creates a link of target to the specified source.

Example:

>LINK $(OUTPUT_ROOT)/SomeFile.txt $(OUTPUT_ROOT)/SomeOtherFile.txt

	Note
	On Windows, unprivileged users may not have permission to create symlinks.

The statement block

TEMPLATE_BEGIN source target
  TEMPLATE_USE_VARIABLES SOMEVARIABLE_PREFIX
  @TVAR value
  ...
TEMPLATE_END

is a special copy statement that copies the file source to target and replaces template macro expressions of the form @(TVAR) with the value of the template variable TVAR. Both source and target must specify single files, evaluated relative to the directory containing the installer script and the $(OUTPUT) directory, respectively.

Template variables are defined locally within the template block and are independent of environment variables or template variables defined in another template block. Preprocessor variables can be used in the values assigned to a template variable. A $ in a template variable assignment can be escaped with $$.

In the source template file, the conditional directives

@IF (TVAR)
@ELSEIF (TVAR)
@ELSE
@ENDIF

may be used. The expression in an @IF/@ELSEIF directive evaluates to true if the template variable TVAR is defined and evaluates to the boolean value true (i.e., neither 0 nor an empty string).

A ! preceding the template variable name negates the expression.

TEMPLATE_USE_VARIABLES can be used multiple times within a block and treats all variables starting with the given prefix as template variables.

Example:

TEMPLATE_USE_VARIABLES PREFSFILE_

takes all variables declared with $PREFSFILE_... as @PREFSFILE_... variables to be used in the template.

This allows setting template variables without specifying them within the template block statement.

The statement block

ZIP_BEGIN sourcePath targetZipFile
  OPTIONS arg1 arg2 ...
  COMPRESSION [0-9]
  REMOVE_ORIGINAL_FILES
  + ...
  - ...
  ...
ZIP_END

collects files via + and - statements that act on the given sourcePath and places them into the targetZipFile.

The OPTIONS command can be used to add zip command-line options.

COMPRESSION defines the compression level: 0 stores the files without compression, while 9 applies maximum compression.

REMOVE_ORIGINAL_FILES indicates that the original files added to the .zip archive should be deleted afterward.

The contents of the zip file are relative to the sourcePath.

If you require a different zip file layout, copy the files to a temporary directory first and run the ZIP block with that directory as sourcePath.

	Note
	Global exclude rules (deferred via >-) do not apply to the collect statements within the ZIP block. ZIP blocks must be run after all corresponding ZIP_COLLECT statements!

In the statement block

ZIP_COLLECT_BEGIN targetZipFile
  + ...
  - ...
ZIP_COLLECT_END

the enclosed collect and exclude statements (+/-) are appended to those of the ZIP block. The paths in these must be relative to the sourcePath of the ZIP block.

	Note
	It is important that ZIP_COLLECT statements are processed before the corresponding ZIP block is executed!

The statement

EXECUTE command

runs the specified command in the directory containing the installer script.

The variant

EXECUTE_NO_FAIL command

The statements

+ path
+L path
+? path

- filter
-G filter
-GR filter

are used to define a list of source files copied to the $(OUTPUT) directory. The +(L) statement adds all files matching the specified path, which is evaluated relative to the $(INPUT) directory (absolute paths are not allowed).

If the path specifies a directory, all files in that directory are added. The + statement adds files recursively, while the +L statement ("local") only adds files in the specified directory.

+? optionally adds files and does not report an error if the file does not exist.

The - statement removes all files from the list that match the specified filter and share the same input directory as the current one.

The -G statement acts globally, removing all matching files regardless of their input directory. It does not affect files that are added by a subsequent + statement.

The -GR statement also acts globally, removing all matching files, but the filter is considered to be a valid regular expression.

Files collected by those statements are copied after the last collect/exclude statement, i.e., before the non-collect or non-exclude statements without < or > (see Section 3.3, “Execution Statements”).

For both path and filter, the wildcards * and ? can be used, as well as [...] and (...|...|...) alternatives.

< and > mark directory name boundaries, allowing a directory to match even if it is at the beginning or end of the path.

Collect + patterns are matched against the start of the relative file path, while exclude - patterns are matched against the full relative file path.

A special pair pattern of the form (...) can be used in exclude statements to exclude a file matching the pattern when a paired file without the (...) expression is included. If the pair pattern expression starts with !, the file without the (...) expression is excluded.

Examples:

+ Dir1/Dir2      # Include Dir1/Dir2 and all subdirectories
+ Dir1/Dir[23]   # Include Dir1/Dir2 and Dir1/Dir3
+ Dir1/(one|two) # Include Dir1/one and Dir1/two
+ Dir1/*.def     # Include all .def files in Dir1 and subdirectories

- *.bak          # Exclude all .bak files
- *<CVS>*        # Exclude all CVS directories
- *(_d).dll      # Exclude all *_d.dll files, for which a *.dll exists
- *(!_d).dll     # Exclude all *.dll files, for which a *_d.dll exists

The statement

SWITCH_PACKAGE [SubDirectory/]PackageGroup/PackageName

switches $(INPUT) and $(OUTPUT) to the specified package. As a result, $(INPUT) points to $(MLAB_PackageGroup_PackageName) and $(OUTPUT) points to $(OUTPUT_PACKAGES_ROOT)/[SubDirectory/]PackageGroup/PackageName.

The output directory is created if it does not already exist. All subsequent collect statements or uses of $(INPUT) or $(OUTPUT) apply to the specified package.

Additional variables are set: $(CURRENT_PACKAGE_OUTPUT) points to the $(INPUT) of the package and $(CURRENT_PACKAGE_INPUT) points to the $(OUTPUT) of the package. These can be used if INPUT or OUTPUT are modified locally.

Examples:

SWITCH_PACKAGE MeVisLab/Foundation
+ lib
+ bin

SWITCH_PACKAGE MyPackageGroup/MyPackage
+ lib
+ bin

The statement

PUT_DIRECTLY_TO_FILELIST ext1 ext2 ext3 ...

adds the specified extensions to a list of file extensions.

All files with one of these extensions are added to a file list instead of being copied to $(OUTPUT).

This can be used, for example, with NSIS installers that can access the source data directly. In such cases, it is not necessary to copy files such as DLLs to the output directory, since they are not modified by the scripts (in contrast to MDL .script files, which are signed).

Typically, this statement should be placed early in the execution queue using <.

Example:

IFDEF WIN32
  <PUT_DIRECTLY_TO_FILELIST .dll .pyd .tiff .tif .dcm
                            .jpg .png .html .lib .exe .gif
ENDIF

The statement

WRITE_NSIS_FILELIST NSIS_OUTPUTFILE NSIS_OUTPUTFILE_UNINSTALL relativePath1
                                               relativePath2 ...

can be used to generate complete source and destination file lists for NSIS installers. It considers both the file list generated by PUT_DIRECTLY_TO_FILELIST and the files copied to the $(OUTPUT_ROOT) directory. If relativePath1 is ., the entire $(OUTPUT_ROOT) directory is included.

Example:

>WRITE_NSIS_FILELIST $(INSTALLER_TMP)/binList.nsi
                     $(INSTALLER_TMP)/binListUninstall.nsi
                     bin

The statement

DELETE target1 target2 ...

removes the specified target file(s) or directories. Globbing patterns are supported for each target. Removal is not recursive.

Example:

>DELETE $(OUTPUT_ROOT)/SomeFile.txt

The DELETE_SILENT variant of this command does not report an error if no files are deleted.

The statement

FIND_AND_DELETE directory pattern1 pattern2 ...

removes the files matching the specified patterns, searched recursively within the given directory.

Example:

>FIND_AND_DELETE $(OUTPUT_ROOT) .svn