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. (Exception: Environment variables BUILDDATE, BUILDVERSION, some others, 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 set $(INPUT)/$(OUTPUT) pair for scanning and target directory.

The statement

INCLUDE file

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

VAR stands for a bare variable name, without braces ($()) around it.

The directives in the block above are processed as usual. The (EL)IFDEF directives evaluate to true if the specified variable is defined and does not have the value "0" or "" (empty string). (EL)IFNDEF is evaluated as above and negated. (EL)IF(N)SET directives test if the specified variable is defined (or undefined in IFNSET case), it does not consider the variable's value.

The operators "==" and "!=" do a string comparison, while "=~" and "!~" do a regular expression search of the second argument in the first argument. (The versions which contain "!" are always the negation of their counterparts with "=".) The syntax for regular expressions is that of the "re" package of Python.

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

Defines the compression level used in pre-compression. Pre-compression is used under Windows if one of 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 will afterward be added to the installer. This ensures support for long file paths, and a better compression compared to the default. Valid values for PRECOMPRESS_COMPRESSION_LEVEL range from 1 (lowest compression rate) to 9 (highest compression rate), the default is 9. It can be used to trade compression rate for compression speed.

The statement

PREPROCESS_EXECUTE command

executes the specified command very early while parsing the mli/mlinstall files. It 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 assembleInstaller run.

The statement

PREPROCESS_CHECK_EXECUTE command

is a variant of PREPROCESS_EXECUTE that does not print an error if the command exits with an error code. Instead the exit code is written (as string) to the variable LAST_EXIT_CODE, which should always be evaluated in an IF statement afterwards, since there is no reason to use this statement otherwise.

The statement

PREPROCESS_MKDIR path

The statement

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

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

The statement

[REGEX_]REPLACE_STRING_IN_VARIABLE varname string1 string2

will replace all occurrences of "string1" in the variable "varname" with "string2". Varname can contain "*" chars, so that the replacement takes place in more than one variable.

Example:

REPLACE_STRING_IN_VARIABLE INSTALLER_* "/" "\"

replaces all slashes with backslashes in variables that start with INSTALLER_. This statement is executed immediately, so that variables assigned after the statement take the replaced variables already.

The REGEX_REPLACE_STRING_IN_VARIABLE statement allows the use of regular expressions.

The statement

REGEX_CAPTURE_IN_VARIABLE sourceVarName targetVarName regExp captureGroup

searches for the given regexp in the value of the sourceVarName variable. The result is queried for the captureGroup and the capture is 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 regexp
REGEX_CAPTURE_IN_VARIABLE TMP_VERSION_FILE MEVISLAB_VERSION 
  "^\s*MEVISLAB_VERSION_STRING\s*=\s*([^\s]+)\s*$" 1

Will load a given file to a variable and search that file for a line with MEVISLAB_VERSION_STRING = xxx and captures the version into MEVISLAB_VERSION.

The statement

HTML_ESCAPE_IN_VARIABLE varName

replaces any special characters into HTML entities and writes the result back to varName.

The statement

(TOUPPER|TOLOWER)_IN_VARIABLE varName

changes the string in varName to all upper/lower case characters.

The statement

READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE varName pathToFile

loads the content of the given file into the variable varName.

The statement

MKDIR path

performs a deep “make directory”. If path is not absolute, it is treated as relative to the $(OUTPUT) directory.

The statement

CD path

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

The statement

COPY source target [exclude-pattern]

copies files from source to target. The source may be a single file, a directory or a path with wildcards. If source is not an absolute path, it is treated as local to the directory containing the installer script. If target is not absolute, it is treated as relative to the $(OUTPUT) directory.

The following cases are handled:

If target ends in an '/' or '\', it is forced to be treated as a directory.

You can provide an exclude pattern as the optional third argument to this command. The pattern syntax is that of the Python re package. If a file path matches this pattern at least in part, it will not be copied.

The statement

MOVE source destination

moves files or directories 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 given source.

Example:

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

	Note
	On Windows a unprivileged user may not be allowed 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) by the value of the template variable TVAR. Source and target must both specify single files and are evaluated relative to the directory containing the installer script and the $(OUTPUT) directory, respectively.

Template variables are defined locally inside the template block and have no relation to environment variables or to template variables defined in another template block. Preprocessor variables can be used within the values assigned to a template variable. A '$' in a template variable assignment can be escaped by '$$'.

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. is not 0 or an empty string). A '!' preceding the template variable name negates the expression.

TEMPLATE_USE_VARIABLES can be used multiple times inside of the block and takes the variables that start with the given prefix as template variables.

Example:

TEMPLATE_USE_VARIABLES PREFSFILE_

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

This allows to set template variables without specifying them inside of 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 are then placed into the targetZipFile. The OPTIONS command can be used to add Zip commandline options. COMPRESSION defines the compression, 0 is store, 9 is maximum compression. REMOVE_ORIGINAL_FILES signals that the original files that are placed in the zip file should be deleted after they were added to the zip. The Zip file contents are relative to the sourcePath.

If the layout of the Zip file should be different, you will need to copy files to a temporary directory first and run the ZIP block with that directory as sourcePath.

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

The statement block

ZIP_COLLECT_BEGIN targetZipFile
  + ...
  - ...
ZIP_COLLECT_END

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

	Note
	It is important that ZIP_COLLECT statements are handled before the corresponding ZIP block is run!

The statement

EXECUTE command

The variant

EXECUTE_NO_FAIL command

The statement

+ path
+L path
+? path
- filter

are used to define a list of source files that are 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 within this directory are added. The '+' statement adds files recursively, the '+L' statement ("local") only adds files in the specified directory. '+? allows to optionally add files and does not print an error if the file does not exist. The '-' statement removes all files from the list that match the specified filter and have the same input directory as the current input directory. The '-G' statement acts globally and removes all matching files regardless of their input directory. It does not affect files that are added by a subsequent '+' statement. The files collected by these statements are copied after the last collect/exclude statement, i.e. before the non- collect/exclude statements without '<' or '>'.

For both path and filter, wildcards '*' and '?' can be used, as well as '[...]' and '(...|...|...)' alternatives. '<' and '>' can be used for directory name boundaries to match a directory even if it is at the beginning or end of the path. Collect ('+') patterns are matched against the beginning of the relative file path, 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, for which a paired file without the '(...)' expression is included. If the pair pattern expression starts with a '!', 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 wich a *.dll exists
- *(!_d).dll     # Exclude all *.dll files, for wich a *_d.dll exists

The statement

SWITCH_PACKAGE [SubDirectory/]PackageGroup/PackageName

switches $(INPUT) and $(OUTPUT) to the given package. Thus $(INPUT) will point to $(MLAB_PackageGroup_PackageName) and $(OUTPUT) will point to $(OUTPUT_PACKAGES_ROOT)/[SubDirectory/]PackageGroup/PackageName. The output directory is created if it does not yet exist. All subsequent collect statements or uses of $(INPUT)/$(OUTPUT) work on the given package.

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

Examples:

SWITCH_PACKAGE MeVisLab/Foundation
+ lib
+ bin

SWITCH_PACKAGE OEM/Visia/Enterprise
+ lib
+ bin

The statement

PUT_DIRECTLY_TO_FILELIST ext1 ext2 ext3 ...

adds the given extensions to a list of file extensions.

All files that have one of these extensions are put into a filelist, instead of copying the file to $(OUTPUT).

This can be used for e.g. NSIS installers, which can take the source data from anywhere and it is not required to copy e.g. DLLs to the output directory, because they are not manipulated by the scripts (in contrast to e.g. MDL script files, which are signed).

Typically you will want to put this into the early 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 ...

This can be used to generate complete src/dest filelists for NSIS installers. It takes into account both the filelist generated by PUT_DIRECTLY_TO_FILELIST and also scans the copied files at the $(OUTPUT_ROOT) directory. If RelativePath1 equals ".", the whole $(OUTPUT_ROOT) directory is taken.

Example:

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

The statement

DELETE target1 target2 ...

removes the given target file(s) or directories, it supports globbing patterns for each target. It does not descend recursively.

Example:

>DELETE $(OUTPUT_ROOT)/SomeFile.txt

There is also a DELETE_SILENT variant of this command which doesn't print an error message if nothing is deleted.

The statement

FIND_AND_DELETE directory pattern1 pattern2 ...

removes the files matching the patterns found recursively in given directory.

Example:

>FIND_AND_DELETE $(OUTPUT_ROOT) .svn