Migrating to install4j 12

2025-10-31

Posted by Ingo Kegel

In most cases, migrating to install4j 12 usually just involves opening and saving your project with the install4j 12 IDE. Nevertheless, there are some considerations with respect to backward compatibility and some behavioral changes.

As part of the evolution of the "Update alert" form component into the "Streamlined installation" chooser form component, the installer variable sys.confirmedUpdateInstallation has been renamed to sys.streamlinedInstallation. When the project is migrated, it is replaced in the entire project file.

However, if you use this variable in custom code, you need to update it accordingly.
The way that install4j determines the previous installation directory has been redesigned. See the What's new page for more details. Project migration to install4j 12 involves the following automatic changes to the project so that the resulting behavior closely corresponds to what happened in previous versions of install4j:
- A "Set installation directory" action is added to the startup node, either after an existing "Request privileges" action or as first action. Its "Search for previous installation" property is selected if the "Detect previous installation directory" setting on the "Installer->Update options" was previously selected. That setting has been removed. By default, the scope is set to "For all users if directory is writable". If a "Request privileges" action is used in the installer, but not in the startup node, the scope is set to "Installation directory for all users" instead.
- A "Set installation directory" action is added after each "Request privileges" action used in screens. The "Installation scope" of the action is set to "For all users if directory is writable" and the search for update installations is disabled.
However, the previous way the installation directory was set involved hidden logic and some heuristics that are not replicated by the new setup. In certain edge cases, the result can now be different. With the flexibility of the "Set installation directory" action you can achieve any desired behavior, but you will have to make it explicit in your project.
The non-public installer variable sys.resolveUserSpecificInstallationDir has been removed. It was previously set by the "Request privileges" action if a fallback to a user-specific installation directory was necessary. In install4j 12, this functionality has been moved to the new "Set installation directory" action which sets the boolean sys.installForAllUsers installer variable.

In the unlikely case that you use sys.resolveUserSpecificInstallationDir, you have to migrate it to the negated sys.installForAllUsers installer variable.
The "AdoptOpenJDK" and "AdoptOpenJDK (OpenJ9)" JDK providers have been deprecated. The associated API has been deprecated for a long time. Migrate to Adoptium for Temurin JDKs and the new Semeru provider for OpenJ9 JDKs instead.

If your project is configured to use a deprecated JDK provider, it is still shown in the JDK provider chooser. However, it cannot be selected for new projects anymore.
install4j now requires a POSIX-compatible shell for Unix/Linux media files. The only case where this is a problem is Solaris 10. Solaris 10 has been EOL since early 2024.

If you still need support for Solaris 10, define the compiler variable sys.ext.solaris10Compatible to add a workaround that executes /usr/xpg4/bin/sh on Solaris 10.
For macOS single bundle media files with the archive format set to ".pkg for App Store submission", additional top-level files are now added to the .pkg file. Previously, any configured additional top-level files were ignored in that case.