Installer

• Installer
• Uninstaller
• Callback DLLs

Installer

There are two possible ways of installation:

• GUI wizard – following on-line prompts and specifying setup parameters.

  There are several installation process dialogs:

  1. "Welcome" dialog, where the package name is displayed;
  2. License Agreement dialog;
  3. Installation type selection dialog (Personal or Common) — only on Windows NT family and if the user has administrator’s privileges;
  4. Destination folder selection dialog;
  5. Program folder selection dialog;
  6. Desktop and Start Menu shortcuts creation dialog;
  7. Settings review dialog;
  8. File copy progress indicator with splash;
  9. "Installation completed" dialog.

  Some of these dialogs may be skipped if respective installer options were not set.

• Automatic installation — in this mode a package can be installed without user interaction. This is useful for a quick product installation to multiple machines, for testing the installer package in different environments, etc.

  To launch an installation in such unattended mode, specify the /batch option to the installer executable. Other command-line options specify installation settings, such as destination folder, etc. The installation process then runs on its own, no user input is required.

  The following command-line options are recognized:

  /personal /common - these two options specify the type of installation: “for the current user only” and “for all users”, respectively.

  /dest "full-path" - defines the destination folder pathname. If it is not specified, the application will be installed into the default folder. The default folder value could be specified with Packager (see Installation directory.)

  /folder "My Product" - defines the name of the program folder to put shortcuts to. If it is not specified, the default folder name is used.

  /primary "full-path" - defines the path to the installation being updated. This option makes sense only for update packages. If it is not specified, the setup will seek the Registry for proper path. If the search fails, the setup will exit with the error code 1.

  /user "SuperUser" - defines a user account under which the Windows service(s) from the installation will run. This option, if specified, should be accompanied with the "/password" option to let the service start automatically after installation. It is applicable only for packages that install Windows services.

  /password "Password@123" - defines a password for the specified user account. This makes sense only for packages that install Windows services.

  /no-reg - disables shortcuts creation and Registry modification.

  /force - forces the setup to override an already installed package instance. If it is not specified and if another instance is detected, the setup will not proceed.

  /no-aftrun - suppresses post-installation runnable invocation.

  /? - shows a brief help page.

  Note: Both - and / are recognized as option starting characters, so /no-aftrun is equal to -no-aftrun.

If a project contains a post-installation runnable, they are invoked in the following order:

• the splash dialog is displayed; application files are copied to the destination location;
• the final dialog is displayed;
• the installation exits, the post-installation runnable is invoked.

For the functions above, the return value of integer type means: zero — no error, installation may proceed, any non-zero value — there is an error, installation must be aborted.

Uninstaller

An Excelsior Installer package may include an uninstaller executable, which removes installed package files , shortcuts and registry keys on user request. If the user runs the executable, e.g. via the shortcut placed in Program Folder of Start Menu, GUI uninstallation wizard appears.

The uninstallation acts as follows:

• the confirmation dialog is displayed;
• if the project contains an uninstallation callback DLL, the
   int __stdcall PreUninstall (void);
  function is invoked; its return value means: ’0’ - no error, uninstallation may proceed, ’non-zero’ - an error occurred, uninstallation must be aborted.
• files, shortcuts and registry keys are deleted;
• the final dialog is displayed.

To perform uninstallation in the unattended mode, the user should specify the /batch option on the command line of the uninstaller executable.

Uninstallation is cumulative, that is, it removes the initially installed package along with all updates that were possibly installed later.

Callback DLLs

The install callback DLL should export the two functions:

 int __stdcall PreInstall (char* installation_folder_name)  int __stdcall PostInstall (char* installation_folder_name)

where the installation_folder_name parameter is the absolute pathname of the installation directory. The uninstall callback DLL should export the function

 int __stdcall PreUninstall (void)

Return value of the functions is a return code. If they return a non-zero value, the (un)installation process will be terminated and a dialog displaying the respective message and the return code, will appear. The installer/uninstaller invokes the functions in the order described in sections Installer and Uninstaller.

Though the declarations are given in the notation of the C language, you can create the DLLs using another programming language provided that it has equivalent types and its implementation supports the __stdcall calling convention.

Note: when building the DLLs, enable the static linking mode so that they do not depend on any other DLLs except those implementing the system API.