File

A File object represents a file for installation or removal. You can add or remove files, and you can optionally register them if they contain self-registration code.

Installation or removal of a file is controlled by its component. If the component is installed, the file's Install action is executed (which may actually remove the file); if the component is removed, the Remove action is executed. If a file is not linked to a component, its Install action is executed during installation of your product and its Remove action when the product is removed.

Windows File Protection

InstallMate complies with the Windows File Protection (WFP) requirements on Windows Me, 2000, XP, and later versions. If an installation file is protected by WFP, InstallMate will never physically install or remove the file. However, any other applicable actions, for example file registration and SharedDlls reference counting, are performed normally. (File unregistration is never performed, because the file will never be removed by InstallMate.)

Attributes

The following attributes and options are available.

Attribute Description
Source path

Enter the source path of the file (i.e., the path to the file on your own system), or click ... (browse) to open the standard Open dialog box that allows you to select the desired file.

Note: Source paths are always displayed as fully qualified paths. However, by default InstallMate stores source paths as relative to the project file's folder. This allows you to move the entire project to a different location, or to access the project and its contents through a different path, for example through a network share on a shared file server.

To store source paths as absolute paths instead of relative paths in the project file, you must change the project default settings by choosing the File > Properties command from the main menu bar and selecting the Preferences page. The options on this page allow you to change the way the various file paths in the project file are stored.

Tip: To move the project file to a different location without moving its source files, use the File > Save Project As... command from the main menu bar. Do not move the project file itself manually, because that will break the relative paths (if any) in the project file.

Require digital signature

Check this box to let InstallMate check if the source file in question has a valid digital signature. Only some file types can be digitally signed (mostly executable files), so this option is typically used to ensure compliance with Windows application guidelines that mandate that all executables of a product have a digital signature.

If this option is checked and the source file does not have a valid digital signature, then a BLD:W0155 diagnostic is produced, which by default stops the build process (this is subject to the Treat warnings as errors setting in the package attributes).

Install name

Enter the installation name of the file; this is the name under which the file will be installed. By default, it is set to the file name in the Source path, but you can change this if desired. You can also use wildcards in this field if you want to perform wildcard file removal; see Uninstalling files created by the application for details.

File alias Enter the alias for the file. This alias must be unique in the project. InstallMate uses the alias to retrieve the file's installation path using the <#file_alias> syntax.
Install action Select the desired installation action from the drop-down list. The installation action is executed when the file's component is installed. If the file is not linked to a component, the action is executed when the product as a whole is installed. See Installation actions for a full list of installation actions.
Remove action Select the desired removal action from the drop-down list. The removal action is executed when the file's component is removed. If the file is not linked to a component, the action is executed when the product as a whole is removed. See Removal actions for a full list of removal actions.
Keep during updates

Check this box to keep the file during updates, i.e., when the uninstaller is run in upgrade mode (TsuUpgrade is nonzero). If this box is checked, the Remove action is ignored during upgrades (only) and the file will remain on the target system.

This option is useful if the file contains data that must be retained during upgrades of the product, but should be removed during full product uninstallations.

Reboot if installed Check this box to schedule a reboot if the file is installed; clear it for no reboot. This option only has effect if the file is physically installed; if the existing version of the file on the target system is reused, no reboot is scheduled.
Shared file

Check this box to indicate a shared file; clear it for an application-private file.

If you mark an installation file as Shared file, its SharedDlls reference count is incremented when the file is installed. This is true even if the file is not physically installed, for example when the existing version is reused because of versioning considerations.

Conversely, when a shared file is removed its SharedDlls reference count is decremented. The file is only physically removed from the target system if both its SharedDlls reference count is zero and its removal condition is satisfied.

No rollback

Check this box to exclude the file from any installation rollback; clear it to let the file participate in the rollback, if any.

An installation rollback is performed if the installation fails; in that case, any files that were replaced prior to the failure are restored to their original versions. However, this requires additional disk space during installation (to save copies of the original files), so for very large files that are not critical, you might choose to disable the rollback functionality.

Registration Select the file registration mode from the drop-down list. See File registration for a full list of file registration actions.
Registration #

Enter a number between 0 and 65535 that determines in which order the file will be registered, if its Registration field allows registration. The default registration order number for DLLs is 1000; see File registration for a full list of file registration orders.

When you add a new installation file to your project, InstallMate will automatically assign a registration order to the file based on built-in heuristics and detected dependencies. However, not all registration dependencies can be statically detected, so if you know that a particular file must be registered before or after another one, then you can set the file's Registration order field to a lower (before) or higher (after) number than the other's registration order number.

Files are registered by increasing order number and unregistered in the opposite order. If two files have the same Registration order number, their mutual order may vary between installation sessions.

DllInstall Check this box and enter the arguments for the file's DllInstall function if the file needs to be registered through its DllInstall entry point; clear it for no additional file registration. This is in addition to the Registration self-registration option.
App Paths

Check this box and enter a semicolon-delimited list of search paths for the file if any App Paths registration must take place for the file; clear it for no App Paths registration.

App Paths registration registers the file name and its location in the Windows registry and optionally adds application-specific search paths that are used when the application loads DLLs.

Create .local DLL
redirection file
Check this box to let the installer automatically create an empty .local file for DLL redirection. This is only useful for .exe files that need to load their DLLs from the same folder in which they reside. The resulting redirection file will be called Install name.local, for example MyApp.exe.local
Archive
Read-only
Hidden
System
Check these boxes to set the corresponding file attribute when the file is installed; clear them to install the file without the corresponding attribute. These attributes are initialized from the source file's attributes, except for Archive, which is always cleared.
Packaging Select the desired packaging for the installation file from the drop-down list. This option only has effect if you are actually distributing the file; it is ignored if not (for example, if the file's Install action is set to Remove). The following choices are available:
Packaging Description
Default The file packaging follows the Packaging option of the package and of its component.
Compressed The file is always compressed and stored in a compressed distribution package (the main package or the component's), regardless of the Packaging option of the package.
Plain file The file is always stored as a plain file (i.e., uncompressed) in the distribution tree, regardless of the Packaging option of the package. See the package documentation for details about the plain file distribution tree.

For a detailed overview of the interaction between the file packaging options and those of its component and package, see the Installer packaging topic.

Tip: If you distribute the file in uncompressed (plain) format, you can obtain its source path at installation time through the $srcpath() runtime function. This allows you to refer to the file prior to installation (after installation, you can use the normal <#file_alias> syntax).

Installation actions

The installer can create or remove files during product installation. The following installation actions are available for files:

Install action Description

Do not install

The installation file is not installed. If it is already present on the target system, it is left unchanged.
Install if not present The installation file is only installed if it does not already exist. If it is already present on the target system, it is left unchanged.
Install if present The installation file is only installed if it already exists. In that case, the existing file is replaced by the installation file if the installation file is newer than the existing file. See File version comparisons for information about "newer" files.
Install if not modified If the installation file does not yet exist on the target system, it is installed. If the installation file already exists, the existing file is replaced by the installation file if, and only if, the existing file has not been modified (i.e., if its Modified date is earlier than its Created date) and if the installation file is newer than the existing file. See File version comparisons for information about "newer" files.
Install if newer

If the installation file does not yet exist on the target system, it is installed. If the installation file already exists, the existing file is replaced by the installation file only if the installation file is newer than the existing file. See File version comparisons for information about "newer" files.

Note: This is the recommended action for Add-on and update installers.

Install always The installation file is installed and the existing file, if any, is replaced by the installation file regardless of versioning considerations.
Remove If the installation file exists, it is removed. Note that the actual file removal is still subject to its SharedDlls reference count; see Shared file above for more information.

Removal actions

The installer can remove or retain files during product removal. The following remove actions are available for files:

Remove action Description
Do not remove The installation file is left as-is.
Remove if installed If the installation file exists it is removed if, and only if, it was newly installed by the current installer. If it was left unchanged or if an existing file was replaced by a new one during installation, the file is not removed. Note that the actual file removal is still subject to its SharedDlls reference count; see Shared file above for more information.
Remove always If the installation file exists, it is removed. Note that the actual file removal is still subject to its SharedDlls reference count; see Shared file above for more information.
Restore original

Restores the version of the file that was present before the current product was installed. If there was no pre-existing file, the current file is removed as per Remove always.

Tip: This is the recommended action for Add-on and update installers.

Remove if not modified

If the installation file exists it is removed if, and only if, it was not modified since its installation. If it was modified since installation (i.e., if its Modified date is later than its Created date), the file is retained. Note that even if the file is removable (i.e., not modified), the actual file removal is still subject to its SharedDlls reference count; see Shared file above for more information.

Tip: This removal action is useful to preserve files that may be modified by the user or the program and whose modifications should be preserved even if your product is uninstalled. If you also set Install action: Install if not present on the file, then the file will not be replaced by the installer during updates.

File installation and removal during updates

During product updates it may be desirable to keep some files from the old version of the product. For example, user-modifiable data files or files that store user preferences are typically kept during updates, and sometimes even if the product is uninstalled completely.

The best combination of Install action and Remove action settings depends on the actual scenario that you are trying to cover. The following table shows the recommended actions for a number of common scenarios.

Situation Install action Remove action Other
File must always be preserved Install if not present Do not remove  
File must be preserved during updates* Install if not present Remove always* Set Keep during updates*
File must be preserved if modified Install if not modified Remove if not modified  

*This assumes that you are using the predefined UninstallPrevious action in the MainInstall action sequence. If you have removed or disabled that action, then the Keep during updates option has no effect and you should use Remove action: Do not remove to preserve the file during updates.

File version comparisons

If the file installation depends on the versions of the existing and installation files, the version comparison is performed as follows and in the order shown.

Situation InstallMate versioning rules
Both files have a VERSIONINFO resource
  1. Compare the ProductVersions (binary). The file with the higher ProductVersion is newer.
  2. If both ProductVersions are equal, compare the FileVersions. The file with the higher FileVersion is newer.
  3. If the FileVersions are also equal, both files have the same version.
Only one file has a VERSIONINFO resource
  1. The file with the VERSIONINFO resource is newer, regardless of its actual version.
Neither file has a VERSIONINFO resource
  1. The file with the later Modified date is newer.
  2. If the Modified dates are equal, both files have the same version.

Related topics

Files and folders, File registration, Working with attribute panes