Media Files

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:

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:

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

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.