Plugin goals

The plugin offers many goals. Some of these goals uses plugin properties but others make use of Custom properties that can be supplied in the project.xml file. Some examples of these custom properties used by the plugin can be found in the section Code extracts of this page.

Goals

GoalDescription
uber-dist:init This goal makes an OS check to to customize some operations based on the nature of the OS where the distribution is created. If on Unix-like (Unix, Solaris, Linux, etc), it will set the property: isOnUnix

Examples of operations that are tailored to the OS are:
  • customization of the tar call so that the file access rights are kept in the tarball if building on Unix or Solaris
  • The classpath entries created for launch scripts are also tailored to the right OS (different entries in the list seperated by a colon (:) on Unix, semi-colon (;) on Windows.
uber-dist:make This goal make a distribution. It starts from the existing target files and from the existing distribution assembly. Some files may be out of date but its way faster that a complete rebuild.
uber-dist:build This goal is used to create from scratch a binary distribution. Like make, it will build the distribution assembly in the dist-assembly dir (under target) but unlike uber-dist:make, this goal calls the goal clean-dist-filesystem before any other goal.
uber-dist:prepare-dist-filesystem This goal is responsible for creating the content of the distribution.

It first creates the necessary directories, then will call the custom goal of the calling project ('pom.artifactId':prepare-dist-filesystem). Once this goal completes, other internal goals gets called to finalize the distribution, goals like:
uber-dist:clean-dist-filesystem This goal, like its name suggests, deletes the distribution assembly directory and also deletes the distribution file (in the distribution directory) if it is found.
uber-dist:create-distrib This goal is responsible for creating the distribution out of the distribution assembly. Its is automatically called as part of both the uber-dist:make and uber-dist:build process.
uber-dist:copy-deps This goal is used to copy all project dependencies marked for deployment. This goal uses some plugin custom properties to control which, how and where the dependencies gets deployed.

The available properties must be supplied inside the properties tag in the maven project.xml file. The list of properties goes as follow:

  • jar.dependency.dist.dir:

    Specifies in which sub-directory the deplendencies must be published. This property can be supplied at the project level or overriden at the dependency level. The project level definition is used as the default value for all deployed dependencies except if the dependency states differently.

  • 'pom.artifactId'.deploy.

    This property must be added to each dependency defined your project.xml if you want it to be deployed in the system's distribution. The example above is valid for a project with id: myproject.
  • jar.dependency.dist.name

    This property allows changing the name of the dependency as it gets deployed. This is very usefull especially if your system is deployed as part of a framework that may use your dependencies but without the version number as part of the jar file name.
uber-dist:make-executable This goal run the chmod program on files to make launch scripts executable under Unix.

The goal will use the value of the property: maven.uber.dist.executable.permission for the permissions to pass chmod. If the property is empty, the value: gu+x will be used.

The files on which those rights will be applied are specified using the property: maven.uber.dist.executable.includes
uber-dist:copy-scripts This is a very usefull goal. It is used to copy launch scripts (bash, DOS batch, etc) with some automatic filtering happenning while doing so. The goal always copy the scripts in the root of the distribution assembly along with the project's artifact (if there is one).

The goal uses 3 properties to complete the work, see those for more details: As of today, 2 tokens are automatically replaced by Uberdist while copying scripts:
  • @artifact_id@: Gets replace by the expression: ${maven.final.name}.jar
  • @pom-artifacts@: Gets replace by the list of all deployed dependencies where each element are seperated between them the the OS specific classpath entry separator.


So with a single property to set, you get a fully configured launch script for your application. It is true that other mechanism can be used like the Class-Path manifest entry along with the Main-Class but if your jar holds many executable classes, multiple launch scripts will be necessary. Uberdist makes this script configuring operation transparent as long as you tell it where your scripts are.

An example of a bash launch scripts before and after running uber-dist is supplied in the section Launch scripts of this page.

Code extracts

project.xml

Example of a project level entry for the default dependency deployment directory in the project.xml file: 

Ex:
...
    </versions>    

    <properties>
        <jar.dependency.dist.dir>lib</jar.dependency.dist.dir>
    </properties>
...

This example shows how to configure a dependency in the project.xml file so that the Uberdist plugin will publish it under a specific directory and with its name overriden (version removed).

NOTE: In the following example, the project id is : myproject. See its usage in the 'projectId.deploy' property to indicate that this dependency must be deployed in the distribution. 


...
<dependency>
	<groupId>commons-logging</groupId>
	<artifactId>commons-logging</artifactId>
	<version>1.0.4</version>
  <url>http://jakarta.apache.org/commons/logging.html</url>
    <properties>
      <myproject.deploy>true</myproject.deploy>
      <jar.manifest.classpath>true</jar.manifest.classpath>
      <jar.dependency.dist.dir>lib/3rdparty</jar.dependency.dist.dir>
      <jar.dependency.dist.name>commons-logging.jar</jar.dependency.dist.name>
    </properties>
</dependency>
...


Launch scripts

This example shows the content of a launch script with the tokens that uber-dist will replace while it creates the distribution. All necessary properties must be set accordingly before.

#!/bin/sh

# Need native library path 
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./lib
export LD_LIBRARY_PATH

$JAVA_HOME/bin/java -cp .:@artifact_id@:@pom-artifacts@ test.com.MyClassToRun
This same script, after being copied by Uberdist, could look like this: 
      
#!/bin/sh

# Need native library path 
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./lib
export LD_LIBRARY_PATH

$JAVA_HOME/bin/java -cp .:myproject-1.0.jar:lib/commons-logging.jar:lib/commons-beanutils.jar test.com.MyClassToRun