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.
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. |
| 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. |
| 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'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 above. 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 project 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 project 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. |
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 project variables such as <ProgramFilesFolder>\MyApp for installfolder. Be sure to quote the entire option if installfolder contains spaces or project 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 |
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 level n can be one of the following:
The current installation level is available through the TsuInstallLevel variable. |
|||||||||||||||||||||||||||||||||||||||||||||
| /bn |
Set reboot mode n. This option determines how Setup handles system restarts at the end of the installation or removal process. The available levels are: /b0 - Never reboot. This is particularly useful to prevent undesired system restarts during unattended installation or removal. Depending on the circumstances, a subsequent reboot might be required to complete the installation or removal process. This is indicated by an exit code of 12 (Reboot required; see Exit codes below). /b1 - Reboot as needed. This is the default behavior and causes Setup to reboot automatically if required. In interactive mode, the customer can still prevent the reboot by indicating as much on the Setup - Installation Completed page. /b2 - Always reboot. This causes Setup to reboot at the end of the installation or removal process without further ado. Use this option with caution. The current reboot mode is available and may be set through the TsuRebootMode variable. |
|||||||||||||||||||||||||||||||||||||||||||||
| /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: /c0 - Do not check. No integrity check is performed. /c1 - Minimal check. (Not currently implemented; behaves as /c2 at the moment.) /c2 - Full integrity check. Calculates a checksum on the entire package and compares that with the checksum that was stored in the package when it was built. If the check fails, the installer will exit with error code 3 (Invalid or missing setup database; see Exit codes below). |
|||||||||||||||||||||||||||||||||||||||||||||
| /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. |
|||||||||||||||||||||||||||||||||||||||||||||
| /l0 /l1 |
Clean up log file after installation or removal These two options override the Clean up log option on the Installer Options project page and force an unconditional clean up or preservation of the installer's log file. If neither option is specified, the installer cleans up its log file after a successful installation or removal, or keeps it if there was a failure. |
|||||||||||||||||||||||||||||||||||||||||||||
| /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 on the Build page 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: /q0 - Not a silent install; the normal Setup wizard is shown after all. This option is mostly useful if you generate the Setup command line programmatically. /q1 - Silent install; equivalent to /q. /q2 - Invisible install. In this mode, the entire installation, registration, or uninstallation process is performed without user intervention and with a completely hidden user interface. (The Setup process will still appear in the Windows Task Manager's list of running processes, though.) 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, 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 Multilingual Setup in the online help for the details of this selection process. The current silence level is available and may be set through the TsuQuiet variable. |
|||||||||||||||||||||||||||||||||||||||||||||
| /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 ExpertInstall, rollback always takes place automatically after a failed installation. |
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 |
Tip 1 - 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.
Tip 2 - [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.
Additional information about the Setup process is written to the diagnostic log file. This file is stored in the TEMP folder of the user who started the Setup program, and has the following name: