File Sets And Installation Components


install4j offers two mechanisms to group files: File sets and installation components. File sets are configured in the distribution tree and can be used in a variety of use cases as building blocks for your installers. Installation components are presented to the user at runtime and mark certain parts of the distribution tree that have to be installed if the user chooses an installation component.

Both file sets and installation components are optional concepts that can be ignored if they are not required for an installer project: There is always a "Default file set" to which you can add files in the distribution tree and on the "Installation components" step you do not have to add any components.

File sets

File sets are a way to group files in the distribution tree. When you need to select files in other parts of the install4j IDE, you can select the file set node instead of selecting single files and directories. Each file set has a special "Installation directory" child node that maps to the installation directory selected by the user at run time. Custom installation roots are defined separately for different file sets. If you require the same installation root in two different file sets, you simply define the same root twice.

The installation of file sets can be toggled programmatically at run time. The code snippet to disable the installation of a file set at run time is

context.getFileSetById("123").setSelected(false);

if the ID of the file set is "123". You could insert this snippet into a "Run script" action that is placed before the "Install files" action on the Installer->Screens & Actions step. File set IDs can be displayed by toggling the "Show IDs" tool bar button.

A common use case is to exclude platform-specific files from certain media files. You can define file sets for different platforms and exclude all unneeded file sets in the "Customize project defaults->Exclude files" step in the media wizard. This is an example of how to use file sets at design time in the install4j IDE.

Within one file set, all relative paths must be unique. However, the same relative path can be present in different file sets. Suppose you have different DLL files for Windows 8 and for Windows 10 and higher. You can create two file sets so that the installer contains both alternative versions. Once you find out whether you run on Windows 8 or on Windows 10 and higher, you can disable the file set that should not be installed with the code snippet shown above. By default, all included file sets are installed. If the same relative path occurs twice, it is undefined which version is used. In this case you have to make sure to disable the file sets that are not appropriate.

Installation components

If you define installation components. the installer can ask the user which components should be installed. In the configuration of an installation component you mark the files that are required for this component. A single file or directory can be required by multiple installation components.

Installation components are defined in a folder hierarchy. This means you can have groups of installation components that are enabled or disabled with a single click. Most options in the configuration of an installation component are used by the "Installation components" screen. They decide how the installation component is presented to the user, whether it should be initially selected or mandatory, and if it has dependencies on other installation components that should be automatically selected. To internationalize the name of the component for different media files, use custom localization keys.

The user will only be able to choose installation components if a "Installation components selector" form component is present somewhere in the installer. The "Installation components" screen that is part of the default project template contains that form component and is only displayed at runtime if you have defined any installation components.

Another important feature of installation components is that they can be marked as "downloadable". If you configure the download option in the "Data files" step of the media wizard, separate data files will be created for the downloadable components.

install4j also offers a two-step selection for installation components: In the first step, the user is asked for the desired "installation type". An installation type is a certain selection of installation components. Typical installation type sets are [Full, Minimum, Customize] or [Server, Client, All]. The display and the configuration of installation types is handled by the "Installation type" screen.

For each configured installation type, you can decide whether the user should be able to further customize the associated installation component selection in the "Installation components" screen or not. If the installation type is not customizable, the installer variable sys.preventComponentCustomization is set to true and a subsequent "Installation components" screen is not displayed.

The IDs of installation components can be used in expressions, scripts and custom code if you want to check whether the installation component has been selected for installation or not. A typical condition expression for an action would be

context.getInstallationComponentById("123").isSelected()

if the ID of the component is "123". In this way you can conditionally execute actions depending on whether a component is selected or not.