Versions Compared

Old Version 11

changes.mady.by.user Ron Wheeler

Saved on

compared with

New Version Current

changes.mady.by.user Ron Wheeler

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Removed spurious dependency in response to comment

Preparation

The Laying out your project files for a Maven build page describes the overall layout of a maven project.

Compiling Using Maven

To compile IzPack using Maven, use the izpack-maven-plugin. There is good documentation at the izpack-maven-plugin page, but this page will describe how to use the most recent IzPack plugin.

...

Create a separate Maven project that will produce your izPack installer. You can refer to the IzPack Maven Plugin Reference section for details on the plug-in and the meaning of the configuration settings.

The basic strategy is as follows:

  1. Configure the Maven pom to create a "staging" area that will contain our izPack descriptor and all of our installer resources, including the jars that we want to include in our installer. 
    1. Use the Maven maven-antrun-plugin to copy our izPack descriptor file and resources into this "staging" area. 
    2. Use the maven-dependency-plugin to copy the jar with our custom panels, and any other jar dependencies that we want in our installer. Two different "executions" of the maven-dependency-plugin may be required; one to copy our application jars into one location, and if there are custom panels, another to copy the custom panel jars into a separate location.
  2. We'll then configure the izpack-maven-plugin to point it to our staging area and our installer descriptor.
Ok, let's get started.
Create Some Helpful Properties
We'll be referencing the The staging area location will be referenced a few times in the pom, so let's configure it as a pom property <property> to make things clearer. Let's also configure  Also configure the izPack version we're using, which we'll want to reference in a few places in the pom, as well. Put this .
Put these in the <properties> element under the root element of your pom file:
Code Block
xml
xml
<properties>
   <izpack.version>5.0.0<9</izpack.version>
   <izpack.staging>${project.build.directory}/staging</izpack.staging>
</properties>

Notes:

  • ${project.build.directory} typically references  references the compilation ./target/ directory of your module
  • Properties from your Maven project compiling the IzPack project can be directly references in the install.xml using the property name enclosed in '@{' and '}' , for example:
    <jar src="@{izpack.staging}/lib/appcore.jar"/>
    This only applies just on to properties defined in the calling project, not for properties seen in the calling projectcompiling project.
Add Your Dependencies

...

  • Add the dependency that contains your

...

  • actual Java application to be installed.
  • If custom panels are used, add the dependency that contains your

...

  • custom panel, 


Code Block
xml
xml
<dependencies>
  <dependency>
    <groupId>com.mycompany</groupId>
    <artifactId>myapplication</artifactId>
    <version>1.0-SNAPSHOT</version>
 </dependency>
  <dependency>
    <groupId>com.mycompany</groupId>
    <artifactId>myapplication-utilities</artifactId>
    <version>1.0-SNAPSHOT</version>
 </dependency>
 <dependency>
    <groupId>com.mycompany</groupId>
    <artifactId>mycustompanels</artifactId>
    <version>1.0-SNAPSHOT</version>
 </dependency>
</dependencies>

...

Put the installer descriptor and resources underneath src/izpack in your module. In the pom's <build> section, configure configure the maven-antrun-plugin to copy this entire directory to the staging area:

...

Configure the maven-depenency-plugin to copy the application's jars.

If there are custom panels, copy its jar as well.

...

Configure the izpack-maven-plugin

...

  • Add the base directory to the  izpack-maven-plugin

...

  • . This is our staging area

...

This example include a section for custom panels which may be omitted if it does not apply.

  • .
  • Add the location of  the install file.


Code Block
xml
xml
<plugin>
   <groupId>org.codehaus.izpack</groupId>
   <artifactId>izpack-maven-plugin</artifactId>
   <version>${izpack.version}</version>
   <executions>
      <execution>
         <phase>package</phase>
         <goals><goal>izpack</goal></goals>
         <configuration>
            <!-- base for relative paths in izpack descriptor -->
            <baseDir>${izpack.staging}</baseDir>
            <installFile>${basedir}/src/izpack/install.xml</installFile>
         </configuration>
      </execution>
   </executions>
   <dependencies>
      <dependency>
         <groupId>org.codehaus.izpack</groupId>
         <artifactId>izpack-panel</artifactId>
         <version>${izpack.version}</version>
      </dependency>
      <dependency>    .
     <groupId>com.mycompany</groupId>     .
     <artifactId>mycustompanels</artifactId>     .
    <version>1.0</version>
      </dependency>
    </</dependencies>
 </plugin>
Some key points:
  • Even though the custom panels dependency is declared as a project dependency, it also must be declared as a dependency to the IzPack plugin itself, or else you will see classloading errors. Maven gives every plugin execution its own classloader, which cannot see the classpath of the project itself.

Create Your Installer Descriptor

...

Create Your Installer Descriptor

Your installer descriptor should reference resources and jars relative to the staging area. For example, here is a resources section in our installer descriptor (i.e., install.xml):

Code Block
xml
xml
<resources>
    <res src="@{izpack.staging}/common_resources/img/install-sidebar.png" id="Installer.image"/>
    <res src="hello.html" id="HTMLHelloPanel.info"/>
    <res src="license.html" id="HTMLLicencePanel.licence"/>
</resources>

Note

...

: these resources are originally under src/izpack.

...

 They are copied from this directory to the staging area, where the IzPack compiler will look for them.

Summary

When finished, the entire build section of our pom should look something like this:

Code Block
xml
xml
<?xml version="1.0"?>.
.
.
<build>
  <plugins>
    <!-- copy izpack resources into izpack staging area, expected by izpack.xml -->
    <plugin>
      <artifactId>maven-antrun-plugin</artifactId>
      <executions>
        <execution>
          <id>create-staging-area</id>
          <phase>process-resources</phase>
          <goals>
            <goal>run</goal>
          </goals>
          <configuration>
            <tasks>
              <copy todir="${izpack.staging}">
                <fileset dir="${basedir}/src/izpack"/>
              </copy>
            </tasks>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <artifactId>maven-dependency-plugin</artifactId>
      <configuration>
        <excludeTransitive>false</excludeTransitive>
        <stripVersion>true</stripVersion>
        <overWriteReleases>true</overWriteReleases>
        <overWriteSnapshots>true</overWriteSnapshots>
        <overWriteIfNewer>true</overWriteIfNewer>
        <excludeScope>system</excludeScope>
      </configuration>
      <executions>
        <execution>
          <!-- copy product jars to izpack staging lib -->
          <id>copy-product-dependencies</id>
          <phase>prepare-package</phase>
          <goals>
            <goal>copy-dependencies</goal>
          </goals>
          <configuration>
            <outputDirectory>${izpack.staging}/lib</outputDirectory>
            <excludeScope>system</excludeScope>
            <!-- this excludes tools.jar, e.g. -->
            <excludeArtifactIds>mycustompanels</excludeArtifactIds>
            <excludeGroupIds>org.codehaus.izpack</excludeGroupIds>
          </configuration>
        </execution>
        <execution>
          <!-- copy izpack custom (custom panels, etc.) jars to izpack staging custom -->
          <id>copy-izpack-dependencies</id>
          <phase>prepare-package</phase>
          <goals>
            <goal>copy-dependencies</goal>
          </goals>
          <configuration>
            <outputDirectory>${izpack.staging}/custom</outputDirectory>
            <includeArtifactIds>mycustompanels</includeArtifactIds>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <groupId>org.codehaus.izpack</groupId>
      <artifactId>izpack-maven-plugin</artifactId>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>izpack</goal>
          </goals>
          <configuration>
            <!-- base for relative paths in izpack descriptor -->
            <baseDir>${izpack.staging}</baseDir>
            <installFile>${basedir}/src/izpack/install.xml</installFile>
          </configuration>
        </execution>
      </executions>
      <dependencies>
        <dependency>
          <groupId>org.codehaus.izpack</groupId>
          <artifactId>izpack-panel</artifactId>
          <version>${izpack.version}</version>
        </dependency>
        <dependency>
          <groupId>com.mycompany</groupId>
          <artifactId>mycustompanels</artifactId>
          <version>1.0-SNAPSHOT</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

Using Custom Panels

If you have custom panels, they should be developed in a separate Maven project. This is a standard Maven project, but you should include izPack as a provided dependency:

Code Block
xmlxml
<dependencies>
.
.
.

As mentioned at the start of this article, the dependencies of your application are project dependencies and need to be specified as normal Maven dependencies in the project's dependencies section.

Code Block
xml
xml
.
.
.
  </build>
  <dependencies>
    <dependency>
      <groupId>org<groupId>com.codehaus.izpack<mycompany</groupId>
      <artifactId>izpack-compiler<<artifactId>myapplication</artifactId>
      <version>${izpack.version}</version><version>1.0-SNAPSHOT</version>
    </dependency>
    <dependency>
      <scope>provided</scope><groupId>com.mycompany</groupId>
      <<artifactId>mycustompanels</dependency>
</dependencies>

We use scope = provided because we only need Maven to use the IzPack dependency at compile time.

In this project, you can create your custom IzPack panels.

Be sure that the Java package names that contain your custom IzPack panels begin with "com", "net", or "org", or else they will not be able to be loaded by your IzPack installer.

 

...

artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>
</project>

Using Custom Panels

If you have custom panels, they should be developed in a separate Maven project. This is a standard Maven project, but you should include izPack as a provided dependency:

Code Block
xml
xml
<dependencies>
   <dependency>
      <groupId>org.codehaus.izpack</groupId>
      <artifactId>izpack-compiler</artifactId>
      <version>${izpack.version}</version>
      <scope>provided</scope>
   </dependency>
</dependencies>

We use scope = provided because we only need Maven to use the IzPack dependency at compile time.

In this project, you can create your custom IzPack panels.

 
As mentioned above, you will need to include an execution of the maven-dependency-plugin to copy the custom panel jar to the staging area.

This example include a section for custom panels which may be omitted if it does not apply.

Code Block
xml
xml
<plugin>
   <groupId>org.codehaus.izpack</groupId>
   <artifactId>izpack-maven-plugin</artifactId>
   <version>${izpack.version}</version>
   <executions>
      <execution>
         <phase>package</phase>
         <goals><goal>izpack</goal></goals>
         <configuration>
            <!-- base for relative paths in izpack descriptor -->
            <baseDir>${izpack.staging}</baseDir>
            <installFile>${basedir}/src/izpack/install.xml</installFile>
         </configuration>
      </execution>
   </executions>
   <dependencies>
      <dependency>
         <groupId>org.codehaus.izpack</groupId>
         <artifactId>izpack-panel</artifactId>
         <version>${izpack.version}</version>
      </dependency>
      <dependency>
         <groupId>com.mycompany</groupId>
         <artifactId>mycustompanels</artifactId>
         <version>1.0-SNAPSHOT</version>
      </dependency>
    </dependencies>
 </plugin>
Some key points:
  • Even though the custom panels dependency is declared as a project dependency, it also must be declared as a dependency to the IzPack plugin itself, or else you will see classloading errors. Maven gives every plugin execution its own classloader, which cannot see the classpath of the project itself.
Add the <execution> section
  • Add the second execution section to copying of the custom panels jar to the custom/ directory under our staging directory (i.e., target/staging/custom). Note that we explicitly include our custom panels dependency so that no other jars are copied to custom/. It wouldn't hurt anything if this happened, but why do unnecessary work.
Summary

When finished, the entire build section of the pom should look something like this:

Code Block
xml
xml
<?xml version="1.0"?>
.
.
.
<build>
  <plugins>
    <!-- copy IzPack resources into IzPack staging area, expected by izpack.xml -->
    <plugin>
      <artifactId>maven-antrun-plugin</artifactId>
      <executions>
        <execution>
          <id>create-staging-area</id>
          <phase>process-resources</phase>
          <goals>
            <goal>run</goal>
          </goals>
          <configuration>
            <tasks>
              <copy todir="${izpack.staging}">
                <fileset dir="${basedir}/src/izpack"/>
              </copy>
            </tasks>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <artifactId>maven-dependency-plugin</artifactId>
      <configuration>
        <excludeTransitive>false</excludeTransitive>
        <stripVersion>true</stripVersion>
        <overWriteReleases>true</overWriteReleases>
        <overWriteSnapshots>true</overWriteSnapshots>
        <overWriteIfNewer>true</overWriteIfNewer>
        <excludeScope>system</excludeScope>
      </configuration>
      <executions>
        <execution>
          <!-- copy product jars to izpack staging lib -->
          <id>copy-product-dependencies</id>
          <phase>prepare-package</phase>
          <goals>
            <goal>copy-dependencies</goal>
          </goals>
          <configuration>
            <outputDirectory>${izpack.staging}/lib</outputDirectory>
            <excludeScope>system</excludeScope>
            <!-- this excludes tools.jar, e.g. -->
            <excludeArtifactIds>mycustompanels</excludeArtifactIds>
            <excludeGroupIds>org.codehaus.izpack</excludeGroupIds>
          </configuration>
        </execution>
        <execution>
          <!-- copy izpack custom (custom panels, etc.) jars to izpack staging custom -->
          <id>copy-izpack-dependencies</id>
          <phase>prepare-package</phase>
          <goals>
            <goal>copy-dependencies</goal>
          </goals>
          <configuration>
            <outputDirectory>${izpack.staging}/custom</outputDirectory>
            <includeArtifactIds>mycustompanels</includeArtifactIds>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <groupId>org.codehaus.izpack</groupId>
      <artifactId>izpack-maven-plugin</artifactId>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>izpack</goal>
          </goals>
          <configuration>
            <!-- base for relative paths in izpack descriptor -->
            <baseDir>${izpack.staging}</baseDir>
            <installFile>${basedir}/src/izpack/install.xml</installFile>
          </configuration>
        </execution>
      </executions>
      <dependencies>
        <dependency>
          <groupId>org.codehaus.izpack</groupId>
          <artifactId>izpack-panel</artifactId>
          <version>${izpack.version}</version>
        </dependency>
        <dependency>
          <groupId>com.mycompany</groupId>
          <artifactId>mycustompanels</artifactId>
          <version>1.0</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>


Add the custom panel jar to the installer description

...

Note that we use the fully qualified name of the panel class. 


Troubleshooting

There are a few simple things to check if your installer is not created properly. 

...