Most of Tarma Installer's Setup behavior is determined by the contents of your project, which are stored in the installation database that is included in the distribution package. However, Setup also recognizes a number of command line options that modify its default behavior.
Tarma Installer's Setup program (including all self-extracting executables built with Tarma Installer) uses the following command line syntax. Parts between [brackets] are optional; ellipsis "..." indicate parts that may be repeated.
[path\]Setup.exe [options...] [var=value...] [setup.dat]
| Part | Description |
|---|---|
| [path\]Setup.exe | Specifies the Setup program's file name or fully qualified path. In actual usage, this may be Setup.exe or any other name that you assigned to the Single Exe distribution package on the Build page. |
| options... | Specifies zero or more runtime options. If you do not specify any options, Setup will run according to the rules set out under Run mode options, below. Options may start with / or - and are not case-sensitive. Therefore, -install, /install, and /INSTALL all have the same effect. Options are processed from left to right, so if you specify conflicting options, the rightmost one "wins". |
| var=value... | Specifies zero or more var=value pairs that allow you to set the value of symbolic variables from the command line. Any values set on the command line override the values of the corresponding variables from the installation script. If a variable doesn't exist in the installation script, it is automatically created. Note: If value contains spaces or special characters such as '<' and '>', you should quote the entire option as in "var=value". This allows you to use other symbolic variables as part of the value specification, for example "INSTALLDIR=<ProgramFilesFolder>\<ProductName>". |
| setup.dat | Specifies the name of the installation database, usually Setup.dat. This parameter is optional; if you omit it, Setup looks for Setup.dat in the self-extracting package or the current directory, and terminates with an error if it cannot find that file. Be sure to enclose the path in quotes if it contains spaces. You must also include the .dat extension. |
The Tarma Installer Setup program is a single executable that acts both as installer and uninstaller. Normally, Setup determines automatically in which capacity it should run. However, there may be occasions where you want to deviate from the usual rules, for example to force a registration run in order to repair a damaged installation.
The current run mode is available and may be set through the TsuRunMode variable. However, changing the run mode after Setup has started should be done with great care, or it may lead to unpredictable results.
| Run mode | Description | How selected |
|---|---|---|
| (none) | Initial run mode if no run mode options apply. If Setup is running interactively, the user is prompted to select the desired run mode. In silent mode, the installer fails with exit code 7 (see Exit codes below). Corresponds to TsuRunMode value 0. |
If no other run mode applies, Setup starts in this run mode. |
| Installer | Performs the initial installation or subsequent modification of your application on the customer's computer. Corresponds to TsuRunMode value 1. |
New installations always run as Installer. Also selected if you specify /install on the command line. |
| Registrar | Performs post-boot file registration. This is only required if one or more files were in use during the original installation. In that case, Setup automatically registers itself to run in Registrar mode after the next system reboot. Corresponds to TsuRunMode value 3. |
Selected through the /register command line option, or interactively if no other run modes apply. Note: This run mode does not apply to new installations, which always run as Installer. |
| Repair | Re-installs your application unchanged, usually to repair a damaged installation. Corresponds to TsuRunMode value 4. |
Selected through the /repair command line option, or interactively if no other run modes apply. Note: This run mode does not apply to new installations, which always run as Installer. |
| Resume | Resumes a partially completed installation. This is typically used to resume an installation after the system was restarted due to the installation of one or more prerequisites. Corresponds to TsuRunMode value 5. |
Selected through the /resume command line option. |
| Uninstaller | Completely removes your application from the customer's computer. Corresponds to TsuRunMode value 2. |
Selected through the /remove command line option, or interactively if no other run modes apply. Note: This run mode does not apply to new installations, which always run as Installer. |
Tarma Installer Setup recognizes the following run mode options:
| Option | Description | TsuRunMode |
|---|---|---|
| /install |
Force Installer mode, regardless of other considerations. The second form allows you to specify an installation folder. It is equivalent to /install followed by INSTALLDIR=installfolder (with quotes, if necessary). You can use absolute paths such as C:\MyApp or symbolic variables such as <ProgramFilesFolder>\MyApp for installfolder. Be sure to quote the entire option if installfolder contains spaces or symbolic variables, or Windows will misinterpret the command line. Note: Because you are essentially assigning a new value to the INSTALLDIR folder alias, installfolder should not refer to <INSTALLDIR> either directly or indirectly to avoid infinite recursion. |
1 |
| /register |
Force Registrar mode, regardless of other considerations. Note: This option does not apply to new installations, which always run as Installer. |
3 |
| /remove |
Force Uninstaller mode, regardless of other considerations. Note: This option does not apply to new installations, which always run as Installer. |
2 |
| /repair |
Force Repair mode, regardless of other considerations. Note: This option does not apply to new installations, which always run as Installer. |
4 |
| /resume | For Resume mode, to resume a partially completed installation after a system restart. | 5 |
In addition to one of the run mode options, you can use the following options to further modify Setup's behavior:
| Option | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| /a /an |
Require Administrator rights (equivalent to /a5) This option modifies the Installation level attribute set on the Installer Options project page. The current installation level is available through the TsuInstallLevel variable. The level n can be one of the following:
|
||||||||||||||||||||||||||||||||||||||||||||||||
| /bn |
Set reboot mode n. This option determines how Setup handles system restarts at the end of the installation or removal process. The current reboot mode is available and may be set through the TsuRebootMode variable. The available levels are:
|
||||||||||||||||||||||||||||||||||||||||||||||||
| /cn |
Set integrity checking mode n. This option determines how Setup checks the integrity of the installation package at the start of the installation. The available levels are:
|
||||||||||||||||||||||||||||||||||||||||||||||||
| /emask |
Set the error mask to mask. The error mask determines which runtime errors will terminate the installation. The initial mask is set on the Installer Options project page; the /e option adds another mask to this. The effective error mask is initial_mask & mask, where '&' represents the binary 'and' operation. To enable specific error types, set mask to the combination of the error values shown below. If you leave out an error type, it is ignored by the installer. To make the installer ignore all runtime errors, specify /e0. This is not recommended, because it may leave the product partially installed or partially uninstalled. However, in emergencies it may help to install or remove the product. Note: Even if you include an error type in the /e option, it will only terminate the installation if it's also enabled on the Installer Options project page. In other words: you can only remove error types, not add them. You may specify mask in decimal or hexadecimal; in the latter case, you must prefix it with 0x. For example, /e255 and /e0xFF are equivalent.
|
||||||||||||||||||||||||||||||||||||||||||||||||
| /l |
Show all valid locale languages in a multilingual installer, even if they don't use the current ANSI code page. This might result in some text being replaced by ??? characters or mapped to the wrong glyphs. Note: This option applies to the ANSI versions of Setup.exe only; Unicode versions always show all valid locale languages. See Setup stubs for an explanation of the various available Setup.exe variations. |
||||||||||||||||||||||||||||||||||||||||||||||||
| /l0 /l1 |
Clean up log file after installation or removal These two options override the Log file mode option on the Installer Options project page and force an unconditional clean up or preservation of the installer's log file. If you specify the /l1 option (always keep log file), then the log file will appear in the location implied by the Log file mode option on the Installer Options project page; see Setup log file below for details. |
||||||||||||||||||||||||||||||||||||||||||||||||
| /p:password | Use password as the password for password-protected Setup packages. This password must match the one that was specified in the Password field of the Build configuration when the Setup package was built. | ||||||||||||||||||||||||||||||||||||||||||||||||
| /q /qn |
Perform a silent (quiet, unattended) installation. During silent installations, the normal Setup wizard is suppressed and the entire installation, registration, or uninstallation process is performed without user intervention. This feature is intended for unattended installations and removals. The second form allows you to specify a silence level n as follows:
Note - In silent installation mode you cannot specify user registration information for use on the Setup - Registration Information page. Only default user registration, if you specified any on the Advanced project page, takes place in silent installation mode. For multilingual installers running in silent mode, Setup always installs the default language version. In practice, this means that installation takes place in the locale of the installing user account, which is usually what is desired. See the Languages option in the build configuration documentation for the details of this selection process. The current silence level is available and may be set through the TsuQuiet variable. |
||||||||||||||||||||||||||||||||||||||||||||||||
| /s:sourcedir | Specify the path to the folder that contains the uncompressed installation source files, i.e., the files that are distributed as plain files instead of as part of the compressed installation archive. The actual files may be stored in the sourcedir folder itself or in one of its subfolders. This option assigns a new value to the <SourceDir> variable. For new installations, this variable is set automatically to the folder that contains the original distribution package; existing installations reuse the most recently used path, unless you override it with this command line option. |
||||||||||||||||||||||||||||||||||||||||||||||||
| /u /un |
Uninstall/upgrade mode. Indicates that the uninstaller is running as part of an upgrade. In other run modes, this option sets the TsuUpgrade variable, but is otherwise ignored. /u sets TsuUpgrade to 1; /un sets TsuUpgrade to n. In Uninstaller mode, it tells Setup to uninstall as part of an upgrade. In that case, Setup performs the uninstallation as per normal, except that in-use files are not queued for delayed removal on the next Windows restart. This prevents problems during upgrades, when delayed file removal by Windows could accidentally remove the new version of a file. The current upgrade level is available through the the TsuUpgrade variable. |
||||||||||||||||||||||||||||||||||||||||||||||||
| /x | Clean up a failed installation. This option is obsolete and only retained for compatibility with Tarma Installer 2.x, but is ignored by Setup.exe. In Tarma Installer 5.x, rollback always takes place automatically after a failed installation. | ||||||||||||||||||||||||||||||||||||||||||||||||
| /z:tizpath | Specify the path to the TIZ archive, i.e., the file that contains the compressed distribution files. This is an advanced option and should not normally be used. |
Tarma Installer's Setup program returns an exit code that indicates the result of its actions. This result code is mainly useful if you use Setup in silent installation mode in a batch file, where it can be tested through the %ERRORLEVEL% variable (Windows NT4 and later only) or by using an IF ERRORLEVEL statement. The following exit codes are currently defined.
| Exit code | Description |
|---|---|
| -1 | Internal error (anything < 0) |
| 0 | Success |
| 1 | Invalid license code or evaluation period expired |
| 2 | Initialization error |
| 3 | Invalid or missing setup database |
| 4 | Error while saving the setup database |
| 5 | Installation cancelled |
| 6 | Other installation failure |
| 7 | Invalid run mode |
| 8 | Error while creating the user interface |
| 9 | Invalid command line option |
| 10 | Administrator rights required |
| 11 | Target system requirements not met |
| 12 | Reboot required |
| 13 | Application is currently running |
| 14 | Previous version detected |
| 15 | Incorrect or missing password |
| 16 | Insufficient disk space |
| 17 | Insufficient access rights |
| 18 | Extension DLL returned error |
| 19 | Error while running installer actions |
| The following exit codes are generated by the pre-Setup loader stub: | |
| 251 | WaitForProcess() failed while waiting for Setup.exe to terminate |
| 252 | CreateProcess() failed: could not start Setup.exe |
| 253 | ANSI installer required, but not included in the package |
| 254 | Invalid loader stub |
| 255 | General function failure |
If you run Setup from a batch file or command line prompt, the default Windows behavior is to continue with the next command as soon as Setup is started; it does not wait until Setup has finished. As a result, the value of %ERRORLEVEL% does not necessarily reflect Setup's exit code.
To remedy this, run Setup as follows:
start /wait Setup.exe other_options...
This ensures that the command does not return until Setup has exited.
[Windows NT/2000/XP/2003/Vista] If the Setup.exe program path in the start command contains spaces, you must quote it. However, the start command on Windows NT/2000/XP/2003/Vista interprets the first quoted string as the program title and not as a program path. Therefore, you should include a dummy, quoted program title prior to the actual program path, thus:
start /wait "title" "setup_path" other_options...
This is only necessary if you quote setup_path for some reason.
Note that this tip only applies to the Cmd.exe command interpreter used on Windows NT/2000/XP/Vista systems; the Command.com command interpreter on Windows 9x systems does not support a title option and therefore requires no workaround.
After installation, the Tarma Setup.exe installation program and its auxiliary files are installed on the target system in one of the following locations, depending on the target system version. For non-English versions of Windows, some of the folder names may be localized.
The above locations are used for All Users or Administrator level installations. If the installation was performed as a Current User installation, then the locations become:
Note that the Windows 9x location is unchanged, because those systems lack any effective security options and all installations are performed at the Administrator level.
Additional information about the Setup process is written to the diagnostic log file. The installer's log file is initially written to the Temp folder of the installing user, which is usually one of the following (or their localized equivalents):
Please note that some of these folders are hidden by default in Windows Explorer; you might have to change the Windows Explorer folder settings to "Show hidden files and folders" in order to see the applicable Temp folder.
The initial name of the installation log file is is PackageName-xxxx.log (with PackageName the name of your installation package and xxxx a hexadecimal number) during a new installation; it is Setup.log during subsequent Change, Modify or Repair runs, and during uninstallation.
If you select Move to TinProductFolder or Move to custom path in the Log file mode field on the Installer Options project page, then the log file is renamed and moved to either <TinProductFolder> or to the path you specify in the Log file path field. This occurs at the very end of the installation process, immediately before the Setup.exe process terminates. Any log files thus moved are automatically deleted when your product is uninstalled.
Note: Log files created during uninstallation of your product are never moved; they either stay in the Temp folder or are removed (if you specify Clean up if successful in the Log file mode field). This happens because the uninstaller removes all product folders, so there is no place left for the log file to go.