Configuration

From mvn-pkg-plugin (inactive) Wiki
Jump to: navigation, search

Contents

WARNING

This page is not ready and probably contains mistakes regarding the configuration of the 4th generation packaging plugin.

Other packaging plugin generations

The packaging plugin exists in various generations these days. This page is going to become the definitive guide for the 4th generation of the plugin. If you are interested in the older generations refer to the respective Wiki pages.

Here is the list of properties which are mandatory to set if your Maven2 project is an application.

version page
1.5.x Configuration_1.5.x
2.x.y Configuration_2_x
3.x.y Configuration_3.x


Plugin usage

At first you need to add the plugin to your project's POM by adding the following lines (Do not forget to download the plugin or configure the Evolvis Maven Repository before!):

 <plugin>
   <groupId>de.tarent.maven.plugins</groupId>
   <artifactId>maven-pkg-plugin</artifactId>
   <version>3.1.1</version>
   <configuration>
     ....
   </configuration>
 </plugin>

Instead of the version above it is recommended to use the latest stable version.

Thinking in mvn-pkg-plugin

The following paragraph explains the basic idea behind the way the packaging plugin and gives you an insight in how to use it for your project.

Software is primarilary source code. Source code does usually not run. When a software is compiled it usually has dependencies which need to be available at compile time but also at runtime. At runtime you also want to put the software in a certain configuration. In other words its environment. Distributions provide your software with the dependencies it needs at runtime. Usually the newer the GNU/Linux distribution the more Java packages are available through the package management. The mvn-pkg-plugin always tries to use the most of those.

However your software, even though it runs within the same version of an operating system, might have a completely different configuration: There might be the configuration used for quality assurance, one for a developer's machine, one for demonstration purposes (adding demo data and setting a few knobs to provide faked visualizations) and finally one or more configurations for production. Each of the beforementioned example uses is called a target in the pkg-plugin. You are able to define different targets where the configuration of the application changes completely but the operating system is the same.

Actually the pkg-plugin tries to go a bit further and allows you to define the operating systems in which your app can run in this configuration. This means that the same behavior is expected on different OS version for example.

So with that explanation you should know that configuring the pkg-plugin for your app means defining targets.

Considerations for defining a target

A target for the pkg-plugin means a definition of what Maven artifacts (via the dependency mechanism) and files belong to a distribution specific package. You are completely free to set up packages in any way you like. However there are some rules which GNU/Linux distributions provide as guidelines. On the other side there are software engineering goals which chose to follow in order to implement an efficient deployment chain. E.g. we propose splitting up your software into code and configuration. For a specific OS you might have a certain package that contains the application's code. You will use the same resulting package for integration tests, QA and finally production. What differs is a second package which contain the configuration to be used.

Needless to say that your software needs a certain flexibility in order to make this approach feasible. E.g. if you have property files buried in JAR or WAR files along with the app's code the beforementioned approach will not work for you.

However the packaging pluging allows you to split packages in any way you like.

Plugin configuration

The plugin's configuration is split between simple and complex configuration parameters. The simple ones are those which are just one value per parameter. The complex parameters are those that consist of multiple values, provide inheritance and lists of values as their properties.

The following configuration parameters are mandatory and are needed for every project.

Basic mandatory parameters

Basic optional parameters

property purpose example
defaultTarget Name of the target configuration which is to be run by default if none is given via the command-line. foo
defaultDistro Name of the default distribution in case the chosen target configuration is ambigous about this (meaning that there is more than one defined). file://home/coder_joe/auxmaps.xml
shortDescription A short description which becomes part of each binary package. Some text.

The plugin provide has built-in support for the following distros: Built-in Distribution-Definitions

Use the id value in your POM.

IzPack is no distribution but an installer system. It is much different from Debian or IPK packaging but is nevertheless supported through the plugin.

Basic optional parameters

property purpose example
defaultPackageMapsURL URL of the default package maps document. By setting this value the built-in packages maps document is skipped and the specified one is used instead. file://home/coder_joe/defmaps.xml
auxPackageMapURL URL of the auxiliary package maps document. By setting this value the specified package maps document is loading in addition to the default one (may it built-in or not). file://home/coder_joe/auxmaps.xml
javaExec Name of the system's java executable. This is needed to run some built-in Java programs (namely IzPack :) ). Default is 'java'. cacao

Complex parameters

Complex parameters are the properties inside a target configuration. For a proper working plugin configuration you are required to at least define one target configuration.

Target configurations

A target configuration is the primary mean to configure the plugin and the way your software is packaged. You have a multitude of abilities at your disposal:

  • included dependencies
  • included files
  • wrapper script contents
  • system properties at runtime
  • default system paths
  • JNI paths
  • define supported operating systems/distributions
  • an inheritance mechanism for ease of configuration (name the common part of a configuration just once)
  • an inter-target configuration dependency mechanism

As explained in the #Optional parameters section the targetConfigurations parameter is a list of targetConfiguration instances. Each such instance can be told to belong to one or many distributions. This is practical because often distribution are so similar that it does not make sense to have separate configuration options for each of them (e.g. Debian Etch and Debian Lenny).

Furthermore you can define an inheritance chain between the configuration instances. The resulting configuration is retrieved by merging all the properties of all the parents. The mechanism works in a way that a child can always overwrite a setting of its parents. Collections (lists, sets) are however not replaced but merged together. There is no possibility to remove entries from a collection yet - you have to use a separate target configuration then.

Here is the list of properties which are mandatory to set if your Maven2 project is an application.

property purpose example
mainClass Denotes the programs main class. This must be available for applications. org.jalimo.examples.swt.SwtExample2
section Denotes the section a program belongs to. Everything but "libs" make a project an application and as such needs a main class. user/other
maintainer IPK-specific: This is mandatory for IPK packaging only!

Emailaddress of the package's maintainer. Make sure to use lt and gt entities in the POM.

Main Tainer <main-tainer@mymailaddress.org>

Complex optional parameters

The packaging plugin implements some simple concepts which are described here to better understand the need for certain properties.

auxfiles

There is a simple concept in the packaging plugin when it comes to dealing with files that are somehow needed for packaging (either at packaging time or after installation). All of those files are called auxilliary files and have to be put in a folder inside the project base directory. This folder is called the auxilliary files source dir (or srcAuxFilesDir as property) and has a default value of src/main/auxfiles.

Besides srcAuxFilesDir there is the auxFiles property which takes a list of AuxFiles entries. Those entries specify the source name and destination name or directory of the file. Since version 3.1.2, AuxFiles can have individual rights, owners and groups, by setting boolean attributes <userRead> <groupWrite> <othersExecute> and similar within the <auxFile> tag. At the moment this functionality is only provided for .rpm packages

special purpose auxfiles

The normal auxfiles can be regarded as untyped. There are other variants which have special purpose and are therefore treated slightly different. These files are handled through an extension of the auxfiles mechanism. There are for instance system-wide configuration files which are installed typically below /etc. Those special auxfiles have a source dir which is specified through the srcSysconfFilesDir property. If you do not set this value, srcAuxFilesDir is used instead. This behavior is consistent with all special purpose auxfiles.

Special purpose files also have a default installation directory on the target system which is distribution specific (but standardised through FHS for instance). You can modify this location by setting the sysconfDir property in case of the system-wide configuration files.

Here is a table of special purpose auxfiles, their meaning, default source and target location and which property has to be used to specify the actual files:

type meaning source dir property target property usual target dir file property
sysconf System-wide application configuration files. Editable only by the administrator. srcSysconfFilesDir sysconfDir /etc sysconfFiles
datadir Application specific data files - non Java resources (starter icons, .desktop files) srcDataFilesDir dataDir /usr/share/<appname>/ dataFiles
datarootdir Root directory of application specific data files - non Java resources (starter icons, .desktop files) srcDatarootFilesDir datarootdir /usr/share datarootFiles
binaries dir Directory of application specific executable files (wrapper script). Although possible it is not yet planned to specify additional executable programs this way. The target location is important for the program's own wrapper script. n/a n/a /usr/bin n/a
bundled Jar files dir Directory of the application's bundled Jar files. It is not planned to specify additional jar files. It is used for the serves for the program n/a n/a /usr/share/java/<appname>/ n/a
JNI files Directory of the application's native (or JNI) libraries. If multiple directories are given, split them with a colon and note that files are copied only into the first directory. srcJNIFilesDir jniFilesDir /usr/lib/jni:/usr/lib jniFiles
IzPack files Directory of the application's IzPack helper files (including installer.xml and all files referenced within it). srcIzPackFilesDir n/a n/a n/a


packaging scripts

Packaging systems usually know about 4 special scripts which are run before and/or after the installation or removal step. Those scripts have to reside inside the srcAuxFilesDir and whose source file name can be specified through a property. Here is the table of possible scripts, its meaning and correspoding property:

type meaning property
pre-installation script This is script is being run before the installation step. preinstScript
pre-removal script This is script is being run before the removal step. prermScript
post-installation script This is script is being run after the installation step. postinstScript
post-removal script This is script is being run after the removal step. postrmScript

All of those scripts are run with the /bin/sh program but do not need to specify this line at their top since this is done by the plugin itself. Furthermore they can access a number of variables. This has being done to allow to make the scripts more generic. Those variables are: prefix, bindir, datadir, datarootdir, sysconfdir, jnidir, bundledjardir, wrapperscriptfile, version, name, mainClass, scriptType, packaging, target, distro and distroLabel.

distro denotes the distro id while distroLabel is a human-readable name for it.

Target configuration properties influencing the plugins execution

The following table contains the list of all the properties which influence the execution of the package plugin itself and have a more indirect effect on the contents of the binary package or archive.

property meaning default value applicable for example
parent Specifies the target configuration from which this one inherits all non-set values or from which collections are merged. Any target configuration's name can be used as a parent identifier. When the plugin is run it will create a so-called merged version of the configuration where the child to parent relationship is traversed fully and properties are merged all along the way. not set *
 <parent>debian_etch</parent>
relations Denotes a list of target configurations whose binary packages are to be included as a dependency in this configuration's package. When building a target configuration which has relations the plugin will make sure the other packages are created as well. The same happens when uploading packages. not set *
 <relations>
   <relation>foo</relation>
 </relations>

Parameters influencing the package content

The following table contains the list of all the properties which directly influence the content of the binary package or archive. Each entry contains an explanation of their meaning and an example value if applicable. Note that certain properties make no sense with certain types of packaging. The table will tell you which one can be used for each.

property meaning default value applicable for example
advancedStarter Denotes whether the packager should use a special starter class to run the application which allows working around platform limitations as fixed command-line length. no * n/a
architecture Denotes the architecure string to be used. This is only effective for packagers supporting this feature (= ipk, deb). all *
 <architecture>i386</architecture>


bundleAll Denotes whether the packager should bundle every dependency regardless of whether a particular item is available from the system's native package management or not. This can be used to work around problems with those packages. no ipk, rpm, deb n/a
bundleDependencies Denotes a set of dependencies (in Maven's artifact id naming) that should be bundled with the application regardless of their existence in the target system's native package management. empty rpm, deb, ipk
 <bundleDependencies>
   <string>axis-saaj</string>
 </bundleDependencies>
distros Denotes the distributions this configuration is used for. This one should not be empty otherwise the configuration cannot be assigned to any distro. not set ipk, rpm, deb
 <distros>
   <string>debian_etch</string>
   <string>debian_lenny</string>
 </distros>
izPackInstallerXml Denotes the name of the IzPack descriptor file (The file has to be within the srcIzPackFilesDir!). installer.xml izpack
 <izPackInstallerXml>someCustomNameForInstaller.xml</izPackInstallerXml>
jniLibraryPath Denotes the java.library.path value of the application. In case of IzPack packaging do not forget to use the "${INSTALL_PATH}" variable. /usr/lib/jni *
 <jniLibraryPath>/usr/share/jni:/usr/share/${artifactId}/jni</jniLibraryPath>
 <jniLibraryPath>${INSTALL_PATH}/jni</jniLibraryPath>
manualDependencies Denotes a list of dependency strings which should be added to the automatically generated ones. This allows to specify dependencies which Maven does not know about. empty ipk, rpm, deb
 <manualDependencies>
   <string>libfoo-java<string>
   <string>libbaz-java<string>
 </manualDependencies>
recommends Denotes a list of strings which should be added to the "Recommends"-field of the package. See the Debian Policy Manual for more information on this field. (Since 2.1.x) empty deb
 <recommends>
   <string>libfoo-java</string>
   <string>libbaz-java</string>
 </recommends>
suggests Denotes a list of strings which should be added to the "Suggests"-field of the package. See the Debian Policy Manual for more information on this field. (Since 2.1.x) empty deb
 <suggests>
   <string>libfoo-java</string>
   <string>libbaz-java</string>
 </suggests>
provides Denotes a list of strings which should be added to the "Provides"-field of the package. See the Debian Policy Manual for more information on this field. (Since 2.1.x) empty deb
 <provides>
   <string>libfoo-java</string>
   <string>libbaz-java<7string>
 </provides>
conflicts Denotes a list of strings which should be added to the "Conflicts"-field of the package. See the Debian Policy Manual for more information on this field. (Since 2.1.x) empty deb
 <conflicts>
   <string>libfoo-java</string>
   <string>libbaz-java</string>
 </conflicts>
replaces Denotes a list of strings which should be added to the "Replaces"-field of the package. See the Debian Policy Manual for more information on this field. (Since 2.1.x) empty deb
 <replaces>
   <string>libfoo-java</string>
   <string>libbaz-java</string>
 </replaces>
maxJavaMemory Denotes the value of the "-Xmx" argument. This is put automatically into the wrapper script. not set *
 <maxJavaMemory>512m</maxJavaMemory>
prefix Denotes a path that is prepended before all application paths. not set (defaults to /) *
 <prefix>/opt</prefix>
revision Denotes the packages revision. This is a version number which appended after the real package version and can be used to denote a change to the packaging (e.g. moved a file to the correct location).

It is possible to use all kinds of strings for that. The ordering rules of those is dependent on the underlying packaging system. Try to use something sane like "r0", "r1" and so on. If this value is not set or set to the empty string, no revision is appended.

not set ipk, rpm, deb
 <revision>r5</revision>
sign Boolean that indicates if the resulting package should be digitally signed. The name provided for the maintainer will be looked up in the local set of private ssh keys and use the matching key to sign the package. false deb, rpm
 <sign>true</sign>

systemProperties Denotes a bunch of system properties keys and their values which are added to the starter script and thus provided to the application. not set *
 <systemProperties>
   <property>
     <name>org.foobar.something</name>
     <value>1000</value>
   </property>
 </systemProperties>
uploadParameters Contains information needed by the pkg:upload goal, in order to transfer files to a remote system/local filesystem path.(New in 4.x) not set. debapt-style URLs are only applicable for Debian packaging. *

 <uploadParameters>
   <urls>
     <url>scp:exe://remoteserver</url>
     <url>sftp://remoteserver</url>
     <url>file:///localpath</url>
     <url>debapt:///localpath</url>
   </urls>
 </uploadParameters>

wrapperScriptName Denotes the name of the wrapper script that is used to run the application. This property is optional and will default to the artifactId is the Maven project. For Windows targets ".bat" is appended to this name. not set (artifact id is used then) *
 <wrapperScriptName>zardoz</wrapperScriptName>
customCodeUnix Denotes a piece of shell script which is added literally into the starter for Unix-like systems. The code is inserted after variables have been set and right before the VM starts. not set (no code is inserted) *
 <customCodeUnix>
   echo "Hello World"
 </customCodeUnix>
customCodeWindows Denotes a piece of shell script which is added literally into the starter for Windows systems. The code is inserted after variables have been set and right before the VM starts. not set (no code is inserted) izpack
 <customCodeWindow>
   @ECHO Hello Windows World
 </customCodeWindow>
packageNameSuffix Denotes a suffix which is appended to the normal package name of the project. This name is being put into the respective system's control file and is also reflected by the actual file name of the package file. Make sure not to use invalid names. E.g. Debian naming does not tolerate upper-case letters. not set, thus no suffix is appended deb, rpm
 <packageNameSuffix>
   data-only
 </customCodeWindow>
packageVersionSuffix Denotes a suffix which is appended to the normal package version of the project. This name is being put into the respective system's control file and is also reflected by the actual file name of the package file. Make sure not to use invalid names. E.g. Debian naming does not tolerate extraneous hyphens and other characters might have an effect on how the value of the version number. not set, thus no suffix is appended deb, rpm
 <packageVersionSuffix>
   production
 </packageVersionSuffix>