Package

A Package defines the parameters for an InstallMate installation package. Among other things, it allows you to specify the name for the package, the language, and the product icon for use in the package. (The actual contents of the installer are determined by the other project pages.)

Attributes

The following attributes and options are available.

Attribute Description
Package name

Enter the internal name for the package. This is also the name of the folder in which the installer package will be created; its full path is <ProjectFolder>\<ProjectName>\Package name, which is available as <BuildFolder> in build actions. The value of the Package name field itself is available as <BuildName>.

Notes

  • You can change this path through the Build folder option in the Build - Advanced dialog box.
  • If you select Per language for the Languages attribute (below), then the configuration name is modified internally during the build process. Each language's installation package is stored in a separate folder called Package name-langID, where langID is the 4-digit hexadecimal language identifier for the build language. The <BuildFolder> and <BuildName> variables reflect this.
Installer name

Enter the external name of the installation package file, with an .exe extension. The installer will be created as <ProjectFolder>\<ProjectName>\Package name\Installer name and its full path is available as <BuildTarget> in build actions.

Note: If you change the build output path through the Build folder option in the Build - Advanced dialog box, then the installation package's location will change accordingly.

Installer type

Select the desired installer type from the drop-down list. The following choices are available:

Installer type Description
Combined 32/64-bit Installer is compatible with all Windows versions from Windows XP onwards, both 32-bit and 64-bit. This is the default option.
x64 Windows only

Installer is a pure x64 executable that will run on all x64 Windows editions. This option is mostly useful if your product must be installed on 64-bit Windows versions that do not have a 32-bit compatibility layer, for example the x64 Windows Preinstallation Environment (WinPE).

Note: This type of installer does not run on IA64-based Windows editions. Use the Combined 32/64-bit option if your product must be installed on those platforms.

For details about the different installer versions, see Setup stubs.

Languages

Select the desired language build mode from the drop-down list. The following choices are available:

Languages Description
Default only Builds the package only for the default project language as defined on the Languages project page.
Per language Builds separate packages for each of the project languages defined on the Languages project page or a subset thereof. To specify a subset, click ... to open the Select Installation Languages dialog box.
Multilingual Builds a single package that contains all of the project languages defined on the Languages project page or a subset thereof. To specify a subset, click ... to open the Select Installation Languages dialog box. When the installation package is run, a dialog box is displayed that allows the user to select the desired installation language. If the installer is running in Quiet mode, no dialog box is displayed and this option behaves as Multilingual, auto.
Multilingual, auto Same as Multilingual, except that no dialog box is displayed during installation. Instead, the installer automatically selects the installation language based on the user's system language.

If you select Per language, each installation package is stored in a separate folder; see Config name above for details.

Regardless of the language build mode, an installation package will only contain the project contents that are relevant for the package's language. This affects the following:

  • If a component is marked for one or more languages, that component and the objects that it contains are only included in the package if the build languages are among the component's languages. (Components that are marked Install for all languages are always included.)
  • For any localizable attributes and localized messages , only the translations for the build languages are included in the package.
  • Dialog box translations are included only for the build languages.

For the Multilingual and Multilingual, auto options the installer performs runtime filtering of the available languages, as follows:

  1. Any languages that are not installed on the target system are suppressed. This ensures that only languages whose fonts, code pages, and keyboard mappings are present on the target system are available for selection.
  2. For ANSI-based installers only (see Setup stub, below), any languages that do not use the current ANSI code page are also suppressed. You can override this by specifying the /l Setup command line option, but this is not recommended because it may render large parts of the user interface text unreadable: any characters outside the current ANSI code page will appear as ? and other characters may be mapped to the wrong glyphs.

For the Multilingual, auto option, and for the Multilingual option when the installer runs in Quiet mode, the installer then determines the "best fit" language, using the following rules:

  1. If the user's system language is among the available installation languages, it is selected. For example, if the user's system language is set to French (France) and this is one of the available installation languages, it is selected.
  2. Else if the user's primary language ID matches the primary language ID of one of the available installation languages, it is selected. For example, if the user's system language is set to French (Canada) but only French (France) is available among the installation languages, the latter is selected. If there are multiple primary language ID matches, the first one is selected.
  3. Else if there is a default language (as set on the Languages project page), it is selected.
  4. Else the first available language is selected.

The language selection only takes place during installation; any subsequent runs of the same installer, for example as uninstaller, use the language that was selected during installation.

Packaging

Select the desired installer packaging from the drop-down list. The following choices are available:

Packaging Description
Compressed .exe The installer consists of a single self-extracting executable that contains all distribution files in compressed format. This is usually the most convenient distribution format.
Plain file tree The installer consists of an executable with the Setup stubs and installation database, plus a separate files and folders tree that contains the installation files in plain (i.e., uncompressed) format. This format is suitable for use on CD-ROMs and similar media if you want the files to be accessible before installation.
Loader + Archive The installer consists of an executable with the Setup stubs and installation database, plus a separate compressed archive with all installation files. The compressed archive may be split into multiple parts if you specify the Disk spanning option in the Build - Advanced dialog (accessible through the Advanced... button).
Loader + Download The installer consists of an executable with the Setup stubs and installation database, plus a number of separate compressed archives with all installation files. The compressed archives are meant to be downloaded from your server during installation; the Download URL field (see above) determines from where the installer will download the archives. There will be one download archive for each component, plus optionally another one for installation files that are not controlled by a component.

The Packaging option defines the overall default for the package. You can override the default packaging options as follows:

  • For individual installation files to include most files in compressed format, except for a few key files that you want to be accessible in uncompressed form (or vice versa).
  • At the component level to determine which components will be downloaded during installation and which will be included in the main installation package.

See Installer packaging for more information about the possible packaging combinations. The Build output files topic describes the layout of the plain file tree and the other parts of the installation package.

Add MSI wrapper

Check this box to wrap the .exe installer in a Windows Installer (MSI) database package suitable for use in MSI-centric environments.

If this box is checked, the .exe installer is built normally and is then placed inside a special MSI database. The resulting MSI package can be used as a regular MSI installation package (including both interactive and non-interactive installations), but will internally run the InstallMate .exe installer. The uninstaller will be the normal InstallMate uninstaller.

Notes

  • The resulting MSI package is approximately 150-170 KB larger than the .exe installer itself, due to the overhead of the MSI database.
  • Both the .exe and the .msi version of the installer are placed in the build output folder (see Build output files). However, you only have to distribute one or the other, depending on your needs.
  • If you specify a Packaging option other than Compressed .exe (see above), then the MSI package will only contain the initial InstallMate loader. Any additional files (download or otherwise) must be distributed in the normal way and will be used by the embedded InstallMate installer when the MSI package is being installed.
  • If you also specify the Disk spanning option in the Build - Advanced dialog box, then the additional size of the MSI package is taken into account for the first disk. This may result in some slack space if you place the .exe installer instead of the .msi package on the first disk.
  • If you also specify Sign after build (see above), then the installer will be signed twice: first the InstallMate .exe package, then the Windows Installer .msi package. This is intended and correct behavior to ensure that Windows sees signed installers at all stages of the installation process. Note: The MSI wrapper will always be signed with a SHA-1 digest, even if you selected SHA-256 for the main .exe package. This is done because the MSI format does not support SHA-256 signatures. For more information, see Concerns with MSIs on the Microsoft web site.

You can use the following MSI properties on the MSI command line to pass installation options to the embedded .exe installer.

Property Description
INSTALLDIR Passed on to the .exe installer's INSTALLDIR variable. This allows you to preset the main installation folder for the embedded .exe installer.
EXEOPTIONS Passed on verbatim to the .exe installer's command line. This allows you to pass arbitrary setup options to the embedded .exe installer.

Note that these property names must be specified in UPPERCASE as per MSI requirements (only uppercase property names are 'public' properties in MSI packages and therefore modifiable from the command line). For example:

msiexec /I myname.msi INSTALLDIR="C:\Program Files\MyPath" EXEOPTIONS="/b0 /e0 MyVar=2"

This would then pass the following command line to the embedded .exe installer:

\temp\path\to\embedded.exe INSTALLDIR="C:\Program Files\MyPath" /b0 /e0 MyVar=2
Download URL

Specify the URL to the download directory on your Internet server that will host the download files produced for the installer. This field is only used if you specified a download packaging option for the package or one or more components.

The download URL must contain the protocol specifier; InstallMate supports the HTTP, HTTPS, FTP, and FILE protocols (see the description of the Download File action for details).

Note: It is your own responsibility to ensure that any download files are present in the indicated location on your server. This means that you must upload all files from the Downloads folder (see Build output files) to the correct server location. Moreover, this must be done each time that you build the installer, because each build is assigned a unique package code and the installer will not accept download files from a different package, even if the contents would be identical.

We recommended that you create a separate directory for each installer on your server, because the filenames of the download packages are not unique across projects. For example, the main download archive is always called _TinMain.tiz and the per-component download archives use the name of the respective components, which are not necessarily unique either.

Default args

Enter the default command line arguments for the installer. Any arguments that you enter here are stored in the installation package and will be used as if they were command line arguments when the installation package is started.

During installation, the installer parses its command line arguments in the following order:

  1. Anything that you enter in Default args;
  2. Any piggy-backed command line arguments;
  3. Any arguments entered on the actual command line that started the installer.

Because of the way the installer processes its command line arguments, later arguments may override earlier ones. As a result, the Default args may be overridden by the piggy-backed arguments, and they both may be overridden by arguments on the actual command line. This enables you, for example, to configure the installer for silent mode by default (by setting Default args to /q), but still allow the user to run it interactively by specifying /q0 on the command line.

Notes

  • You must use "quotes" in the Default args field just as you would on a normal command line to enclose arguments that contain spaces. Unquoted spaces are used as separators between arguments.
  • If the Default args field contains symbolic references such as <ProgramFilesFolder>, then you must enclose them in `backticks` to prevent expansion at build time. For example, this:
    /q "INSTALLDIR=<ProgramFilesFolder>\MyApp"

    ...will be expanded when the installer is built, which is probably not what you intend because it resolves <ProgramFilesFolder> on your own development system instead of on the target system. Instead, use extra `backticks` like so:

    /q "INSTALLDIR=`<ProgramFilesFolder>\MyApp`"

    This will pass the string <ProgramFilesFolder>\MyApp literally to the installer, which in turn will resolve it at installation time as intended. (Obviously, if you have any symbolic references that must be resolved at build time such as build-time variables like <BuildDate>, then you should not use the backticks.)

  • The Default args and piggy-backed command line arguments are only present in the installation package and are used when the original installation package starts. During subsequent Modify or Repair runs or the removal of your product, they are not present and not used.
Password

Check this box to protect the installation package with a password, and either enter the desired password or click Generate to generate a pseudo-random password. If the installer is protected with a password, the entire package except for the Setup.exe program itself is encrypted and can only be opened after the correct password is entered during installation.

Notes

  • The password protects the installation of your product (including subsequent Modify or Repair runs), but not the removal. Anyone with access to the target system can run the uninstaller.
  • If you select the Packaging: Plain file tree option, then only the package consisting of the installer and its database (and any files explicitly included in the compressed archive) is protected by the password. Any files that are distributed uncompressed in the file and folders tree are accessible without special means.
Generate Click this button to generate a pseudo-random password for the installation package. This opens the Generate password dialog box that allows you to specify the strength of the password. The resulting password uses the uppercase letters A-Z (except for I and O to avoid confusion with the digits 0 and 1), plus the digits 2-9.
Mask password entry Check this box to mask password entry in the installer; clear it to allow the user (and any bystanders) to see the password as it's being typed.
Custom icon

Check this box to use a custom icon as the product icon for the installation package; clear it to use the default Tarma icon. If you check this box, you can select the desired icon file by clicking on ... (browse). To revert to the default icon, click X.

The custom or default icon is used for the installation package. It will also be used for the uninstaller icon when your product is registered for the Add/Remove Programs control panel applet, unless you specify a custom uninstaller icon through the Uninstaller icon option on the Installer options page.

Build variables

Enter a list of variables to set when the configuration is being built. The list must consist of name=value pairs that are separated by semicolons, for example IncludeMe=1;IncludeYou=0. You can use build variables to embed configuration-specific variable values anywhere in the installer, or to use as part of build conditions in components.

The variables are set just before the configuration is built and removed immediately afterwards. Some important notes about the build variables:

  • If the name portion refers to an existing symbolic variable, that variable's value is replaced temporarily; it is restored once the configuration is built. Existing read-only variables are left unchanged.
  • If the name portion does not refer to an existing variable, a new variable is created for the duration of the configuration's build process and is removed afterwards.
  • The value portion is used to set the Value attribute of the symbolic variable; you cannot set the Value (NT) or the Value (x64) attributes here.
  • The value portion cannot be localized and will remove any localization in the name variable for the duration of the build.
  • By default, newly created build variables are saved in the installer's database. If this is not desired, you must explicitly create the name variable on the Variables project page and set or clear its Include in installer attribute as required.

Except as noted above, build variables behave as regular variables for the duration of the build process and in the installer. Among other things, this means that:

Build manifest

Select the desired build manifest type from the drop-down list.

The build manifest contains a detailed list of all source files that were included in the installation package; it can be used as part of an audit trail for your product's release.

The following choices are available:

Option Description
None Do not generate any build manifest.
Packing list

Generate a plain text listing of all source files that are included in the installation package.

If generated, the packing list is stored as <ProjectFolder>\<ProjectName>\<BuildName>(<ProductVersion>)-PackList.txt, i.e., with the name of the package (modified for per-language packages, if necessary) and its product version.

You can change this path through the Packing list path option in the Build - Advanced dialog box.

XML manifest

Generate an XML file listing of all source files that are included in the installation package.

If generated, the build manifest is stored as <ProjectFolder>\<ProjectName>\<BuildName>(<ProductVersion>)-Manifest.xml, i.e., with the name of the package (modified for per-language packages, if necessary) and its product version.

You can change this path through the Manifest path option in the Build - Advanced dialog box.

Packing list +
XML manifest
Generate both manifest types.
Build report

Select the desired build contents report format from the drop-down list.

The build contents report contains a per-folder overview of the files and shell links that will be installed by the installation package, along with details about the installation settings of each item and source file information where appropriate.

If generated, the build report is stored as <ProjectFolder>\<ProjectName>\<BuildName>(<ProductVersion>)-Contents.rtf, i.e., with the name of the package (modified for per-language packages, if necessary) and its product version.

Note: The file extension of the path will automatically be set to the one appropriate for the report format: .txt, .rtf, or .htm You should just put a placeholder extension at the end of the path as in the default .rtf path above.

You can change this path through the Build report path option in the Build - Advanced dialog box.

The following report formats are available:

Format Description
None Do not generate a build contents report.
Plain text

Generate a plain text build contents report in a markdown-like format.

Rich text

Generate a rich text (formatted) build contents report.

HTML

Generate an HTML (formatted) build contents report.

Treat warnings
as errors

Check this box to treat any preflight warning messages as errors; clear it to treat them as mere warnings. If you check this option, any preflight warnings will terminate the build process; this will be flagged by an additional BLD:E0005 or BLD:E0122 message.

Because preflight warnings indicate issues that might cause the installation to fail, you should attempt to build your installers without preflight warnings. This option helps you to enforce that policy.

Sign after build

Check this box to attach a digital signature (Authenticode) to the installation package; clear it to create an unsigned package. Using this option involves two prerequisites:

  1. You must obtain and configure the Microsoft SignCode or SignTool program in the Preferences - SignCode dialog box. You can open that dialog box by choosing Edit > Preferences from the main menu.
  2. You also need a Software Publishing Certificate (SPC), which you can create yourself using Microsoft's MakeCert tool or obtain from a Certificate Authority (CA) such as Verisign or Thawte. Certificates issued by a certificate authority have the advantage that they are countersigned by a trusted third-party, which allows the recipients of your installation package to verify your identity if they check the signature.

See Digital Signatures for background information about SignCode and digital signatures.

Note: If you select the Packaging: Plain file tree option, then only the package consisting of the installer and its database (and any files explicitly included in the compressed archive) is signed. Any files that are distributed uncompressed in the file and folders tree are excluded from the signature.

Advanced...

Click this button to open the Build - Advanced, Build - Diagnostics, Build - Actions, and Build - SignCode property sheets. These property sheets allow you to specify the level of detail during preflight checks, any external actions to execute before, during, and after the build process, and the global or per-configuration SignCode settings, respectively.

Related topics

Build output files, Packages, Installer packaging, Working with attribute panes