The Tarma Installer Setup program is a single executable that performs three distinct functions:
Installer - To perform the initial installation of your application on the customer's computer.
Registrar - To perform post-boot file registration. This is only required if one or more files were in use during the original installation.
Uninstaller - To remove your application from the customer's computer.
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. Furthermore, Setup also supports silent installations (without user interaction); these require a special command line option to enable.
Unless you indicate otherwise by specifying one or more command line options (see below), Tarma Installer's Setup program selects its operating mode based on the following rules:
These rules are sufficient for most common situations. Among other things, they allow the customer to simply start a new Setup package in order to install it, and to start an existing Setup program in order to remove it.
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.
Setup.exe [options...] [var=value...] [setup.ini]
| Item | Description |
|---|---|
| Setup.exe | Specifies the Setup program's file name. 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... |
[2.75 and later] 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 "AppFolder=<ProgramFiles>\<AppTitle>". |
| setup.ini | Specifies the name of the installation script, usually Setup.ini. This parameter is optional; if you omit it, Setup looks for Setup.ini 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 .ini extension. |
Tarma Installer Setup recognizes the following run mode options:
| Option | Description |
|---|---|
| /install /install:installfolder |
Force Installer mode, regardless of other considerations. The second form allows you to specify an installation folder, which overrides the default installation folder that you specified on the Installation project page. It is equivalent to /install followed by AppFolder=installfolder (with quotes, if necessary). You can use absolute paths such as C:\MyApp or project variables such as <ProgramFiles>\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 <AppFolder> variable, installfolder should not refer to <AppFolder> either directly or indirectly. |
| /register | Force Registrar mode. Since this mode is never chosen automatically, specifying this option is the only way to run Setup in Registrar mode. |
| /remove | Force Uninstaller mode, regardless of other considerations. |
In addition to one of the run mode options, you can use the following options to further modify Setup's behavior:
| Option | Description |
|---|---|
| /bn |
[2.36 and later] Set reboot level 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 (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. |
| /l | [2.99] 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 garbled or replaced by ??? characters. |
| /p:password | [2.50 and later] 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 |
[2.30 and later] 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. |
| /u /un /un:key |
[2.41 and later, Pro] Uninstall/upgrade mode. The interpretation of this option depends on the Setup run mode: In Installer mode, this option is similar to the Previous version uninstaller key option on the Installation project page and determines if Setup should detect and handle previous versions of your application during installation of the new version. 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. In Installer mode, the /u option requires an upgrade level n and allows an optional :key specification. In Uninstaller mode, anything beyond /u is ignored. The following Installer upgrade levels are currently defined: /u0 - Fail the installation if a previous version is detected. /u1 - Uninstall the previous version if possible, else fail the installation. This is also the behavior if you omit the /u option altogether, but did check the Previous version uninstaller key project option. /u2 -Uninstall the previous version if possible, else install the new version anyway. Use this option with caution; it might overwrite the previous version and prevent a clean uninstallation later on. See After uninstallation, some files are not removed. Why not? and After uninstallation, some (empty) folders are not removed. Why not? in the Knowledge Base for possible side-effects of this option. /u3 - Install the new version without checking for a previous version. This option in effect suppresses the Previous version uninstaller key project option. The same caveats as mentioned under /u2 apply here. Note - The /u option is primarily intended for use in silent installation and uninstallation modes (i.e., in combination with /q). However, you can also use this option in interactive mode: In interactive Installer mode, upgrade levels n <= 2 always query the customer for permission to uninstall the previous version, failing the installation if permission is denied. This is similar to checking the Previous version uninstaller key project option on the Installation page. Using /u3 in interactive mode has the same effect as using it in silent mode: it suppresses the Previous version uninstaller key project option and installs the new version without further ado. In interactive Uninstaller mode, /u suppresses delayed file removals as documented above. With options /u1 and /u2, uninstallation is considered possible if the uninstaller of the previous version is Tarma Installer's Setup. In that case, the previous version's uninstaller is automatically run in silent upgrade mode (/q /u) to avoid user interaction and inadvertent delayed file removal. If the previous version's uninstaller is from a third party, no uninstallation is attempted because it might involve user interaction, which is undesirable if the current installation is running in silent mode. The optional :key specification (with a leading colon) allows you to specify the uninstaller key for the previous version; Setup checks this key to detect the presence of a previous version. If you omit key, Setup uses the value of the <UninstallPrev> project variable that you entered in the Previous version uninstaller key field on the Installation page. See Uninstaller information for more information about the use of uninstaller keys in Windows. With the /u3 option, the key specification is allowed but ignored. Tip - You may use project variables in the key specification. If you do, be sure to enclose the entire option in quotes or Windows will misinterpret the command line. Also, because you are in effect assigning a new value to the <UninstallPrev> project variable, key should not refer to <UninstallPrev> either directly or indirectly. |
| /x | [2.36 and later] Clean up a failed installation. This option only applies to Installer runs; it is ignored otherwise. If this option is given a failed installation will be cleaned up regardless of the customer's choice on the Setup - Installation cancelled page during interactive installations. During silent installations, this ensures that a failed installation is immediately removed (the log file will be retained, though). |
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 NT only) or by using an IF ERRORLEVEL statement. The following exit codes are currently defined.
| Code | Meaning | Notes |
|---|---|---|
| -1 | Internal error | **** |
| 0 | Success | |
| 1 | Invalid license code | * |
| 2 | Initialization error | * |
| 3 | Invalid or missing setup script | * |
| 4 | Error while saving the setup script | *** |
| 5 | Installation aborted due to error | ** |
| 6 | Installation prematurely terminated | ** |
| 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 | Password required | * |
Notes
* Indicates an error condition before the installation process proper has started. In that case, no changes have been made to the customer's system yet and no cleanup is necessary.
** Indicates an error condition during the installation process. Cleanup is required in order to restore the customer's system to its previous state. The /x command line option will initiate the required cleanup.
*** This error condition occurs after what is essentially a successful installation. However, failure to save the Setup script leaves the application unremovable. This should rarely, if ever, occur.
**** This error code is a special case; it is basically a last-ditch indication that an exception was caught at a point from where no resumption was possible. In theory, this should never happen at all; in practice, it's unpredictable but hopefully exceptionally rare (pun intended).
# Indicates that the installation or removal was successful, but that a system restart is required or under way to complete it.
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] 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 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/2003 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 same name as the Setup program, but a .log file name extension.