Merge Modules and Templates

Merge modules allow for the easy creation of suite installers, subinstallers, and templates, delivering reusability from project to project, within development teams, across the enterprise, or from third-party providers.

A suite installer is an installer for a suite of applications. Each application in a suite may be collected in a merge module so that they may be easily added to a different mix of applications.

Templates are generally used as starting points for installer projects. Installer items that remain unchanged, such as the License Agreement panel, would be saved in an InstallAnywhere template. You may also want to create a template to maintain the look and feel of your installer projects.

Merge Modules

Merge modules are essentially installer subprojects that can be created independently of one another and later merged. Like an installer, a merge module is a reusable collection of installation functionality, complete with features, components, panels, actions, and files. However, a merge module cannot be installed on its own; instead, developers use merge modules when they want to include the functionality of one installer within another installer.

Merge modules provide the following benefits and solutions to complex installation requirements:

• You can combine several merge modules from different products to create a suite installer.

• Independent development teams in different locations can create merge modules for different software components. A release engineer can combine those merge modules into a single product installer.

• You can create self-contained units of installer functionality for reuse in future installer projects. For instance, if the same software component needs to be in several different installers, build it into a merge module and make it available to all of the installer developers.

• You can save common installer functionality, such as License Agreement panels and Custom User Input panels, into merge modules to simplify future installer project creation.

• You can combine merge modules from third-party software packages to build complex software solutions without having to figure out how to install each individual package.

  NOTE

  Zero G provides many third-party merge modules on its Web site. See www.ZeroG.com to download them.

  
  

• You can use a merge module as the starting point for a new installer project. These merge modules are referred to as templates and are covered in the “Templates” section below.

• You can build any installer project into a merge module, and you can use any merge module within any other installer project.

• Merge modules are created as an option through the installer build process. Because merge modules contain all of the resources for a project, building them is just like building an installer. They can be built automatically when the installer is built, or they can be built explicitly from the advanced designer (check the Build Merge Module option on the Build task under the Distribution tab) or from the command line (use the +merge option).

Merge modules can be merged into an existing installer in one of two ways:

Merge modules can be integrated with a project in one of two ways:

Other important things to know about merge modules include the following:

• Read-only option: Merge modules can be locked to prevent them from being opened, used as templates, or merged into an installer. Read-only merge modules can only be installed as self-contained installer units.

• Optimize merge module size by platform option: Separate merge modules will be created for each platform. Each will contain only the resources needed for that specific platform. Do not use this option if merge modules will be imported into another installer. Importing a merge module requires a nonoptimized merge module.

• Advertised variables: These InstallAnywhere variables must be set before a merge module can be installed using the Install Merge Module action. On the Build task, under the Distribution tab, click Edit Advertised Variables to add variables, set default values, and add comments. Use advertised variables to inform master installers of settings required for a merge module's configuration.

• InstallAnywhere variables: These can be passed to the merge module when using the Install Merge Module action. Only selected variables will be passed to the merge module. By default, any advertised variable set by the merge module (advertised variables are set when the module is built) will be automatically passed in. Specific variables can also be passed in through the customizer of the merge module. For example, if the Magic Folder variable $IA_PROJECT_DIR$ was advertised by the merge module, it will be passed in. If the variable $OTHER_VARIABLE$ was not advertised, but was set in the customizer of the Install Merge Module action, it, too, would be passed in.

Templates

A template is the starting point for every new installer project. A template can be a simple empty project, or it can contain everything a regular project would contain, such as license agreements, custom graphics and billboards, and even files.

A template is simply a merge module that has been placed within the iatemplates folder inside the InstallAnywhere installation folder. When you create a new project, you have the option of starting from a template. When you start from a template, a copy of the template is created and saved.

Templates are great for large installer teams, where you want everyone to have a consistent starting point, or for starting a new project based upon an older one.

Merge Module Types

Design-Time Merge Modules

Use design-time merge modules to integrate a merge module into your main installer project. Once a merge module has been imported, it is fully integrated into your master project file; all files, actions, and panels will appear as if they were a part of your main installer project. Merged projects may be added and removed; however, any changes that are made once they've been imported will be lost if you remove a merged project from the suite.

For example, if you import a merge module into your master installer and then modify a few panels, when you save the project, those changes will be saved. If you remove the imported merge module from the suite, all of those changes will be lost, regardless of how many times your main installer project is saved.

Design-time merge modules display all panels you add to the project. They are the only merge module type that is not run silently.

Build-Time Merge Modules

A build-time merge module is included in your installer at build time and installed by the master installer. Unlike install-time merge modules, build-time merge modules are included with the master installer when you build the installer project. At install time, the master installer will install the build-time merge module. To specify that the merge module be build-time, select the option labeled Bundle Merge Module at Build Time from the Install Merge Module action customizer and pick a merge module with the Choose Merge Module button.

Build-time merge modules are packaged along with the master installer project in one .iap_xml file. Build-time suite installers can build a number of separate installers into a single executable. In this scenario, a single master installer runs a number of merge modules silently during the installation process. The master installer is responsible for the user interface and for passing properties files to the merge modules so that they run with the correct configuration information. The merge modules may also advertise specific properties they require to operate properly.

Install-Time Merge Modules

The main installer executes install-time merge modules at install time. They are external to the main installer project. At install time, the master installer looks for the merge module at the specified path and launches whatever merge module it finds there. If the install-time merge module path points to a directory, then all merge modules contained in that directory will be installed. This enables you to update suite installers without having to update the master installer package

To specify that the merge module will be an install-time merge module, select the Locate Merge Module at Install Time option from the Install Merge Module action customizer and then enter a path in the text field next to it.

Creating Merge Modules and Templates

You create merge modules and templates in much the same way as regular installers. Add any panels, actions, and rules just as you would for a typical installer project, then before building the Build | Distribution | Merge Module/Template Option, select Build Merge Module/Template. Once merge modules are built, they have almost the same contents as a regular installer project, except they don't contain an IAClasses.zip file or a launcher.

Build Options

When you have an InstallAnywhere project ready to be made into a merge module, go to the Build | Distribution | Merge Module/Template Option. Select Build Merge Module/Template. Build options are used to optimize the size of the merge module, define whether it is to be read-only, and edit the advertised variables for the merge module.

Merge Module Size

Merge modules will contain an approximation of their required size (based on the largest amount of space any given module could need), but you may override this size with your own calculation by setting an advertised variable. The variable $DISK_SPACE_REQUIRED$ may be set to override the automatic approximation.

Creating Merge Modules as Read-Only

You have the option of designating merge modules as read-only. This option protects their integrity; they can only be added to an installer project through the Install Merge Module action. A read-only module cannot be integrated with the main installer project using the Project | Modules task.

Advertised Variables

The Advertised Variables area lists all variables in a merge module installer project. The main installer project can pass InstallAnywhere variables to a merge module at install time. The merge module will then use these variables as regular InstallAnywhere variables.

To add your own variables to be passed to a merge module, go to the customizer for the Install Merge Module action in the designer, and click Edit Variables to add some variables.

There may be cases, however, when the merge module cannot run without some variables having already been set. Those variables should be advertised so the merge module can be configured easily. To do this, click Edit Advertised Variables on the Build Settings tab and set up your variables.

Now, if you go to the main installer project, add a merge module, and look at the settings for variables that will be passed to the merge module, you will see that the names of advertised variables have been added to your list and some may have been set to default values. Change the values as you like, and these will be passed to the merge module at install time.

Adding Advertised Variables

To add advertised variables, go to the Build task and then select Build Settings. Click Edit Advertised Variables. The Edit Advertised Variables dialog appears.

The variable name is the same as that defined for the merge module. The value is the corresponding value in the main installer project. For example, if you included the common Magic Folder $IA_PROJECT_DIR$ in your merge module, and you wanted that to correspond with the value of $IA_PROJECT_DIR$ in the main installer project, the variable name and value would both be $IA_PROJECT_DIR$.

Adding Merge Modules

To add a merge module, go to the Files task and click Add Action. Select Install Merge Module, and click Add. For information on the merge module action customizer, please see the “Merge Module Customizer” section below.