Introduction

There are two fundamental needs for merged projects: First, there are large projects where a monolithic project file is undesirable since multiple developers work on the installer. Second, if you have multiple products that share certain components, it is undesirable to duplicate configuration for their installers.

The merged projects feature in install4j is a solution for both of these problems. You can create project files that are separate installers by themselves, such as a "database installer" and reuse them in multiple projects. On the other hand, you can also create project files that do not install anything by themselves, but just contain a collection of "Run script" actions that are useful in several of your installers.

Flat Merging Considerations

Merged projects in install4j are not sub-projects that will retain their structure at runtime. Merging inserts selected elements into the main project before the main project is compiled. Files, launchers and custom installer applications are inserted automatically, while elements from the installer and the uninstaller have to be inserted manually by adding links to the installer and uninstaller in your main project. At runtime, all merged elements are equivalent to the elements that were defined directly in the main project.

Merging works across an arbitrary number of levels and is performed in a bottom-to-top fashion: If the main project A includes a merged project B which in turn includes a merged project C, then C is first merged into B and the result is merged into A.

As a result of flat merging, there are no intermediary artifacts for merged projects, the result of the compilation is a single monolithic installer. This has the advantage of being easy and flexible, but collisions can occur unless concerns are properly separated between the main project and its merged projects. In particular, all elements in the final result share the same namespace for compiler and installer variables. All custom localization files are merged, so that localization in merged projects is not impacted unless there is a collision in the message keys. Such problems can be avoided if unique prefixes are used for compiler variables and installer variables as well as custom localization keys. For example in project A, all variables could be prefixed with "a." and in project B with "b.".

One area where such collisions are not possible is for IDs of any entity in a project, such as launchers, file sets, actions, screens or form components. When a project is merged, install4j prefixes all IDs with the application ID of that project. For example, if the application ID of a merged project is "1406-2150-6354-3051" and a launcher has the ID "2265", the ID is changed to "1406-2150-6354-3051:2265" after merging. This ensures that all IDs remain unique no matter how many projects are merged. Beans (screens, actions and form components) in the merged project are passed a special context that automatically prefixes all unqualified IDs with this application ID. For example, if you have a script in your merged project that calls context.getLauncherById("2265") this will succeed, even though the ID is now actually "1406-2150-6354-3051:2265". If you want to access that same launcher configuration from a script in the main project, you would have to call context.getLauncherById("1406-2150-6354-3051:2265").

Generally it is recommended to organize merged projects so that they are relatively self-contained and only interact with their main project through common installer variables. In that way, the main project can continue to work if the merged project is removed and the merged project can work as a standalone installer.

Display Of Merged Elements

Merged project files are only displayed on the Merged Projects tab. There is no hierarchical display of the elements of merged project files in the main project. Merging is only done at compile time and the merged elements are added to the media file.

One exception is the merging of screens and actions which is not done automatically, but through the placement of links on the screens & actions tab.

Merging Of Files

If you have enabled file merging for a merged project, files are merged automatically according to the following rules: All files from the default file set of the merged project are merged into the default file set of the main project. Roots are merged if the main project has roots with the same name, otherwise they are discarded. Files in each other file set of the merged project are only merged if the main project has a file set with the same name. To facilitate the set up of file sets in the main project, there is an action to synchronize file sets in merged projects.

If there are files with the same relative paths, the main project has the highest precedence and the most deeply nested merged project has the lowest precedence. For merged projects on the same level, a project with a lower position in the list has a higher precedence than a project with a higher position.

There is no merging of installation components. Installation components can only be defined in the main project. However, with the appropriate definition of file sets in merged projects you can easily contribute files to installation components in the main project. For example, if your merged project installs your database, and you want to ask the user whether to install the database, define a file set named "database" in the merged project and add all files to that file set. In your main project, you also add a file set named "database" (when adding the merged project, you will be asked whether to add that file set automatically). In your installation component for the database, choose the file set "database". It will not contain any files in the IDE, but during compilation, the files from the merged project will be added to it.

Merging Of Launchers And Custom Installer Applications

Launchers and custom installer applications are merged automatically if you have enabled merging for launchers and custom installer applications. It is not an error if there are collisions of launchers or custom installer applications with the same relative paths and the rules of precedence are the same as for the merging of files. However, it is recommend not to hide launchers in this way since this can lead to unexpected problems at runtime.

Both launchers and custom installer applications can be attributed to a particular file set. In that case, they are only merged if the file set also exists in the main project. The attribution to a particular installation component in the main project is done in this way, analogous to the way it is done for files.

Merging Of Styles

If style merging is enabled, all styles from the main project are made available for installer applications, screen groups and screens. This allows you to centrally manage a set of styles and re-use it in multiple projects.

See the help topic on styles for more information on how merged styles can be used in the project.