Debianization
When you are working on a Java based project, it is often handy to debianize the resulting application. Using a package installer your application can be easily installed together with its dependencies, it will will be accessible automagically by the all the users of the system and can easily be uninstalled,...
Manually
You could do this debianization manually, but there are many drawbacks when doing so:
- It would work only for your machine type (e.g. Ubuntu Karmic, or Debian Sid), not for other os types.
- Extra documentation needs to be provided to the other developers in the team.
- It would be a very repetitive job.
- I'm sure errors will be made.
The pkg plugin
When the application is built using Maven the pkg plugin can be used to automate the package building process.
The package builder itself is managed at the Evolvis site. It is created by Tarent, an IT company from Bonn, and is released under GPL version 2.
Prepare
Best to start by adding this plugin prepository to your pom or your settings.xml:
:::::xml
<pluginRepositories>
<pluginRepository>
<id>evolvis-release-repository</id>
<name>evolvis.org release repository</name>
<url>http://maven-repo.evolvis.org/releases</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
Configure
Here is an example of a simple Java application configured for Ubuntu Hardy debianization. These tags should be placed in the <build><plugins> section of your pom. Further down the important tags are explained.
:::::xml
<plugin>
<groupId>de.tarent.maven.plugins</groupId>
<artifactId>maven-pkg-plugin</artifactId>
<version>2.1.4</version>
<configuration>
<defaultDistro>ubuntu_hardy</defaultDistro>
<shortDescription>PPP Monitor</shortDescription>
<auxPackageMapURL>
${project.baseUri}/src/main/package/elevenbits.xml
</auxPackageMapURL>
<defaults>
<distros><string>ubuntu_hardy</string></distros>
<architecture>all</architecture>
<section>misc</section>
<mainClass>com.elevenbits.pppmonitor.PPPMonitor</mainClass>
<maintainer>
ElevenBits <[email protected]>
</maintainer>
<revision>r6</revision>
<customCodeUnix>
#echo "Updating classpath..."
POSTFIX=$${CLASSPATH_ARG#* }
PREFIX=/etc/pppmonitor
CLASSPATH_ARG="-cp $PREFIX:$POSTFIX"
#echo "Classpath: $CLASSPATH_ARG"
</customCodeUnix>
<srcSysconfFilesDir>src/main/packager/etc</srcSysconfFilesDir>
<sysconfFiles>
<sysconfFile>
<from>log4j.xml</from>
<to>pppmonitor</to>
</sysconfFile>
<sysconfFile>
<from>pppmonitor.properties</from>
<to>pppmonitor</to>
</sysconfFile>
</sysconfFiles>
<datadir>
/usr/share/pppmonitor/
</datadir>
<dataFiles>
<dataFile>
<from>pppmonitor</from>
<to></to>
</dataFile>
</dataFiles>
<srcAuxFilesDir>src/main/packager/scripts</srcAuxFilesDir>
<postinstScript>postinst.sh</postinstScript>
<postrmScript>postrm.sh</postrmScript>
</defaults>
</configuration>
</plugin>
Now follows the explanation of the important tags. The pkg web site contains all information on the configuration settings.
:::::xml
<groupId>de.tarent.maven.plugins</groupId>
<artifactId>maven-pkg-plugin</artifactId>
<version>2.1.4</version>
Version 2.1.4 or higher is required, since it allows the installment of pre/post install/remove scripts in the resulting package.
:::::xml
<defaultDistro>ubuntu_hardy</defaultDistro>
The pkg plugin can build packages for distributions like Debian and Ubuntu as well as embedded Linux variants like Maemo and OpenMoko. Additionally it supports the creation of IzPack installers. The defaultDistro tag value can be one of these.
:::::xml
<auxPackageMapURL>
${project.baseUri}/src/main/package/elevenbits.xml
</auxPackageMapURL>
The auxPackageMapURL should point to the ElevenBits package map. This package map sets the defaultBinPath to /usr/sbin. That way the generated package will be runnable by root only. You can find more info on the PackageMaps is available at the pkg site. Here is the ElevenBits mapping xml:
:::::xml
<!--
Package maps document for Ubuntu 8.04 LTS (Hardy Heron) with
ElevenBits updates.
-->
<package-maps>
<version>1.0</version>
<distro>
<id>ubuntu_hardy</id>
<label>ElevenBits's Ubuntu Hardy mapping.</label>
<inherit>ubuntu_gutsy</inherit>
<defaultBinPath>/usr/sbin</defaultBinPath>
<map>
<!-- Add extra mappings here. -->
</map>
</distro>
</package-maps>
Lets continue with some other tags:
:::::xml
<architecture>all</architecture>
<section>misc</section>
<mainClass>com.elevenbits.pppmonitor.PPPMonitor</mainClass>
The package will run on all architectures (since it is a Java application), the section in the package list is misc and the main class is com.elevenbits.pppmonitor.PPPMonitor.
::::xml
<maintainer>
ElevenBits <[email protected]>
</maintainer>
The maintainer will be used when signing the package. This is in detail explained further below.
:::::xml
<customCodeUnix>
#echo "Updating classpath..."
POSTFIX=$${CLASSPATH_ARG#* }
PREFIX=/etc/pppmonitor
CLASSPATH_ARG="-cp $PREFIX:$POSTFIX"
#echo "Classpath: $CLASSPATH_ARG"
</customCodeUnix>
When pkg builds a package a script is created using the pom data. At the end of the script the customCodeUnix is added by the plugin. Here is the code generated for this example:
:::::bash
#!/bin/sh
# This file is autogenerated by the maven-pkg-plugin. The source responsible
# for this script can be found in class: de.tarent.maven.plugins.pkg.generator.WrapperScriptGenerator
# You can provide additional VM arguments by setting the VMARGS environment variable.
BOOTCLASSPATH_ARG=""
CLASSPATH_ARG="-cp /usr/share/java/pppmonitor/devices-1.1.0.jar:/usr/share/java/RXTXcomm.jar:/usr/share/java/commons-logging.jar:/usr/share/java/log4j-1.2.jar:/usr/share/java/pppmonitor/mail-1.4.jar:/usr/share/java/activation.jar:/usr/share/java/pppmonitor/jms-1.1.jar:/usr/share/java/pppmonitor/jmxtools-1.2.1.jar:/usr/share/java/pppmonitor/jmxri-1.2.1.jar:/usr/share/java/pppmonitor/rolling-appender-1.0.jar:/usr/share/java/pppmonitor.jar"
MAIN_CLASS=com.elevenbits.pppmonitor.PPPMonitor
# Path of the shared libraries (e.g. for SWT
LIBRARY_PATH_ARG="-Djava.library.path=/usr/lib/jni:/usr/lib"
# Path to BC-ABI compiled classes. Has no effect on runtimes other than GCJ.
DB_PATH_ARG=""
# Additional system properties which are special for this application:
SYSTEM_PROPERTIES=""
# Allows overriding the VM by setting the JAVA environment variable.
if [ x${JAVA} = x ];
then
JAVA=java
fi
#echo "Updating classpath..."
POSTFIX=${CLASSPATH_ARG#* }
PREFIX=/etc/pppmonitor
CLASSPATH_ARG="-cp $PREFIX:$POSTFIX"
#echo "Classpath: $CLASSPATH_ARG"
exec ${JAVA} ${VMARGS} ${BOOTCLASSPATH_ARG} ${CLASSPATH_ARG} ${LIBRARY_PATH_ARG} ${DB_PATH_ARG} ${SYSTEM_PROPERTIES} ${MAIN_CLASS} ${@}
To set up the /etc and the related data files you can use these tags:
:::::xml
<srcSysconfFilesDir>src/main/packager/etc</srcSysconfFilesDir>
<sysconfFiles>
<sysconfFile>
<from>log4j.xml</from>
<to>pppmonitor</to>
</sysconfFile>
<sysconfFile>
<from>pppmonitor.properties</from>
<to>pppmonitor</to>
</sysconfFile>
</sysconfFiles>
<datadir>
/usr/share/pppmonitor/
</datadir>
<dataFiles>
<dataFile>
<from>pppmonitor</from>
<to></to>
</dataFile>
</dataFiles>
The default sysconfDir is /etc. The pppmonitor is a script that will be placed in the /etc/init.d by the postinst.sh. The ppppmonitor script is created with the Linux Standard Base in mind:
:::::bash
#! /bin/sh
### BEGIN INIT INFO
# Provides: pppmonitor
# Required-Start: $all
# Required-Stop:
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: The ppp monitor checks the 3G/UMTS state
### END INIT INFO
# Do NOT "set -e"!
PATH=/sbin:/usr/sbin:/bin:/usr/bin
NAME=pppmonitor
DESC="PPP Monitor"
DAEMON=/usr/sbin/pppmonitor
PIDFILE=/var/run/pppmonitor.pid
SCRIPTNAME=/etc/init.d/$NAME
# Exit if the package is not installed
[ -x $DAEMON ] || exit 0
# Load the VERBOSE setting and other rcS variables
. /lib/init/vars.sh
# Define the LSB start_daemoin, killproc and log_* functions
. /lib/lsb/init-functions
case "$1" in
start)
[ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"
start_daemon -p $PIDFILE $DAEMON
if [ $? -ne 0 ]; then
[ "$VERBOSE" != no ] && log_end_msg 1 || \
log_failure_msg "Oops!"
exit 1
fi
[ "$VERBOSE" != no ] && log_end_msg 0
;;
stop)
[ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"
killproc -p $PIDFILE $DAEMON
if [ $? -ne 0 ]; then
[ "$VERBOSE" != no ] && log_end_msg 1
exit 1
fi
[ "$VERBOSE" != no ] && log_end_msg 0
;;
restart)
log_daemon_msg "Restarting $DESC" "$NAME"
killproc -p $PIDFILE $DAEMON
if [ $? -ne 0 ]; then
log_end_msg 1
log_failure_msg "Failed to stop $NAME."
exit 1
fi
start_daemon -p $PIDFILE $DAEMON
if [ $? -ne 0 ]; then
log_end_msg 1
log_failure_msg "Failed to start $NAME."
exit 1
fi
log_end_msg 0
;;
status)
log_failure_msg "Status is not implemented yet."
;;
*)
echo "Usage: $SCRIPTNAME {start|stop|restart|status}" >&2
exit 3
;;
esac
exit 0
The last plugin tags define the install and remove scripts:
:::::xml
<srcAuxFilesDir>src/main/packager/scripts</srcAuxFilesDir>
<postinstScript>postinst.sh</postinstScript>
<postrmScript>postrm.sh</postrmScript>
They are placed in the directory set in the srcAuxFilesDir. Here uis the postinst.sh:
:::::bash
echo "Installing $name..."
/bin/cp $datadir/$name /etc/init.d
/bin/chmod +x /etc/init.d/$name
cd /etc/init.d
/usr/sbin/update-rc.d $name start 95 2 3 4 5 . stop 95 0 1 6 .
echo "Installed $name successfully!"
The postrm.sh:
:::::bash
echo "Removing $name..."
/bin/rm -f /etc/init.d/$name
/usr/sbin/update-rc.d -f $name remove
echo "Removed $name successfully!"
When following this example, do use this code layout for your maven package:
Execute
The pkg plugin has four goals: config, pkg, sign and deploy. To create a package, use this command:
:::::console
[email protected]:~/java/workspace/pppmonitor$ mvn pkg:pkg
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building PPP Monitor
[INFO] task-segment: [pkg:pkg]
[INFO] ------------------------------------------------------------------------
[INFO] Preparing pkg:pkg
[INFO] [resources:resources {execution: default-resources}]
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 1 resource
[INFO] [compiler:compile {execution: default-compile}]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources {execution: default-testResources}]
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 1 resource
[INFO] [compiler:testCompile {execution: default-testCompile}]
[INFO] Nothing to compile - all classes are up to date
[INFO] [surefire:test {execution: default-test}]
[INFO] Surefire report directory: /home/jw/java/workspace/pppmonitor/target/surefire-reports
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running com.elevenbits.pppmonitor.command.CurrentOperatorCommandTest
...
[device] [DEBUG] [2009.12.25 13:52:11] com.elevenbits.pppmonitor.command.ATCommand.handleLine(146) | Received empty line, ignore
[device] [DEBUG] [2009.12.25 13:52:11] com.elevenbits.pppmonitor.command.ATCommand.handleLine(148) | Received OK, output complete
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 sec
Results :
Tests run: 10, Failures: 0, Errors: 0, Skipped: 0
[INFO] [jar:jar {execution: default-jar}]
[INFO] [pkg:pkg {execution: default-cli}]
[INFO] distribution : ubuntu_hardy
[INFO] package system : deb
[INFO] default package map : built-in
[INFO] auxiliary package map : file:/home/jw/java/workspace/pppmonitor//src/main/packager/elevenbits.xml
[INFO] type of project : application
[INFO] section : misc
[INFO] bundle all dependencies : no
[INFO] ahead of time compilation: no
[INFO] custom jar libraries : <none>
[INFO] JNI libraries : <none>
[INFO] auxiliary file source dir: src/main/packager/scripts
[INFO] auxiliary files : <none>
[INFO] prefix : / (default)
[INFO] sysconf files source dir : src/main/packager/etc
[INFO] sysconfdir : (default)
[INFO] dataroot files source dir: src/main/auxfiles (default)
[INFO] dataroot : (default)
[INFO] data files source dir : src/main/auxfiles (default)
[INFO] datadir : /usr/share/pppmonitor/
[INFO] bindir : (default)
[INFO] creating temporary directory: /home/jw/java/workspace/pppmonitor/target/deb-tmp
[INFO] cleaning the temporary directory
[INFO] creating package directory: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-0.0.3-0ubuntu~hardy-r6
[INFO] copying artifact: /home/jw/java/workspace/pppmonitor/target/pppmonitor-0.0.3.jar
[INFO] destination: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-0.0.3-0ubuntu~hardy-r6/usr/share/java/pppmonitor.jar
[INFO] copying sysconf file: /home/jw/java/workspace/pppmonitor/src/main/packager/etc/log4j.xml
[INFO] destination: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-0.0.3-0ubuntu~hardy-r6/etc/pppmonitor
[INFO] copying sysconf file: /home/jw/java/workspace/pppmonitor/src/main/packager/etc/pppmonitor.properties
[INFO] destination: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-0.0.3-0ubuntu~hardy-r6/etc/pppmonitor
[INFO] copying data file: /home/jw/java/workspace/pppmonitor/src/main/packager/scripts/pppmonitor
[INFO] destination: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-.0.3-0ubuntu~hardy-r6/usr/share/pppmonitor
[INFO] resolving dependency artifacts
[WARNING] ubuntu_hardy has no entry for: com.elevenbits:devices:jar:1.1.0:compile
[WARNING] ubuntu_hardy has no entry for: javax.mail:mail:jar:1.4:compile
[WARNING] ubuntu_hardy has no entry for: javax.jms:jms:jar:1.1:compile
[WARNING] ubuntu_hardy has no entry for: com.sun.jdmk:jmxtools:jar:1.2.1:compile
[WARNING] ubuntu_hardy has no entry for: com.sun.jmx:jmxri:jar:1.2.1:compile
[WARNING] ubuntu_hardy has no entry for: org.apache.log4j:rolling-appender:jar:1.0:compile
[INFO] using traditional starter
[INFO] copying 6 dependency artifacts.
[INFO] destination: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-0.0.3-0ubuntu~hardy-r6/usr/share/java/pppmonitor
[INFO] copying artifact: org.apache.log4j:rolling-appender:jar:1.0:compile
[INFO] copying artifact: com.elevenbits:devices:jar:1.1.0:compile
[INFO] copying artifact: com.sun.jmx:jmxri:jar:1.2.1:compile
[INFO] copying artifact: javax.jms:jms:jar:1.1:compile
[INFO] copying artifact: com.sun.jdmk:jmxtools:jar:1.2.1:compile
[INFO] copying artifact: javax.mail:mail:jar:1.4:compile
[WARNING] ubuntu_hardy has no entry for: com.elevenbits:devices:jar:1.1.0:compile
[WARNING] ubuntu_hardy has no entry for: javax.mail:mail:jar:1.4:compile
[WARNING] ubuntu_hardy has no entry for: javax.jms:jms:jar:1.1:compile
[WARNING] ubuntu_hardy has no entry for: com.sun.jdmk:jmxtools:jar:1.2.1:compile
[WARNING] ubuntu_hardy has no entry for: com.sun.jmx:jmxri:jar:1.2.1:compile
[WARNING] ubuntu_hardy has no entry for: org.apache.log4j:rolling-appender:jar:1.0:compile
[INFO] creating control file: /home/jw/java/workspace/pppmonitor/target/deb-tmp/pppmonitor-0.0.3-0ubuntu~hardy-r6/DEBIAN/control
[INFO] calling dpkg-deb to create binary package
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5 seconds
[INFO] Finished at: Fri Dec 25 13:52:13 CET 2009
[INFO] Final Memory: 13M/78M
[INFO] ------------------------------------------------------------------------
You can find the .deb file in the target folder.
To sign and deploy a site to your (private) package list, you can use this command:
:::::console
[email protected]:~/java/workspace/pppmonitor$ mvn pkg sign deploy -Dmaven.test.skip -Drepo=<dupload config name>
where the dupload config name is the name linking to your packaging system as specified in the /etc/dupload.conf file. The dupload tool is a utility to upload Debian packages. See here for an example and information regarding this command.
What is the UUID?
The UUID library, present in all Linux systems, is used to generate unique identifiers for objects that may be accessible beyond the local system. The UUIDs generated by this library can be reasonably expected to be unique within a system, and unique across all systems. They could be used, for instance, to generate unique HTTP cookies across multiple web servers without communication between the servers, and without fear of a name clash. The UUIDs are also used to identify the hard disks on your Linux box.
Retrieve the UUID of your disk using blkid
The blkid program can be used to determine the type of content (e.g. filesystem, swap) a block device holds, and also attributes (tokens, NAME=value pairs) from the content metadata (e.g. LABEL or UUID fields).
::::console
[email protected]:~$ blkid /dev/sda5
/dev/sda5: UUID="21fb314a-b170-42b4-960a-07d7930b693f" TYPE="ext3"
The UUIDs of your disks can also be found in /dev/disk
::::console
[email protected]:~$ ls -al /dev/disk/by-uuid
total 0
drwxr-xr-x 2 root root 120 2009-10-14 10:31 .
drwxr-xr-x 5 root root 100 2009-10-14 10:31 ..
lrwxrwxrwx 1 root root 10 2009-10-14 10:31 0B7E-3FC3 -> ../../sda7
lrwxrwxrwx 1 root root 10 2009-10-14 10:31 21fb314a-b170-42b4-960a-07d7930b693f -> ../../sda5
lrwxrwxrwx 1 root root 10 2009-10-14 10:31 50340AA1340A8A64 -> ../../sda1
lrwxrwxrwx 1 root root 10 2009-10-14 10:31 9e83c2fe-b180-4b46-8b1c-b21eb1634895 -> ../../sda6
Use the vol_id command...
...when you want to see even more info on the hard disk:
:::::console
[email protected]:~$ sudo vol_id /dev/sda5
ID_FS_USAGE=filesystem
ID_FS_TYPE=ext3
ID_FS_VERSION=1.0
ID_FS_UUID=21fb314a-b170-42b4-960a-07d7930b693f
ID_FS_UUID_ENC=21fb314a-b170-42b4-960a-07d7930b693f
ID_FS_LABEL=
ID_FS_LABEL_ENC=
It is very simple to merge serveral PDF documents together into one PDF document. Just make sure that the gs package is installed on your system.
::::console
[email protected]:~$ gs -dNOPAUSE -sDEVICE=pdfwrite \
> -sOUTPUTFILE=result.pdf \
> -dBATCH one.pdf two.pdf three.pdf
This command will merge the thee PDF documents one.pdf, two.pdf and three.pdf into the resulting result.pdf document.