Media files are the final output of install4j: single artifacts that are used to distribute your application to your users. The creation of a media file has platform-dependent options, so for each platform, you have to define a separate media file. It also makes sense to define several media files for one platform in case you wish to distribute different subsets of your distribution tree, or if you distribute your application with and without a bundled JRE.

Common options for all media files, such as the destination directory, a pattern for naming the output file and compression options are defined on the "General Settings->Media File Options" step.

Media files have names and IDs. The name is available elsewhere by using the sys.mediaName compiler variable but is otherwise not used by the compiler. IDs of media files can be used for selecting media files when building the project from the command line. You can show IDs by toggling the "Show IDs" tool bar button.

There are two fundamentally different types of media files: installers and archives. Installers support the full functionality of install4j while archives are limited in several ways.

Installers

Installers install your application programmatically with the configured sequence of screens & actions. Optionally, an installer can be executed in unattended or in console mode and it can download a JRE if no suitable JRE is found on the target system.

The following installer media file types are available:

• Windows

  A media file for Windows is a native setup executable that installs your application with an installer wizard.

  Optionally, you can create an MSI wrapper instead of a regular executable. This is configured on the "MSI wrapper" advanced options step below the "Installation options". It is not recommended to use the MSI wrapper without having a specific requirement for it. The MSI wrapper adds a lot of extra process machinery and additional logic to bridge mismatches between the concepts of install4j and MSI. This results in additional overhead, increased temporary disk space requirements, reduced responsiveness and extra considerations for the non-GUI installer modes.

  

  MSI usually has a fixed setting for whether an installation will be performed per-machine or per-user. In install4j, this corresponds to whether the "Request privileges" action is performed or not. If you execute the "Request privileges" action conditionally, you have to use the default "Selectable" MSI installation scope. However, for unattended installations, the user then has to specify the command line options

  ALLUSERS=1

  and start the msi installation with elevated privileges for a per-machine installation, otherwise the installation will be per-user.

  To avoid this extra parameter, install4j offers the "per-machine" MSI installation scope where this extra command line option is not required for unattended installations. It is your responsibility to ensure that the "Request privileges" action is always executed for the "per-machine" installation scope and is never executed for the "per-user" installation scope.

  If the scope is not selectable, MSI will also prevent that an installation is repeated if it has already been performed. The identity of an installation is defined by the MSI product ID. If an installation with the same product ID is found, the MSI installer will show an error message and terminate. By default, install4j creates a unique MSI product ID for each build. You can also tell install4j to create a new product ID for each application version as configured on the "General Settings->Application Info" step, or to use a custom MSI product ID that you can change as required.

  To change the installation directory, the variable INSTALLDIR can be specified on the command line. In addition, PARAMETER can be used to pass arbitrary command line parameters to the wrapped installer.

• macOS single bundle

  A single bundle media file for macOS is a DMG file that contains an installer wizard that is started by double clicking on it in the Finder. The wizard installs your application as a single application bundle for a selected GUI launcher. Command line launchers and service launchers are contained in the application bundle. If you wish to support multiple GUI launchers, choose the "macOS folder media wizard" instead.

  All files in the distribution tree will be installed inside the application bundle under the relative path Contents/Resources/app. The full path of that directory is exposed by the installer variable sys.contentDir at runtime. To install files to other directories, add an installation root to the distribution directory, for example with the name

  ${installer:sys.installationDir}/My Application Documents

  to create a folder "My Application Documents" next to the installed application bundle.

  The main drawback of this media file type is that the installer application bundle is not signed. Signing an application bundle has to be done at compile-time. With an installer, the exact contents of the installation are not known at compile-time. The installer itself will be signed, but if you need app entitlements that can be set on the "Executable info->macOS options" step of the launcher wizard, a signature of the installed application bundle is required. Use the single bundle archive in that case.

• macOS folder

  Like the single bundle installer, the folder media file for macOS is started by the user from the Finder after opening the DMG. The wizard installs your application as a folder that contains the entire distribution tree and multiple application bundles for each included GUI launcher.

• Unix/Linux GUI installer

  A Unix/Linux GUI installer media file is an executable shell script that extracts an installer and installs your application with an installer wizard.

Archives

Archives can be extracted by the user to arbitrary locations or are submitted to package managers for installation. No screens are shown and no actions are executed. If you define additional installation roots, the files in them are not installed. Also, no installation components are downloaded.

Apart from the "macOS single bundle" archive that produces the idiomatic deployment mode for GUI applications on macOS, archives are mainly intended as a fallback or for additional packages such as documentation bundles.

When a launcher is executed for the first time after an extraction, you can call a custom installer application to perform tasks that would otherwise have been part of the installer. With the ApplicationLauncher.isNewArchiveInstallation() method you can find out whether this is the case:

import com.install4j.api.launcher.*;

if (ApplicationLauncher.isNewArchiveInstallation()) {
    ApplicationLauncher.launchApplication("123", null, true, null);
}

where "123" is the ID of the custom installer application that should be run.

The following archive media file types are available:

• Windows archive

  An archive media file for Windows is a ZIP-file that contains your application.

• macOS single bundle archive

  A single bundle media file for macOS is a DMG or .tgz archive that contains a single application bundle for a selected GUI launcher. Command line launchers and service launchers are contained in the application bundle. If you wish to support multiple GUI launchers, choose the "macOS folder archive" media file type instead.

  Just like for the single bundle installer, all files in the distribution tree are contained inside the application bundle under the relative path Contents/Resources/app.

• macOS folder archive

  A folder media file for macOS is a DMG or .tgz archive that contains the distribution tree and multiple application bundles for each included GUI launcher.

• Unix/Linux archive

  A Unix/Linux archive media file is a gzipped TAR archive that contains your application. Users will extract them with a command like

  tar xzf archive.tar.gz

• Linux RPM

  An RPM archive for Linux can be installed and uninstalled with the rpm command on Linux distributions that use the Redhat package management.

  A basic installation command looks like

  rpm -i archive.rpm

• Linux Deb

  A Deb archive for Linux can be installed and uninstalled with the dpkg command on Linux distributions that use the Debian package management.

  A basic installation command looks like

  dpkg -i archive.deb

Customizing project defaults

Many project configuration settings can be overridden for each media file. Settings in text fields can be overridden by using compiler variables and overriding them in the "Customize project defaults->Compiler variables" step of the media wizard.

It is also possible to override compiler variables for specific media files from the command line by prefixing the variable name with the media file ID and a colon, as in

-D 123:key=value

if the media file ID is "123". As a special case, you can change the principal language on a per-media file basis by setting the compiler variable sys.languageId with the 2-letter ISO code of the desired language, for example

-D 123:sys.languageId=fr

For some features where text fields are not used, special screens are available in the "Customize project defaults" category. They let you exclude files, launchers, installation components and installer elements. In addition, the principal language and auto-update options can be overridden for the media file.

Because it is often necessary to change the name of the media file from the global media file pattern configured on the "General Settings->Media File Options" step, a separate customization step is available in the media wizard. For example, you may want to produce two different variants for the same platform with and without some files. To avoid a name clash of the two media files, you have to adjust the name of one or both of the media files.

Pack200 JAR compression

Pack200 compression is a compression algorithm that was designed for JAR files and achieves exceptional results, especially for large JAR files.

If you have signed JAR files or JAR files that create a digest, apply the $JDK_HOME/bin/pack200 executable in your build process with

pack200 --repack my.jar

before signing the JAR files. Pack200 rearranges JAR files but the reordering is idempotent, so the above pack/unpack sequence creates a stable JAR file.

While Pack200 compression can be quite slow, Pack200 decompression is relatively fast. Pack200 compression is only used for installers and not for archives.

To avoid problems with external JAR files, you can check the "Exclude signed JARs or JARs creating digests" option. If you would like to exclude selected JAR files only, you can place an empty *.nopack file next to it. For example, if the jar file is named app.jar, then a file app.jar.nopack in the same directory will disable Pack200 compression for that file.

To pass options to the packer, create a file *.packoptions next to the file and add one option per line. Currently, only -P and --pass-file are supported.

Executable post-processing

The install4j compiler can invoke a post-processor for each executable that is generated. This includes

• generated launchers
• the installer
• the uninstaller
• custom installer applications

Typically, this feature is used for custom code signing with special requirements that are not supported by the integrated code signing.

In the post processor text field you can use the $EXECUTABLE variable to reference the executable that is currently being post-processed. The working directory of the executed process is the directory where your project file is located, so you can use relative file names for key or certificate files. If the signing command cannot replace the executable directly, but rather needs a separate output file, use the $OUTFILE variable. It will receive a temporary output file name that will be moved back to the processed executable by install4j after the post processor has completed.