Application Development Kit (ADK)


Table of Contents

About this Document
1. Installer Wizard
1.1. Starting the Installer Wizard
1.2. Installer Wizard Start Screen
1.3. General Settings
1.4. Adding Files
1.5. Application Options
1.6. Additional Application Options
1.7. Installer Files
1.8. Example .Wiz File (Standalone)
2. Application License Manager
2.1. Using the Application License Manager
2.2. Example License File
2.3. License File Search Paths
3. Installer Script Language Specification
3.1. General Remarks
3.2. Preprocessor Statements
3.2.1. Preprocessor Variables
3.2.2. INCLUDE Statements
3.2.3. Conditional Directives
3.2.4. PREPROCESS_EXECUTE Statements
3.2.5. PREPROCESS_CHECK_EXECUTE Statements
3.2.6. PREPROCESS_MKDIR Statements
3.2.7. PRINT and PRINT_ERROR Statement
3.2.8. [REGEX_]REPLACE_STRING_IN_VARIABLE Statement
3.2.9. REGEX_CAPTURE_IN_VARIABLE Statement
3.2.10. HTML_ESCAPE_IN_VARIABLE Statement
3.2.11. TOUPPER_IN_VARIABLE/TOLOWER_IN_VARIABLE Statement
3.2.12. READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE Statement
3.3. Execution Statements
3.3.1. MKDIR Statements
3.3.2. CD Statements
3.3.3. COPY Statements
3.3.4. MOVE Statement
3.3.5. LINK Statement
3.3.6. TEMPLATE Statements
3.3.7. ZIP Statements
3.3.8. ZIP_COLLECT Statement
3.3.9. EXECUTE Statements
3.3.10. Collect/Exclude Statements
3.3.11. SWITCH_PACKAGE Statement
3.3.12. PUT_DIRECTLY_TO_FILELIST Statement
3.3.13. WRITE_NSIS_FILELIST Statement
3.3.14. DELETE Statement
3.3.15. FIND_AND_DELETE Statements
3.4. Standalone Application Installer Variables
4. Advanced Commands
4.1. runApplicationCommand

List of Figures

1.1. Project Wizard
1.2. Installer Wizard
1.3. General Settings
1.4. Adding Files Manually
1.5. Application Options
1.6. Additional Options
1.7. Generated Installer Files
2.1. Application License Manager
2.2. Application Missing License Dialog

About this Document

The following document includes special features that come with the application development kit (ADK) of MeVisLab.

The difference between the SDK and the ADK is that with the latter, stand-alone applications (installers) can be created. For being able to use that, your own license file needs to be an ADK license file.

Chapter 1. Installer Wizard

To ease the installer generation for an application, an Installer Wizard is available. This Wizard leads through the creation of the .mlinstall file which can then be used in a build process, e.g. in ToolRunner.

[Note]Note

For further information on the MeVisLab Project Wizard, please refer to the MeVisLab Reference Manual.

1.1. Starting the Installer Wizard

In the menu bar of MeVisLab, open FileRun Project Wizard and select Standalone Application.

Figure 1.1. Project Wizard

Project Wizard

This opens the Installer Wizard, which leads through the creation of a stand-alone application (or in a first step, the .mlinstall file necessary for it) from a macro module.

For using the Installer Wizard, the following programs have to be installed:

  • MeVisLab ADK, for signing the files and creating the standalone application

  • (Windows only) Dependency Walker (version see link in MeVisLab)

  • (Windows only) NSIS Installer (version see link in MeVisLab)

Move between the dialogs with Back and Next. At any point, the settings can be saved as .wiz file (see Section 1.8, “Example .Wiz File (Standalone)”) via Save Setting.

1.2. Installer Wizard Start Screen

Figure 1.2. Installer Wizard

Installer Wizard

The info text is only available on Windows.

Macro Module

Set the macro module to be used for the application. Select one from the list.

Target Package

Set the target package. Select a target from the list (or stop here and create a user package with the Package Wizard first).

Check if required tools are installed (Windows only)

Run the tool check tool (which is also part of ToolRunner).

1.3. General Settings

Figure 1.3. General Settings

General Settings

Product Name

Enter the product name. Can be chosen freely.

Version

Enter the program version.

Release, Debug

Select whether the installer includes the release and/or debug version.

[Note]Note

For each option, the C++ code is compiled accordingly.

Precompile Python files

All python files will be precompiled if selected.

Exclude original Python files (*.py)

If python files are precompiled, then it is possible to exclude the original python files from the installer.

Create Packages.zip

Choose whether you would like to create a Packages.zip file containing all *.(py|pyc|script|def|mlab|js|txt|png) files. This is an optimization because MeVisLab does not access the file system for each of those small files.

[Note]Note

It is currently not possible to use the Packages.zip when referencing PNG images in Qt stylesheets, because Qt cannot load the images from the zip file.

License

Set the license that is used for signing the application file.

1.4. Adding Files

The required files of the macro module are detected by the dependency analysis of MeVisLab and are automatically added to the installer.

The ModuleDependencyAnalyzer module can be used to test the result of the automatic analysis. If required files are missing, then they should be added to the Deployment section of the module that depends on it. If there is a reason for not adding files to the Deployment section, then they can be manually specified here.

Figure 1.4. Adding Files Manually

Adding Files Manually

If not all necessary files have been found automatically, more commands and files can be added manually.

1.5. Application Options

Figure 1.5. Application Options

Application Options

Window Mode

Set the window mode of the application upon startup. Available options are Maximized, Normal, Full Screen.

Splash Screen Image

Set the screen to be shown upon startup of the application. Preferably in .png format.

Icon File Win32

Set the icon displayed for the application on Windows. Preferably in .ico format.

Icon File Mac

Set the icon displayed for the application on Mac. Needs to be in .icns format.

Create application with diagnosis console (for debugging only)

Add the diagnosis console to the application.

1.6. Additional Application Options

Figure 1.6. Additional Options

Additional Options

Header Image Win32

Set the image to be displayed upon startup of the installer (on Windows).

Header Image Mac

Set the image to be displayed upon startup of the installer (on Mac).

This is the last dialog. Now the installer can be created.

1.7. Installer Files

Figure 1.7. Generated Installer Files

Generated Installer Files

The installer is first created as a collection of files:

  • <ProductName>.autodetect.mli: List of files and paths collected via Auto-Detect.

  • <ProductName>.bat: Windows batch file for calling up the Python script and the .mlinstall file.

  • <ProductName>.mlinstall: file with the installer information. For the installer script language details, see the chapter Chapter 3, Installer Script Language Specification.

  • <ProductName>.sh: Shell script for Linux/macOS (equivalent to batch file).

The installer compilation needs to be started explicitly via the batch file or shell script.

Create Installer

Starts the ToolRunner to build the executable.

[Note]Note

The application files are signed and encrypted automatically. If the files shall remain uncrypted, this needs to be stated explicitly in the <ProductName>.mlinstall file by adding the line

$STANDALONE_NO_FILE_CRYPTING 1 # don't crypt files (after the $Product name).

(For the installer script language details, see the chapter Chapter 3, Installer Script Language Specification.)

Browse Output Directory

Open the output in the default file browser.

Create Application License

Create an application license (.dat file) to be distributed with the application. Starts the Application License Manager, see Chapter 2, Application License Manager

Close

Close the installer generation at this point. The output files will remain in the output directory.

1.8. Example .Wiz File (Standalone)

// MDL v1 utf8
wizard = StandaloneAppWizard
fields  {
  instanceName  = wizard
  moduleName    = CurveInspector
  productName   = CurveMaker
  debugFlag     = 0
  releaseFlag   = 1
  diagnosisFlag = 0
  version       = 1
  licensePath   = "C:/Dokumente und Einstellungen/jdoe/mevislablicense.dat"

  autoAssembleInstallerScript = "# Switching to package MeVisLab/Standard
                                 SWITCH_PACKAGE MeVisLab/Standard
                                 + Package.def
                                 + Modules/ML/MLBase
                                 + Modules/ML/MLMiscModulesInv
                                 + Modules/Macros/Inspectors"

  assembleInstallerScript = ""
  splashScreenImage       = ""
  headerImageWin32        = ""
  iconFileWin32           = ""
  headerImageMac          = ""
  iconFileMac             = ""
  windowMode              = MAXIMIZED
  createEnable            = TRUE
  packageIdentifier       = MyPackageGroup/Research
}

Chapter 2. Application License Manager

[Note]Note

ADK licenses that allow the creation of own run-time licenses with the Application License Manager are no longer available for customers. If you need run-time licenses please contact the MeVis Medical Solutions AG sales department.

MeVis Medical Solutions AG Caroline-Herschel-Str. 1 28359 Bremen Germany Tel.: +49 421 22495 0 Fax: +49 421 22495 999 sales@mevislab.de

2.1. Using the Application License Manager

In the menu bar of MeVisLab, open FileRun Application License Manager.

Figure 2.1. Application License Manager

Application License Manager

Change License

Click here to change the license based on which the new license should be created. A file dialog opens. The default license is your own developer license.

Customer Information:

Site Id

Enter the Site Id, for example a company name, “The Medical Company”.

Owner Full Name

Enter the full name of the application license owner, for example “John Doe”.

Mail

Enter the owner's mail address, for example “jdoe@mymail.com”.

Info

Enter any free text information regarding the application and/or license.

License Settings:

Applications

Select the application(s) that the generated license should allow to run. Applications are listed by package groups. Additional applications can be added in the field Manual applications.

Selected Applications Overview

All selected applications are displayed in this area.

Available License Features

This box lists special features that can be made available for the end user license. Only features permitted by the developer license are listed.

Hardware Addresses

The end user license can be restricted to computers with a certain MAC address (the hardware address of the network adapter). If no addresses are given, there is no restriction, otherwise the license will only be valid on a computer which has one of the given MAC addresses.

The MAC address of a user can easily be found out if the user starts the created application. A “missing license” dialog will be shown that also has a System Information button, that will show the MAC addresses of all installed network adapters together with the type of the adapter.

Figure 2.2. Application Missing License Dialog

Application Missing License Dialog

License expires

Check this option to set an expiration date in the field to the right.

Save

Click to save the license. The Save dialog opens. The license name is constructed as “CurrentDate_SiteID_OwnerName.dat”. In the example this results in a license named “20090224_The Medical Company_John_Doe.dat”. The created license is signed with the MeVis license.

2.2. Example License File

The generated license may look as follows:

// MDL v1 utf8
license  {
  version = 1
  owner  {
    id       = "The Medical Company"
    mail     = "jdoe@mymail.com"
    fullName = "John Doe"
    info     = "This application is for demo purposes only. "
  }
  publicKey  = ""
  privateKey = ""
  features   = "application CurveInspector"
  expire     = 2009-05-24
  platform   = "win32 macos linux"
  tickets  {
    ticket application {
      value =
      "K2ttRTRxa2lnSjREUHFNRjFxZ1plSCt5RXNTYUh4VFVjSjA1S0YxZ29NNlZrSW5
      yYVU3UFJyeHJ6bWFtbXBMbkdoM3kwYklYCm02YlFIamt0WEd5cVNRU1JIZCtVSWd
      MdgoKLy8jIE1lVmlzIHNpZ25hdHVyZSB2MQovLyMga2V5OiBNRm93RFFZSktvWkl
      odmNOQVFFQkJRQURTUUF3UmdKQkFNZUxFVHprUEhQbkwxS3NSNXFjT1F0NEJ2T1c
      0NUpKTnlscDlpMUhodVJlTGgvRVRqT0M2K3BoSnFWR0ZHS3I3OXB6OE45MXdhYjh
      mb0dHNUpEWEpmVUNBUkU9OmVoR1hncStvQzZscVVSZENxWWZrb0NVeml3RzFVMUF
      HaFV2UFpBbVpSUU9kYkFtRkdybndKeGd0LzJ0RjlNZU9sTzQzSDVkYk40T2gwTmU
      zMDVkYUFBPT0KLy8jIG93bmVyOiBNZVZpcyBMaWNlbnNlTWFuYWdlcgovLyMgZGF
      0ZTogMjAwOC0wNi0yNFQxNzowMzoxOAovLyMgZmxhZ3M6IGNyeXB0ZWQKLy8jIGh
      hc2g6IEh1ZC9FQXFPWXpGTmZWNm91M1RQRDhvTUplTk41dXpNaXMwYmNxVXlKUEI
      3ZnYyL0dLbEozSmZBV2ViSnA5b0FRajRyY3MxVjRCMjNNZHFkdVRYNzJ3PT0KLy8
      jIE1lVmlzIGVuZAo="
    }
  }
}

//# MeVis signature v1
//# key:
MFowDQYJKoZIhvcNAQEBBQADSQAwRgJBAJ39AF/+qRFGV0lZzIzNP4omakEwTD6kCi8JyX
EVrGPusCE1lC7nmusDutrgfEC17wdGJljOayO/txkXTBxpkFcCARE=:DLuRbU1lg8t990I
RMCieK8NkY7E5AjAp3jIGWrcs1gSGWy+HVlgt1skD4tXED+0TjB0NSfKZHJn+NiqQFXhTu
Q==
//# owner: StandaloneMeVisApp
//# date: 2009-02-24T14:31:42
//# hash:
KSjfg+gKjNTNNsag4ifyLFN/aUkuPmoT4Q2upxXa4g2XiQTSXqXUJ2CCejrp72CZeRn3iU
4XGUNW4XqxWcQKmQ==
//# MeVis end

2.3. License File Search Paths

This pseudo code shows where MeVisLab searches for license files and in which order. The first valid license that is found is used:

getLicenseFile() 
{
  if (overrideLicenseFilePath)
  {
    // overridden license file path from the command line 
    // option "-license <license file path>"
    licenseFile = overrideLicenseFilePath
    return licenseFile
  } 
  else 
  { 
    if (windows) 
    {
      // e.g., C:/Documents and Settings/Username/<appname>license.dat
      licenseFiles  = QDir::homePath()/<appname>license.dat
      
      // e.g., C:/Documents and Settings/Username/My Documents/
      //          <appname>license.dat
      licenseFiles += winGetSpecialFolder(CSIDL_PERSONAL)/<appname>license.dat>
      
      // e.g., C:/Documents and Settings/Username/My Documents/MeVis/ 
      //          <appname>license.dat
      licenseFiles += winGetSpecialFolder(CSIDL_PERSONAL)/MeVis/ \
                      <appname>license.dat
      
      licenseFiles += <Install Path>/<appname>license.dat
    }

    if (linux) 
    {
      licenseFiles  = $(HOME)/.local/share/MeVis/<appname>/<appname>license.dat
      licenseFiles += $(HOME)/Documents/MeVis/<appname>license.dat
      licenseFiles += <Install Path>/<appname>license.dat
    }

    if (macos) 
    {
      // e.g., /Users/doe/bonelicense.dat
      licenseFiles  = $(HOME)/<appname>license.dat
      
      // e.g., /Users/doe/Library/Application Support/Bone/Licenses/bonelicense.dat
      licenseFiles += $(HOME)/Library/Application Support/BundleName/Licenses/ \
                      <appname>license.dat
         
      // e.g., /Users/doe/Library/Application Support/Bone/bonelicense.dat
      licenseFiles += $(HOME)/Library/Application Support/BundleName/ \
                      <appname>license.dat
          
      // e.g., /Library/Application Support/Bone/Licenses/bonelicense.dat          
      licenseFiles += /Library/Application Support/BundleName/Licenses/ \
                      <appname>license.dat
           
      // e.g., /Applications/Bone.app/Contents/Licenses/bonelicense.dat 
      licenseFiles += <Install Path>/Contents/Licenses/ \
                      <appname>license.dat                         
    }
    
    if (hasEnvVar("<APP_NAME>_LICENSE_FILE")) 
    {
      licenseFiles += getEnvVar("<APP_NAME>_LICENSE_FILE")
    }
    
    // use first valid license file
    for (licenseFile in licenseFiles) 
    {
      if (existsAndIsValid(licenseFile)) 
      {
        break
      }
    }
    return licenseFile
  }
}
      

Chapter 3. Installer Script Language Specification

The contents of this chapter can be found in the folder MeVis\BuildSystem\BuildTools, file assembleInstallerSyntax.txt. In case of divergences between the two documents, the text file is the relevant file.

3.1. General Remarks

Installer scripts are used to collect all files necessary for a certain installer version in a temporary output directory and call an installer generator to create the installer executable. Most of the installer script statements occupy a single line, except for TEMPLATE blocks, which consist of several lines enclosed by TEMPLATE_BEGIN and TEMPLATE_END statements, and #if(n)def .. #else(if) .. #endif directives.

Installer script statements are either preprocessor or execution statements. During the preprocessing step, the script is read, and the execution statements are collected and put into the specified order. During the execution step, the execution statements are executed to collect the files and to generate the installer.

Both '/' and '\' are accepted as path separators, except for the first one, which has to be '\' on windows (e.g. "C:\" and not "C:/"). Everything from a '#' character up to the end of the line is treated as comment. Leading and trailing spaces and tabs are ignored.

3.2. Preprocessor Statements

3.2.1. Preprocessor Variables

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)

Defines the current root for collect statements.

$(OUTPUT)

Defines the current output directory as target for collect statements.

$(OUTPUT_ROOT)

Defines the output root directory (taken from OUTPUT on startup).

$(OUTPUT_PACKAGES_ROOT)

Defines the output root directory for Packages (initial value is $(OUTPUT_ROOT)/Packages).

$(WIN32)

Set to 1 on Windows systems.

$(UNIX)

Set to 1 on Linux AND macOS systems.

$(LINUX)

Set to 1 on Linux systems.

$(MACOS)

Set to 1 on macOS systems. The variable MACX is available for backwards compatibility but should no longer be used.

$(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.

3.2.2. INCLUDE Statements

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
  1. in the directory containing the current file

  2. in the current working directory

(in this order).

INCLUDE_IF_EXISTING file
is a variant of this command that silently skips the file if it is not found.

3.2.3. Conditional Directives

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

3.2.4. PREPROCESS_EXECUTE Statements

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.

3.2.5. PREPROCESS_CHECK_EXECUTE Statements

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.

3.2.6. PREPROCESS_MKDIR Statements

The statement

PREPROCESS_MKDIR path
is a variant of MKDIR that is executed while parsing the mli/mlinstall files. It is useful if you need to create a directory before executing some other command with PREPROCESS_EXECUTE.

3.2.7. PRINT and PRINT_ERROR Statement

The statement

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

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

3.2.8. [REGEX_]REPLACE_STRING_IN_VARIABLE Statement

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.

3.2.9. REGEX_CAPTURE_IN_VARIABLE Statement

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.

3.2.10. HTML_ESCAPE_IN_VARIABLE Statement

The statement

HTML_ESCAPE_IN_VARIABLE varName

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

3.2.11. TOUPPER_IN_VARIABLE/TOLOWER_IN_VARIABLE Statement

The statement

(TOUPPER|TOLOWER)_IN_VARIABLE varName

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

3.2.12. READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE Statement

The statement

READ_FILE_AND_WRITE_CONTENTS_TO_VARIABLE varName pathToFile

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

3.3. Execution Statements

Execution statements are used to create directories, copy files and execute external commands. As a special form of copy statements, collect (+) and exclude (-) statements are available to copy and filter whole subdirectories. In general, execution statements are executed in the order they appear in the installer script. By preceding an execution statements with a '<' or '>', it can be pushed to the beginning or the end of the execution queue, resp. The statements in the execution queue are processed in the following order:

  1. All '<' statements except collect/exclude statements

  2. All '<' collect/exclude statements

  3. All collect/exclude statements without '<' or '>'

  4. All '>' collect/exclude statements

  5. All '>>' collect/exclude statements

  6. Now all collected files are copied

  7. All other statements (non-collect/exclude) without '<' or '>'

  8. All '>' non-collect/exclude statements

  9. All '>>' non-collect/exclude statements

3.3.1. MKDIR Statements

The statement

MKDIR path

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

3.3.2. CD Statements

The statement

CD path

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

3.3.3. COPY Statements

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:

  • Source is a file and target does not exist: Source is copied to the file target.

  • Source is a file and target is an existing file: The file target is overwritten by source.

  • Source is a file or directory and target is a directory: Source is copied into target.

  • Source is not a single file and target does not exist or is a directory: The source files are copied into the directory target, which is created in case it does not exist.

  • Source is not a single file and target is an existing file: An error message is generated.

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.

3.3.4. MOVE Statement

The statement

MOVE source destination

moves files or directories to a new destination.

Example:

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

3.3.5. LINK Statement

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]Note

On Windows a unprivileged user may not be allowed to create symlinks.

3.3.6. TEMPLATE Statements

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.

3.3.7. ZIP Statements

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]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!

3.3.8. ZIP_COLLECT Statement

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]Note

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

3.3.9. EXECUTE Statements

The statement

EXECUTE command
executes the specified command in the directory containing the installer script.

The variant

EXECUTE_NO_FAIL command
will ignore a non-zero exit code returned by the command.

3.3.10. Collect/Exclude Statements

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

3.3.11. SWITCH_PACKAGE Statement

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

3.3.12. PUT_DIRECTLY_TO_FILELIST Statement

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

3.3.13. WRITE_NSIS_FILELIST Statement

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

3.3.14. DELETE Statement

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.

3.3.15. FIND_AND_DELETE Statements

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

3.4. Standalone Application Installer Variables

DEBUG

If DEBUG is set to 1, then the debug binaries (executables and libraries) are included in the installer. If it is set to 0, then the debug binaries are excluded.

INSTALLER_BRANDING

INSTALLER_BRANDING might be displayed in the installer. E.g., on Windows the generated NSIS installer will show this string in lower half above the button bar.

The default is "MeVis Medical Solutions AG"

INSTALLER_COMPANY

The string in INSTALLER_COMPANY is used on Windows for the registry key that stores the installation information.

The default is "MeVis"

INSTALLER_COMPILE_ALL_PYTHON_FILES

Set INSTALLER_COMPILE_ALL_PYTHON_FILES to 1 to compile all Python source files (*.py) into *.pyc files will also be included in the installer.

INSTALLER_EXCLUDE_UNCOMPILED_PYTHON_FILES

Set INSTALLER_EXCLUDE_UNCOMPILED_PYTHON_FILES to 1 to exclude all Python source files (*.py) from the installer. This option is typically used in conjunction with INSTALLER_COMPILE_ALL_PYTHON_FILES.

INSTALLER_FINISHPAGE_LINK

Set INSTALLER_FINISHPAGE_LINK to a string that is the title of a link that is shown on the finish page. The link URL must be set with the INSTALLER_FINISHPAGE_LINK_LOCATION variable.

Example: $INSTALLER_FINISHPAGE_LINK Your Link Text

INSTALLER_FINISHPAGE_LINK_LOCATION

Set INSTALLER_FINISHPAGE_LINK_LOCATION to an URL that is shown as a link on the finish page. The link title must be set with the INSTALLER_FINISHPAGE_LINK variable.

Example: $INSTALLER_FINISHPAGE_LINK_LOCATION http://www.whatever.com

INSTALLER_FINISHPAGE_RUN_NOTCHECKED

Set INSTALLER_FINISHPAGE_RUN_NOTCHECKED to 1 to uncheck the run check box by default

INSTALLER_FINISHPAGE_RUN_TEXT

Set INSTALLER_FINISHPAGE_RUN_TEXT to a string to overwrite the run application text.

INSTALLER_FINISHPAGE_SHOWREADME

Set INSTALLER_FINISHPAGE_SHOWREADME to a relative path to show a checkbox for readme/documentationan..

Example: $INSTALLER_FINISHPAGE_SHOWREADME Packages/YourPackageGroup/YourPackage/.../SomeFile.[html/PDF/txt]

INSTALLER_FINISHPAGE_SHOWREADME_NOTCHECKED

Set INSTALLER_FINISHPAGE_SHOWREADME_NOTCHECKED to 1 to uncheck the show readme check box by default.

INSTALLER_FINISHPAGE_SHOWREADME_TEXT

Set INSTALLER_FINISHPAGE_SHOWREADME_TEXT to a string that is the title of the readme checkbox.

IINSTALLER_FINISHPAGE_TEXT

Set INSTALLER_FINISHPAGE_TEXT to a string to overwrite the text of the finish page.

Example: $INSTALLER_FINISHPAGE_TEXT Alternative text...

INSTALLER_FINISHPAGE_TITLE

Set INSTALLER_FINISHPAGE_TITLE to a string to overwrite the title of the finish page.

Example: $INSTALLER_FINISHPAGE_TITLE Your Title

INSTALLER_GENERATE_ZIP

Set INSTALLER_GENERATE_ZIP to 1 if you rather want to create a zip file instead of a self-installing executable.

The files in the zip file will basically have the same layout as with an executable installer, but of course things like installing desktop icons will not happen this way.

INSTALLER_HEADERBMP

Set INSTALLER_HEADERBMP to a path of a bitmap file that is displayed in the installer header.

Example: $INSTALLER_HEADERBMP $(LOCAL)/MyHeader.bmp

INSTALLER_MACX_DSSTORE

INSTALLER_MACX_DSSTORE points to a file used to store custom attributes of the disk image (DMG)'s root folder (.DS_Store).

INSTALLER_MACX_IMAGE

INSTALLER_MACX_IMAGE sets the pdf/png/jpg that is used as background image in the mac installer. Requires INSTALLER_MACX_DSSTORE to be set as well.

INSTALLER_MACX_LICENSE

html,rtf,txt file displayed as license for package (guided) installer. For disk images rtf and txt files are supported. The txt file should not contain line breaks within a paragraph.

INSTALLER_MACX_WELCOME

html,rtf,txt file displayed as welcome for package (guided) installer. Only used if INSTALLER_MACX_BUILDPKG is 1.

INSTALLER_MACX_README

html,rtf,txt file displayed as readme for package (guided) installer. Only used if INSTALLER_MACX_BUILDPKG is 1.

INSTALLER_MACX_CONCLUSION

html,rtf,txt file displayed as conclusion for package (guided) installer. Only used if INSTALLER_MACX_BUILDPKG is 1.

INSTALLER_MACX_BUILDPKG

Builds a package (guided) installer if set to 1. If not set, a disk image will be created.

INSTALLER_WINDOWS_ICON

Set this to the absolute path of a Windows .ico file to change the default icon for the Windows installer executable.

MACX_APPBUNDLE_NAME

Overwrite default application bundle name. Only required if bundle name and product name are different.

MACX_INFO_BUNDLEID

Overwrite the auto-generated bundle-id for the application.

MACX_INFO_APPSTYLE_NATIVE

Set MACX_INFO_APPSTYLE_NATIVE to 1 to use native, Aqua-style GUI for macOS applications.

MACX_SIGN_APPLICATION

Enable creation of a code signature for application & installer if set to 1.

MACX_SIGN_INSTALLER

Enable creation of a code signature for installer if set to 1.

MACX_SIGN_CHECK_IDENTITY_BEFORE_USE

Check the existence of the required certificates before using them (fail without error).

MACX_APPLICATION_SIGN_IDENTITY_NAME

Overwrite default identity name of the certificate used to sign the application.

MACX_INSTALLER_SIGN_IDENTITY_NAME

Overwrite default identity name of the certificate used to sign the installer.

MAKE_ALL_OUTPUT_FILES_WRITEABLE

Set MAKE_ALL_OUTPUT_FILES_WRITEABLE to 1 make all output files writeable (this is needed when working with read-only source files).

PREFSFILE_OPTION[1-10]

Set PREFSFILE_OPTION[1-10] to provide up to 10 variables in the prefs file.

You can use any text in these options, they are copied verbatim and in order into the preferences file of the application.

Example: $PREFSFILE_OPTION1 MLCacheSizeInMB = 1024

Example: $PREFSFILE_OPTION2 OtherOption = OtherValue

PRODUCT

Set PRODUCT to the product name.

PRODUCT_VENDOR

Set PRODUCT_VENDOR to the product vendor name. On Windows this will be, e.g., used in the registry.

The default is "MeVis Medical Solutions AG"

RELEASE

If RELEASE is set to 1, then the release binaries (executables and libraries) are included in the installer. If it is set to 0, then the release binaries are excluded.

SIGN_LICENSE_FILE

SIGN_LICENSE_FILE sets the path to the license file that is used for signing files.

STANDALONE_APPLICATION_ARGS

STANDALONE_APPLICATION_ARGS sets the arguments that are passed to the MeVisLab macro.

Example: $STANDALONE_APPLICATION_ARGS arg1 arg2

STANDALONE_APPNAME

STANDALONE_APPNAME overrides the internal name of the application (default is the value of STANDALONE_MACRONAME), which is used for things like registry entries, preference and license files, etc. .

STANDALONE_AUTO_DETECT_MODULE_DEPENDENCIES

If STANDALONE_AUTO_DETECT_MODULE_DEPENDENCIES is set to 1, then the application macro dependencies are automatically detected.

STANDALONE_CLI_APPLICATION

Set STANDALONE_CLI_APPLICATION to 1 if the application should be run from the command line only. It replaces -runapp by -runappbatch in the application arguments.

STANDALONE_CREATE_PACKAGES_ZIP

Set STANDALONE_CREATE_PACKAGES_ZIP to 1 to enable compressing certain files, *.(py|pyc|script|def|mlab|js|txt), into a Packages.zip next to the Package directory. This is a file I/O optimization, because it will speed up loading the included files.

STANDALONE_EXECUTABLENAME

Set STANDALONE_EXECUTABLENAME to the name you want the starter executable to have (since that will appear, e.g., in process listings). It is recommended that the name does not contain spaces. If not given the default is MeVisLabApp.

This currently only works for Windows and Linux.

STANDALONE_FINISHPAGE

Set STANDALONE_FINISHPAGE to 1 to enable the installer finish page on Windows, which allows to start the application after it was installed and/or to show additional information. See also the INSTALLER_FINISHPAGE_X variables.

STANDALONE_ICON

Set STANDALONE_ICON to the path of an icon file.

STANDALONE_LICENSEKEY

Set STANDALONE_LICENSEKEY to the path of a license file if you want to embed one into the application installer.

STANDALONE_MACRONAME

Set STANDALONE_MACRONAME to the name of the MeVisLab application macro module.

STANDALONE_SPLASHIMAGE

Set STANDALONE_SPLASHIMAGE to the path of an image file to replace the MeVisLab splash image.

STANDALONE_STARTER_ARGS

STANDALONE_STARTER_ARGS contains additional arguments that are passed to the MeVisLab starter.

Call MeVisLabApp -help in Packages/MeVisLab/IDE/bin to get a list of possible arguments. Note that -runapp or -runappbatch are added automatically to the command line arguments (see STANDALONE_CLI_APPLICATION).

VERSION

VERSION defines the product version.

WEB_APPLICATION

Set WEB_APPLICATION to 1 to create a web application installer.

WEB_APPLICATION_INDEX_TEMPLATE

Set WEB_APPLICATION_INDEX_TEMPLATE to the path of a html file that is used instead of the default template.

Chapter 4. Advanced Commands

4.1. runApplicationCommand

In the Commands section of a macro module, the runApplicationCommand tag defines a scripting command that is executed after a module is loaded and before its window is opened.

The runApplicationCommand receives the following arguments: (argumentlist, absolutePath).

When MeVisLab is started with MeVisLab -runApp[Batch] SomeMacro arg1 arg2... it creates the SomeMacro macro and runs the runApplicationCommand with ([arg1, arg2, ...], currentDirectoryAsAbsolutePath) before showing the window of SomeMacro.

In case of starting MeVisLab with -runAppBatch instead of with -runApp, no window will be shown but the runApplicationCommand is executed nevertheless.

[Tip]Tip

Please have a look at the module TestBatchCommand for an example.