There are two basic motivations for merged projects: First, there are large projects where a monolithic project file is inconvenient because multiple developers work on the same installer. Secondly, if you have multiple products that share certain components, it is undesirable to duplicate configuration for their installers.

The "merged projects" feature 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 by adding them on the "General Settings->Merged Projects" step. 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.

Merged projects in install4j are not subprojects that will retain their structure at runtime. Merging inserts selected elements into the main project before the main project is compiled.

Merge options

By default, files, launchers and custom installer applications are inserted. The corresponding merged elements are only added at compile-time and will not be visible in the main project. You can change merge options for each merged project individually.

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.

All selections are transitive for nested merged projects. For example, if the merged project contains another merged project for which merging of files is enabled, those files are only merged if file merging is enabled in the main project.

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 file set of the merged project are only merged if the main project has a file set with the same name.

The contained files in the merged project are not displayed in the main project. When defining installation components in the main project, you will only be able to select the entire file set. This means that the file sets in the merged project have to be as granular as required for your main project.

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 files" in the merged project and add all files to that file set. In your main project, you also add a file set named "Database files".

When adding the merged project, you will be asked whether to add that file set automatically to the main project. If file sets change later on, there is an action to repeat this synchronization. After invoking the action, the new file sets are displayed in the definition of the distribution tree.

In your installation component for the database, choose the file set "Database files". 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

All launchers and custom installer applications are merged if you have enabled the corresponding option for a merged project. 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 recommended not to hide launchers in this way because 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 the same way as for files.

Merging of screens and actions

Screens and actions are not merged automatically, but through a selective placement of links on the "Installer->Screens & Actions" step. If merged projects are configured, the "Add link into" menu contains an entry for each merged project.

You can add multiple links to single screens and actions, but for more complex tasks it is advisable to create groups for related beans and add a link to a single group.

When adding links, the install4j IDE, shows special nodes that do not show any structure but just a button that opens the target of the link in a different window. At compile-time, the target elements are inlined. This means that at runtime, it appears as if all merged elements were defined directly in the main project.

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.

Flat merging considerations

As a result of flat merging, there are no intermediary artifacts for merged projects and the result of the compilation is a single monolithic installer. This has the advantage of being straightforward 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.