Build Configuration attributes (Tarma)

Generic Win32 Setup program. It implements an installer that runs on Windows 9x (95, 98, Me) and Windows NT (NT4, 2000, XP, 2003) systems and contains all functionality required for those systems.

This Setup program uses ANSI text processing internally and can only handle languages that use the current ANSI code page on the target system.

This installer is slightly bigger (app. 75 KB) than either Setup9X.exe or SetupNT.exe, but smaller than those two together.

Windows 9x-specific installer. It implements all 9x-specific functionality (in addition to the common Win32 functions), but does not run properly on Windows NT-based systems, because it lacks NT-specific functions such as service installation and environment variable handling.

This Setup program uses ANSI text processing internally and can only handle languages that use the current ANSI code page on the target system.

Windows NT-specific installer. It implements all NT-specific functionality (in addition to the common Win32 functions), but does not run on Windows 9x-based systems, because it uses (versions of) Windows functions that are not implemented on Windows 9x systems.

This Setup program uses Unicode text processing internally and can handle all languages that are installed on the target system.

Always uses the generic Win32 Setup program, regardless of the build platforms.

This option is useful if you want to ensure that your installation package always uses an ANSI-based installer, for example if you are using an extension DLL and only want to provide its ANSI version.

Includes both the 9x- and the NT-specific installers. The former is used on 9x-based Windows versions; the latter on NT-based ones.

This option ensures that your installer uses the most appropriate installer for each target platform, including Unicode text processing on NT-based platforms, at the expense of a slightly bigger installation package.

Enter the name for the build configuration. This is also the name of the folder in which the installer package will be created; its full path is <ProjectFolder>\Project name\Config name, which is available through the BuildFolder variable. The value of the Config name field is available through the BuildName variable; you can use the values of these variables as <BuildFolder> and <BuildName> in any build actions.

Note: 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 Config name-langID, where langID is the 4-digit hexadecimal language identifier for the build language. The BuildFolder and BuildName variables reflect this.

Enter the name of the installation package; for a Tarma Installer package, this should have an .exe extension. The installation package will be created as <ProjectFolder>\Project name\Config name\Installer name and is available through the BuildTarget variable. You can use the value of this variable as <BuildTarget> in any build actions.

Tip: To retrieve portions of the installer's file name, you can use expressions such as <$fbase(<BuildTarget>)> and <$fname(<BuildTarget>)>.

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 and when your product is registered for the Add/Remove Programs control panel applet.

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.

Note: 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.

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.

Note 1: 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.

Note 2: 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.)

Note 3: 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.

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 or features.

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 product 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 product variable; you cannot set the Value (NT) attribute 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 Product Variables project page and set or clear its Save for Tarma 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:

• You can use symbolic expressions for the value portion;
• You can use them anywhere in the project (and installer) where you can use variables, including in conditional expressions;
• You can use them in build conditions for components and features.

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

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 strings, 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.

Select the desired Setup.exe stub from the drop-down list. The following choices are available:

See the section Setup stubs earlier in this topic for more details.

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

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 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.

Check this box to generate a build manifest during the build process; clear it to build without generating a manifest. The build manifest is an XML file that contains a detailed list of all files that were included in the installation package; it can be used as part of an audit trail for your product's release.

If generated, the build manifest is stored as <ProjectFolder>\Project name\<BuildName>.Manifest.<BuildDayNo>.xml, i.e., with the name of the build configuration (modified for per-language packages, if necessary) and the serial number of the day it was built.

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 tool 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.

Check this box to generate a ZAP file for each distribution package. A ZAP (Zero Administration Package) file is a text file containing rudimentary information about the accompanying Setup package. It is intended for Setup packages that do not use Windows Installer, and gives system administrators an opportunity to manage the Setup package in an automated fashion.

The ZAP file will be created as <ProjectFolder>\Config name\Installer name.zap, where .zip replaces the extension of the installer itself.

Click this button to open the Select Installation Platforms dialog box, which allows you to specify the Windows versions for the package.

The configuration's build platforms affect which project contents are included in the installation package. In particular, if a component is marked for some platforms but not for all, that component and its contents will only be included in the package if its platforms overlap with the configuration's build platforms. The build platforms also determine which Setup program is included in the installation package; see Setup stub above for details. Finally, the System Requirements are also intersected with the platforms that you specify, and the installer will refuse to install on any of the non-build platforms.

Tip: If you want to build separate installation packages for different Windows versions, for example one for Windows 95, 98 and Me, and another for Windows NT4, 2000, XP and later, you can do so as follows:

1. Create two TSU Configurations (or create one first, set its options, then use Copy and Paste to create a duplicate).
2. Set the Config name attribute of the first configuration to, for example, Install-9x and the second to Install-NT. It is important to choose a unique Config name for each configuration, or they will overwrite each other.
3. In the first configuration, check the Windows 95, 98 and Me platforms and clear the rest; in the second configuration, clear Windows 95, 98 and Me and check the rest.

You can now build both versions of the installer from a single Tarma ExpertInstall project. Obviously, you can create further configurations as needed.

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