You can build a project from the IDE or from the command line. The command line compiler executable is bin/install4jc and takes the project name as an argument. On macOS, that directory is inside the application bundle and can be shown in the Finder with the "Tools" toolbar button. That same toolbar button also allows you to create symlinks for all command line tools in /usr/local/bin so they can be directly invoked in a terminal.

There are plugins for Gradle, Maven and Ant for configuring the build in a way that is idiomatic for the respective build systems. In the end, all plugins invoke the command line compiler and for each command line compiler option there is a corresponding setting in the build system plugins.

When you start a build, install4j will check if all required information has been entered. If the build has been started from the install4j IDE, the corresponding step will be activated, and the offending setting will be focused, so it is recommended to try out your builds in the IDE first.

Build modes

There are three different build modes that correspond to different toolbar buttons in the install4j IDE or different command-line options in the command line compiler.

When a  regular build is started, the media files are built and placed in the media file output directory that is configured on the "General Settings->Media File Options" step.

Previous media files are overwritten, but a single build may not produce the same media file twice. On the "Customize project defaults->Media file name" step of the media wizard, you can adjust the media file name if the global pattern resolves to the same name for multiple media files. You can also use a compiler variable for the media file output directory and override it for each media file to avoid name clashes.

If you just want to check if the build will not produce any errors or warnings, you can start a  dry run. The media files will be built in the temporary directory but not moved to their final location. For command line builds, use the --test option.

Building media files can take a long time, especially if you package a lot of files that have to be collected and compressed. To facilitate faster development, install4j offers to  build an installer incrementally. The corresponding command-line option is --incremental.

This build mode is intended for testing changes that you make in the installer configuration such as adding, removing or modifying screens, actions and form components.

The action looks for the first media file in the "Media" step that can be run on the current platform and has an installer media file type. The media file must be already built, otherwise the action will terminate with an error message.

All scripts are recompiled and the installer configuration files are regenerated. The installed files are taken from the full build of the media file. If you change the definition of the distribution tree and expect to see these changes in the installer, you have to rebuild the media file with a regular build.

When the build is complete, the installer is started, so you can try out your changes immediately. With respect to a full build, the compilation time is reduced substantially, typically to a couple of seconds. A full build can take several minutes, depending on the number of files that are included and the selected type of compression.

Selective building of media files

Instead of building all media files, you can build only a subset by explicitly selecting the desired media files on the "Build" step.

This selection is persistent, but the command line build will still build all media files unless you pass the --build-selected option. This allows you to build a suitable media file in the IDE for testing without impacting the command line build on your build server.

To specify media files from the command line, pass the --build-ids=ID[,ID] or the --media-types=T[,T] option. IDs of media files are visible in the "Media" step if the "Show IDs" toolbar toggle button is selected. Selecting media files by their media type ID is useful if you build different media files on different platforms. The --list-media-types command-line option prints the full list of supported media types and exits.

Faster builds during development

During development, you can speed up your build by compromising on the size of the produced media files. By switching off LZMA and Pack200 compression, builds times can be reduced by 50% and more. By disabling JRE bundling, the generated installer will start up faster, because the JRE does not have to be unpacked. Finally, disabling code signing will prevent dialogs that ask for keystore passwords from being shown.

All these options for making builds faster are also available for the command line compiler, the corresponding options are --faster for disabling advanced compressions, -disable-bundling for ignoring JRE bundles and --disable-signing for building without code signing.

Trouble-shooting build failures

By default, basic progress information is shown in the build output and warning messages are highlighted. Any error will stop the build, and the command line compiler will exit with a non-zero return code. For debugging purposes, there are two options that give access to more detailed information.

With the --verbose option, install4j prints more information about interesting events during the build. For example, all compiler variable replacements are shown in detail. If the source of an error message is not clear, switching on verbose mode can give you more context about the compilation phase that caused the failure. In addition, a compilation failure that occurs while verbose mode is enabled will print the entire stack trace to the build output.

Secondly, the install4j compiler prepares its artifacts in a temporary directory which is deleted after the build completes. With the --preserve option you can ask install4j to keep this temporary directory so that you can inspect intermediate artifacts.