Using Path Variables in a DIM

InstallShield 2018

Project • This information applies to DIM projects.

When you add product files to a DIM project, InstallShield creates a path variable to use as the source of the product files by default. A path variable is a variable that InstallShield uses to represent a directory that contains a project’s source files. Note that InstallShield uses path variables at design time and build time; path variables are not available or used at run time when the installation is running on end users’ machines.

A general advantage of using path variables instead of hard-coded paths is that if the source files are moved to a different directory on the development system, you need to change only the value of the path variable. That is, you do not need to update each hard-coded path to all of your source files.

Using path variables in DIM projects can help to simplify source file management, especially if the DIM project is located on a different machine than the Basic MSI projects that will include the DIM project.

Path variables can also be helpful if you use source code control to store all of your code and InstallShield project files, and if you have build machines that obtain the appropriate files from source code control, compile the code, and build the installations. In this type of scenario, different release engineers and developers may use different local working directories for obtaining the latest files from source control. Using path variables to define the locations helps to minimize the issues that occur with different source locations.

Predefined Path Variables in DIM Projects

Following is a list of predefined path variables, as well as their typical values, in a DIM project.

Predefined Path Variables in a DIM Project

Predefined Path Variable

Typical Value

CommonFilesFolder

C:\Program Files\Common Files\

ISProductFolder

C:\Program Files\InstallShield\2016\

ISProjectDataFolder.DIM_GUID

<ISProjectFolder>\ProjectName\

ISProjectFolder.DIM_GUID

C:\InstallShield 2016 Projects\

ISRedistPlatformDependentExpressFolder

C:\Program Files\InstallShield\2016\Redist\Language Independent\i386 Express

ISRedistPlatformDependentFolder

C:\Program Files\InstallShield\2016\Redist\Language Independent\i386

ProgramFilesFolder

C:\Program Files\

SystemFolder

C:\Windows\System32\

WindowsFolder

C:\Windows\

In both cases where the path variable name contains DIM_GUID, DIM_GUID is the identifier that is defined in the DIM GUID setting of the General Information view of the DIM project. Following are sample path variables in a DIM project:

ISProjectDataFolder.8356F8B7_8DE5_4E04_A77A_6FA722CBE1CC
ISProjectFolder.8356F8B7_8DE5_4E04_A77A_6FA722CBE1CC
MyNewPathVariable.8356F8B7_8DE5_4E04_A77A_6FA722CBE1CC

The GUIDs help to identify the applicable path variables as originating in the DIM project. They also help to minimize or eliminate conflicts that would occur if the same path variable is used in a DIM project and also in a Basic MSI project that contains that DIM, and if different values are assigned to those two path variables.

The path variable names that do not include GUIDs—such as SystemFolder and WindowsFolder—are not specific to the project that is open in InstallShield, and they are available on all machines. The values of these types of path variables may vary depending on the operating system. For example, on a 32-bit machine, the value of ProgramFilesFolder may be C:\Program Files\. On a 64-bit machine, it may be C:\Program Files (x86)\.

Syntax for Referencing Path Variables

When a path variable is used in InstallShield, the path variable is enclosed in angle brackets—for example:

<ISProjectDataFolder.8356F8B7_8DE5_4E04_A77A_6FA722CBE1CC>

In some cases, you may want to define a path variable so that it is relative to a different path variable. For example, you may create a standard path variable called MySourceFiles. You may also want to use a different path variable called BinFiles to define a path to a Bin folder inside that MySourceFiles directory. When you enter the relative path variable in the Defined Value column for BinFiles variable, you must surround the base path variable name with angle brackets. Thus, the Defined Value column for the BinFiles variable would be:

<MySourceFiles>\Bin

If the value of MySourceFiles is C:\CheckoutRoot\, the value of BinFiles is C:\CheckoutRoot\Bin\.

Sample Path Variable Scenarios

If you work in an environment where you create and edit InstallShield projects on one or more machines but you build your installations on other machines, you may need to plan how you want to use path variables in your projects. Otherwise, when you build your installations in InstallShield, you may encounter build errors because of missing files, or the wrong files may be included in your builds.

The following examples illustrate different ways of using path variables in InstallShield projects. The method that is described in example 3 is the easiest one to use.

Example 1: Overriding the Values of DIM Path Variables in the Basic MSI Projects that Contain the DIMs

The following table shows examples of how one predefined path variable and several standard path variables are used in a DIM project.

Example 1 Path Variables in a DIM Project

Name

Defined Value

Current Value

ISProjectFolder.4E846FD3_5307_4CF5_9FF1_C476E5505666

(This is a predefined path variable for the folder that contains the InstallShield project file. Its value cannot be manually defined.)

C:\Source\Units\Utility\

CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666

C:\Source

C:\Source

PATH_TO_RELEASE_FILES.4E846FD3_5307_4CF5_9FF1_C476E5505666

<CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666>\SpellLib\Bin\Release

C:\Source\SpellLib\Bin\Release

PATH_TO_DICTIONARIES.4E846FD3_5307_4CF5_9FF1_C476E5505666

<CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666>\Dictionaries

C:\Source\Dictionaries

In this example, the author of the DIM project assigned the path variable CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666 to his source root folder—the working directory on his machine where he checks out files from source control—C:\Source. Path variables for other folders that contain source files are defined relative to the source root path variable.

If the release engineer uses a different working directory location on a build machine, it may be necessary to override the value of this path variable when building a Basic MSI installation for a project that includes the DIM. Therefore, the release engineer can set a new value for the source root path variable by passing the -l parameter to ISCmdBld.exe when building the installation from the command line. Since the other path variable values are defined by using the source root path variable, the values of those other path variables are updated accordingly.

Note that using this method may be tedious and error prone, especially if you are building an installation for a Basic MSI project that includes several DIM projects, each with their own path variables that need to be overridden.

Example 2: Changing the Values of the DIM Path Variables According to the Build Environment

If the source root paths on the DIM development machine do not match the corresponding paths on the Basic MSI build machine, you can open the DIM directly and update the values of the path variables as needed. To learn how to open the DIM project from within the open Basic MSI project, see Opening a Referenced DIM Project from Within an Installation Project.

This method may not be optimal if you are trying to deliver daily builds to your testing team and you are still making changes to the DIM projects.

Example 3: Using Path Variables that Are Relative to a Predefined Path Variable Such as ISProjectFolder.DIM_GUID

The easiest way to manage path variables in DIM projects is to always store source files in a path that is relative to a predefined path variable such as ISProjectFolder. DIM_GUID. The following table illustrates how you can do this.

Example 3 Path Variables in a DIM Project

Name

Defined Value

Current Value

ISProjectFolder.4E846FD3_5307_4CF5_9FF1_C476E5505666

(This is a predefined path variable for the folder that contains the InstallShield project file. Its value cannot be manually defined.)

On a development machine, the current value may be:

C:\Source\Units\Utility\

On the build machine, the current value may be:

C:\BuildWorkspace\Source\Units\Utility\

CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666

<ISProjectFolder.4E846FD3_5307_4CF5_9FF1_C476E5505666>\..\..

Note • Using the predefined project folder path variable for the value of this path variable, and then using the checkout root path variable for the other path variable values, makes the InstallShield project and all of its source files portable from one machine to another.

On a development machine, the current value may be:

C:\Source

On the build machine, the current value may be:

C:\BuildWorkspace\Source

PATH_TO_RELEASE_FILES.4E846FD3_5307_4CF5_9FF1_C476E5505666

<CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666>\SpellLib\Bin\Release

On a development machine, the current value may be:

C:\Source\SpellLib\Bin\Release

On the build machine, the current value may be:

C:\BuildWorkspace\Source\SpellLib\Bin\Release

PATH_TO_DICTIONARIES.4E846FD3_5307_4CF5_9FF1_C476E5505666

<CHECKOUT_ROOT.4E846FD3_5307_4CF5_9FF1_C476E5505666>\Dictionaries

On a development machine, the current value may be:

C:\Source\Dictionaries

On the build machine, the current value may be:

C:\BuildWorkspace\Source\Dictionaries

Using the predefined project folder path variable for the value of the checkout root path variable, and then using the checkout root path variable for the other path variable values, makes the InstallShield project and all of its source files portable from one machine to another.

See Also