by Robert Dickau, Principal Technical Training Writer, Flexera Software
To help you detect and resolve potential problems in your installation project, you can perform several types of validation before you run the installation on a target system. The types of validation discussed in this white paper include:
- Build warnings and errors
- Internal Consistency Evaluator (ICE) validation
- Update and patch validation
Addressing these types of design-time validation errors will help you avoid errors. This white paper also shows you how InstallShield® helps you with design-time validation.
Learn More about InstallShield
If you wish to learn more about the capabilities of InstallShield, please visit the Flexera Software Web site at www.flexerasoftware.com/installshield
Using the InstallShield Environment
This white paper frequently refers to the InstallShield development environment. It is assumed you are familiar with the general layout of the InstallShield interface, which contains a list of views with which you can modify different portions of your installation project.
For example, the General Information view is where you set general product and project properties; the Setup Design view enables you to edit the features, components, and component data used by your project; the Registry view enables you to modify the registry data installed by your installation program; and the Direct Editor view gives you access to the raw MSI database tables.
It is also assumed you are familiar with some of the wizards available with InstallShield, such as the Release Wizard and Component Wizard.
- The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the properties— media type, compression settings, and so forth—of a release, and then builds the specified release image.
- The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types of components, such as components for COM servers, fonts, and Windows services.
The InstallShield Help Library contains information about using every view and wizard in the InstallShield environment. The InstallShield Help Library is available when you press F1 with any view selected; you can also select Contents from the Help menu to view the help library.
In addition to the graphical environment, InstallShield provides several tools for modifying and building projects from the command line or an external script. For example, to build a project from the command line, batch file, or other automated process, you can use the executable IsCmdBld.exe. The IsCmdBld executable is located in the System subdirectory of the InstallShield distribution directory.
To rebuild a project, you pass IsCmdBld the project file path, the product configuration name, and the release name that you want to rebuild. A sample command appears as follows:
iscmdbld -p C:\ProductName.ism -a BuildConfig -r ReleaseName
In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment.
Build Warnings and Errors
As InstallShield builds your project, status messages are displayed in the output window at the bottom of the development environment.
For a command-line build using IsCmdBld.exe, status messages are displayed at the command prompt.
If any errors or warnings occur, they are displayed in the Build tab of the output window, as well as in the Tasks tab. The Tasks tab contains links to the InstallShield Knowledge Base for the latest information about resolving these warnings. (This requires a live Internet connection.)
Addressing Build Errors and Warnings
Build errors and warnings typically refer to missing or unexpected source files or merge modules, but can refer to any condition that prevents a build from completing. For example, the build process reports error –1014 (“Cannot rename directory…”) if an installation inside the build folder is running, or if Windows Explorer or a command prompt is pointing to the build folder.
In addition, the InstallShield environment will prevent you from entering some project settings that would cause the package to fail at deployment time. For example, a project cannot use DATABASE or PATCH as an internal Directory-table identifier—the way INSTALLDIR or SystemFolder is a Directory identifier—as these are reserved identifiers used by Windows Installer. If you try to define a component destination folder with internal identifier DATABASE, the environment will rename the identifier to a valid value such as DATABASE_DIR1. (If, however, you use the Direct Editor to define a Directory called DATABASE or PATCH, the build process will report error –6262.)
TIP: When you manually search the InstallShield Knowledge Base for a particular build warning or error number, omit the minus sign in the search. For example, instead of searching for “–1014”, search for “1014”.
Errors Regarding Missing Source Files
If the build process cannot find a source file, because it has been renamed or deleted, the build process returns error –6103 (“Could not find file file”) and –1007 (“Cannot copy source file to target directory”).
Two features of InstallShield that can help you work with source files are path variables and dynamic file linking. Path variables are variables used by the InstallShield build process to represent the locations of source files on the development system. Whenever you add a file to a component, InstallShield by default creates a path variable or reuses an existing path variable to represent that file’s location. If you move the source file, instead of having to reestablish the file link, you can simply assign the path variable a new value in the Path Variables view of the InstallShield environment. (The InstallShield help library also describes registrybased and environment variable–based path variables, with which you can modify path variable values without having to modify the project file.)
In addition, if you have source directories that contain lists of files that are continually changing, you can use dynamic file linking. With dynamic linking, you specify a directory and optional file name masks for inclusion and exclusion. Each build process then copies all of the matching files in the dynamic link into the corresponding component.
An important consideration regarding file linking is that a dynamically linked file cannot be the key file of its component. However, a component can contain any combination of static and dynamic links, and therefore a solution is to set a statically linked file as the key file, additionally marking the key file as an exclusion to the dynamic link.
Moreover, when using dynamic file linking, it is important to specify a “previous package” in the build settings to ensure File, Component, and Media table keys are synchronized between builds. For more information, see the InstallShield help topic “Upgrade Considerations”.
Another error related to missing data on the build system is –1024 (“File not found. Cannot stream the file into the Binary file.”), which occurs if a file used by a custom action or dialog box (such as a DLL or bitmap file) has been moved or deleted. Similarly, build error –7017 occurs if your project includes merge modules or other redistributables that are not present on your build system. Other errors sometimes related to missing source files are –6271 (“File file not found. An error occurred building the MsiFileHash table record…”) and –1501 (“Could not compress file into file.cab”).
Design Issues and Build Warnings
In addition to issues related to source files, some build warnings address design issues in your project.
A deferred custom action must be placed between InstallInitialize and InstallFinalize in the Execute sequence of an installation. To help detect problems with improper placement of deferred actions, the build process generates warning –6524 if it detects a deferred custom action outside the range of InstallInitialize and InstallFinalize
TIP: By default, the build process will continue to completion even if any build errors occur. To cancel a build, you can click the Stop Build toolbar button, or press Ctrl+Break. To specify always to stop a build if an error occurs, you can pull down the Tools menu and select Options; in the General tab, select the check box labeled “Stop build process when first error is encountered”.