Aug 082012
 

The nbm:build-installers Maven goal allows you to build the platform application installers using Maven, as I wrote about in an earlier blog post. Yesterday I decided to investigate how to configure the installer when building it using that goal.

The first thing that can be customised is which platform(s) to create installers for. This can be configured in the IDE from the application project’s properties, under the Build > Installer category. I chose to build an installer only for Windows. And when I looked at the pom.xml for the application project, I found the following:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>nbm-maven-plugin</artifactId>
    <configuration>
        <installerOsLinux>false</installerOsLinux>
        <installerOsMacosx>false</installerOsMacosx>
        <installerOsSolaris>false</installerOsSolaris>
    </configuration>
</plugin>

Looking at [1] (see Useful References below), we see that there are a number of other properties that can be set in addition to those now set by the IDE. This includes the parameters that get passed to the template.xml file via the userSettings property. To understand what this actually means, run the nbm:build-installers goal and have a look at the target folder of the application. In the folder targetinstallernbistub you will see the file template.xml. It is the ant script that will get executed during the process of building the installer. And that is the script that the properties get passed to.

The first useful thing is setting the icon that is displayed in the installer when it is running (see also [2]). After adding the icon, the same section in the pom.xml now looks like this:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>nbm-maven-plugin</artifactId>
    <configuration>
        <installerOsSolaris>false</installerOsSolaris>
        <installerOsMacosx>false</installerOsMacosx>
        <installerOsLinux>false</installerOsLinux>
        <userSettings>
            <nbi.icon.file>${basedir}/src/resources/icon.png</nbi.icon.file>
        </userSettings>
    </configuration>
</plugin>

However you will most likely not want to stop at the icon, but also change all the other images in the installer (see [4]). The template.xml provided with NetBeans 7.2 does not allow this out of the box. But the changes are simple (see [3] for some info towards the bottom of the page and also [5] as an example of a template.xml). First lets add a new property called nbi.instleftcorner.file that will specify the location of the image to be displayed at the top left of most of the installer wizard pages.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>nbm-maven-plugin</artifactId>
    <configuration>
        <installerOsSolaris>false</installerOsSolaris>
        <installerOsMacosx>false</installerOsMacosx>
        <installerOsLinux>false</installerOsLinux>
        <userSettings>
            <nbi.icon.file>${basedir}/src/resources/icon.png</nbi.icon.file>
            <nbi.instleftcorner.file>${basedir}/src/resources/left.png</nbi.instleftcorner.file>
        </userSettings>
    </configuration>
</plugin>

Then we create a copy of the template.xml file and specify the templateFile property in the pom.xml:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>nbm-maven-plugin</artifactId>
    <configuration>
        <installerOsSolaris>false</installerOsSolaris>
        <installerOsMacosx>false</installerOsMacosx>
        <installerOsLinux>false</installerOsLinux>
        <templateFile>${basedir}/src/resources/template.xml</templateFile>
        <userSettings>
            <nbi.icon.file>${basedir}/src/resources/icon.png</nbi.icon.file>
            <nbi.instleftcorner.file>${basedir}/src/resources/left.png</nbi.instleftcorner.file>
        </userSettings>
    </configuration>
</plugin>

The final part of the puzzle is changing the template.xml file to also copy the new file (see [5] again for a more complete example). As a quick fix, I just added the following

<copy file="${nbi.instleftcorner.file}"
    tofile="${installer.build.dir}/ext/engine/src/org/mycompany/installer/wizard/wizard-description-background-left.png"
    overwrite="true"/>

to the -prepare-icon target. Now when the nbm:build-installers goal is executed, the custom template.xml is copied including this change and the wizard-description-background-left.png image will be replaced before the installer gets built. The same can be done for any of the images. :)

Useful References

  1. NBM Maven Plugin documentation
  2. Developers FAQ Create Installers
  3. JIRA Build installers goal proposal
  4. Geertjan’s Blog: Customizing the NetBeans Platform Installer
  5. template.xml from osm2garmin

Edit (4 October 2012): Another useful resource:

Edit (1 February 2013): Timon Veenstra of AgroSense provided the following additional very useful information:

“If you want to adjust only the installation folder for windows, you will need to copy the default template.xml and adjust this part:

<replacefilter token="{product-install-directory-name}"         
        value="${suite.props.app.installdir}"/>
<replacefilter token="{product-install-directory-name-windows}" 
        value="${suite.props.app.installdir}"/>
<replacefilter token="{product-install-directory-name-macosx}"  
        value="${suite.props.app.installdir}"/>

If you want to adjust all of them, you could change your branding token. But beware that the branding token should be the same as the parent artifactId (without -_[0-9]).”

Also read Timon’s article entitled How to Change a NetBeans Platform Executable Icon with Maven for more valuable information!

  5 Responses to “Migrating my Mind to Maven (Part 6) – Customising the Installers”

  1. Heya, I’m trying to change the default installation directory for the Installer when using maven.

    In Geertjan’s blog entry ( https://blogs.oracle.com/geertjan/entry/predefining_the_installation_folder_in ), he says to modify the property product.properties.2.value in harness/nbi/stub/ext/infra/build/products/helloworld/build.properties .

    However, we need to have this defaulting to the %%APPDATA%% Windows environment variable instead of just “C:Program Files”. Any ideas on how to tackle that?

    • I haven’t forgotten about your question, but I don’t have an answer yet. I have some ideas but I haven’t had the time to try them out. :-)

    • If you want to adjust only the installation folder for windows, you will need to copy the default template.xml and adjust this part:

      If you want to adjust all of them, you could change your branding token. But beware that the branding token should be the same as the parent artifactId (without -_[0-9])

      • Timon, thanks for replying! It appears, however, that the XML was not successfully posted in your comment. Could you please try again? Or email me the snippet and I will add it to the original post?

      • Updated the article with the details. Thanks for the information, Timon!

 Leave a Reply

(required)

(required)


eight − 3 =

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>