Category: install4j

Migrating to install4j 5

Those who made the move from install4j 3 to install4j 4 will remember that it was a lot of work to migrate custom code, because most core concepts had been changed.
Not so with install4j 5: Your old project file will be transformed to the new format and most projects will work right away, without the need for any manual work. If you are interested in the changes in the project file structure, please see the file config/transforms/transform_3.xsl in your install4j installation directory.

However, there are a number of cases where old functionality has been replaced, behavior has been changed or the API has been fixed. In those cases backwards incompatibilities can arise. This post intends to present an exhaustive list of them:

  • We have removed support for Java 1.3. This allows us to use the standard XML beans decoder and XML parser in the JRE. Java 1.4 is still supported.
  • The “Require admin user” action and the “Request admin privileges on Windows Vista” option on the “Installer options” step of the Windows media wizard have been removed. They have been replaced with a much more capable “Request privileges” action. The “Request privileges” action is now added to all projects by default and will be inserted into the “Startup” sequence of old projects as well. If you had a “Require admin user” action in your project, the “failure” properties will all be selected (they are otherwise not selected by default). If you had a condition expression on the “Require admin user” action, it will be lost. Especially platform-dependent configuration is now possible directly in the “Request privileges” action.
  • On the Installer->Custom Code tab, the old “Use installed JAR files if possible” option has been removed. Previously, the installer performed a two-phase initialization of screens and actions, before and after the “Install Files” action, so you could use custom code from installed JAR files. The main reason for that option was to prevent double packaging of JAR files, once for the installer and once for the launcher. In install4j 5, if entries in the custom code are also present in the distribution tree, they will be moved to the final destination by the “Install Files” action, and the custom code will automatically include the installed files in custom installer applications and the uninstaller. This change significantly improves custom code handling, because double packaging is always prevented and you can use such custom code before the “Install Files” action is executed.
    However, if your code depends on the location of the JAR file, this can be a breaking change and you have to change your custom code. In that case, the new Screen#isCreatedLazily() method and the optional Context#initializeLazilyCreatedScreens() method will help you to move the initialization of the custom screen after the “Install Files” action while the Context#addToClassPath(File) method allows you to add installed JAR files to the custom code for dependencies that only work in the installed location.
  • The compiler variable “sys.platform” now resolves to “windows-x64” for 64 bit media files. Previously, it always resolved to “windows”. This variable is used in the standard media file name pattern on the General Settings->Media File Options tab, so your 64-bit Windows media files will now be named differently if you have not changed or overridden the media file name.
  • There was a typo in the system message key name “LocateBrowerExecutable”. In the unlikely event that you used that key explicitly in your project before, it will lead to a runtime exception.
  • A few installer variable names have changed to make naming more consistent. The old names will be replaced automatically with the new names when you open your old project file for the first time. However, if you use them outside of the install4j IDE, for example in custom code, you will have to change them. The replacements are:
    • sys.mediaDirectory -> sys.mediaDir
    • sys.installerDirectory -> sys.installerDir
    • -> sys.programGroupName
    • sys.programGroup.linkDir -> sys.symlinkDir
    • sys.programGroup.allUsers -> sys.programGroupAllUsers

  • (Updated on 2010-07-15) The “Services” screen has been removed. The reason is that since the service actions now support arbitrary service executables (not only those generated by install4j), it would be difficult for us to present a list like in 4.x. Also, we feel that this is really a technical question that users should not have to answer. If needed, you can create a question with a configurable form. The “Hello world” project has such a screen.

Other breaking changes only concern the API:

  • The method ApplicationRegistry.ApplicationInfo#getProgramGroup() has been removed from the API. It has been obsolete since 4.2, when the “Load reponse file” action was added. In the GUI, the “Suggest previous program group” option on the Installer->Update Options tab has been removed as well.
  • Several typos in method names have been fixed. Fortunately, typos were only discovered for the rarely used methods Context#isErrorOccurred(), Context#setErrorOccurred(boolean) and
    FormComponent#initialize(). If you are affected by the first two changes, the build will fail. If you derive a form component from AbstractFormComponent, the third change concerns a method that is overridden and would not cause a compilation error, so we have added a method for backwards compatibility in that case.
  • Several methods in the Install4jBeanInfo and Install4JPropertyDescriptor classes had their return values changed from void to the class itself in order to facilitate usages in builder patterns. You just have to recompile your code against the new runtime library, no source code changes are required.
  • The Context#getWizardContext() does not return null in unattended or console mode anymore. Instead, a dummy wizard context is returned that does nothing when its methods are invoked. If you use Context#getWizardContext() to check for those installer modes, you have to change your code and use Context#isUnattended()and Context#isConsole()instead.
  • The “installerAndUninstaller” argument from ActionBeanInfo#setAssociatedStartupAction(String) was removed because the new ActionBeanInfo#setComplementaryStartupLink(boolean) makes more sense.

That’s it! Most of these changes are only breaking changes for corner cases and even then it should be easy to fix them. If you notice any other breaking changes, please let us know, so we can add them to this list.

Fine-tuning console installers

In the upcoming install4j 4.2.4 release, we’ll expand on the improvements that were introduced with the visibility script in install4j 4.2.3.

The GUI installer operates in a “one screen at a time” mode while the console installer does “one question at a time”. Due to this difference, the automatic translation of form screens from GUI to console mode will not always be optimal.

In 4.2.4 we will introduce a “Console handler” form component that allows you to fine-tune the console mode of your installers. The form component is invisible and has no effect in GUI mode. Its action is defined in the “Console script” property:

Besides the usual parameters for form components, the script is passed a “console” parameter, which is of type com.install4j.api.screens.Console and offers a number of methods for interacting with the user on the console. This has previously only been offered in the API for the development of custom screens and custom form components.

In the console script shown above, an error condition is handled in the middle of the form component sequence. In GUI mode, such error conditions are usually handled in the validation script of the screen, but due to the lack of “screens” in console mode, the validation might be more appropriate at an earlier time.

Another scenario for the use of console handler form components are form screens that do no require user input. In such a case, you could add a console handler form component and set its console script to

console.print("Please read the information above");
return true;

Appending to redirection files

install4j has always offered the possibility to redirect stderr and stdout to files. The main purpose of this feature is to analyze uncaught exceptions and to get debug information when something goes wrong in a customer’s installation.

The redirection files are created lazily, meaning that as long as there is no output, the file will not be created or replaced. However, once output is detected, the redirection file is created or overwritten. This has been the only option so far and while it is often sufficient to retain the error or debug output of the last run, in some cases you might want to keep the entire output over multiple invocations of the launcher.

In the upcoming install4j 4.2.4, we have added this feature and in the redirection step of the launcher wizard, you can change the classic “Overwrite” behavior to “Append”.

The redirection file will still be created lazily, but it will be appended to if it already exists.

install4j and Java for Mac OS X v10.5 Update 4

Unfortunately the latest release of Java 6 on Mac OS X a few days ago broke all installers on Mac OS X that require Java 6 as a minimum Java version.

This is why we have sped up our release schedule for 4.2.3 and we pushed out the release today.

The error message you get with installers that are generated by older versions of install4j is:

Java application launched from PPC or bad stub. Relaunching in 32-bit, and tagging sub-processes to prefer 32-bit with $JAVA_ARCH=i386.
[JavaAppLauncher Error] This process is [i386] and was re-exec'd from [i386], but for some reason we are trying re-exec to [].

How could this happen? The explanation goes like this: Installers on Mac OS X ship their own binary Java application stub. Prior to Java 6 this application stub only contained 32-bit executables for PPC and Intel architectures. So far, Java 6 is only available on 64-bit Intel machines. From the beginning, the 32-bit stub continued to work with Java 6. This behavior was changed in Java for Mac OS X v10.5 Update 4, so we had to add a 64-bit executable to the Java application stub.

If you’re on an older version of install4j and cannot update to the latest version for whatever reason, you can copy the file $INSTALL4J_HOME/resource/macos/JavaApplicationStub from a 4.2.3 installation to your older installation.

Changing the visibility of form components at runtime

One of the strong points of form screens is that they are displayed by console installers without any further configuration. You don’t have to program the user interface twice, once for the GUI and once for the console.

However, it is often necessary to hide certain form components at runtime. For example, a certain form component might only make sense on a specific platform. Until now, you could use the initialization script of the form component to change the visibility like this:

boolean visible = Util.isWindows();

This hides the form component unless the operating system is Windows.

However, the drawback of this method is that the console installer does not execute the initialization script of a form component – there is no GUI widget created and so the configurationObject parameter would be null. In the upcoming install4j 4.2.3, we have added a visibility script property that works for both the GUI and the console installer:

Even simpler than the previous initialization script, a simple visibility expression of


(no semicolon at the end to make it an expression rather than a script) hides the form component on non-Windows platforms.

Evaluation of cross-platform installer builders

On stackoverflow, there’s a question regarding the comparison of cross-platform installer builders. This answer is apparently the result of a very thorough evaluation and paints a very favorable picture of install4j.

Signing launchers and installers

  Since the release of Vista, code signing has been of growing interest for our users, mainly because a signed installer or launcher produces nicer and less UAC dialogs when it wants to elevate its privileges.

install4j provides a signing hook for all generated windows executables. On step 5 of the Windows Media Wizard, you can specify any external tool with the executable files as parameter. The signing tool will be called with the working directory set to the project file parent directory so you can specify keys and certificates relatively. You can use the $EXECTUABLE variable to refer to the launcher or installer and an $OUTFILE variable if the tool you use requires different in and out files. (more…)