Useful links For more detailed information, see: http://www.debian.org/doc/manuals/maint-guide/index.en.html (maintainer guide) http://www.debian.org/doc/packaging-manuals/java-policy/ (java packaging policy) http://www.debian.org/doc/manuals/debian-java-faq/ch4.html (see 4.3 Questions on platforms and license concerns)

"Theory" behind Java packaging

When packaging for Java there are a minimum set of rules that MUST be followed in order to do things the right way, i.e., the "Debian way".

First, we need to clarify what we are packaging. There are 4 different Java "things" that may be packaged. They are:

1. Virtual machines (Not covered here since it probably won't show up in SCAPE context. For more info see the links in the top of the page)
2. Java libraries
3. Java programs
4. Java compilers (Not covered here since it probably won't show up in SCAPE context. For more info see the links in the top of the page)

Java libraries

Following some of the aspects of the philosophy behind Object Oriented Programming, more particularly encapsulation and modularity, functionalities that can be shared by two or more classes SHOULD be isolated. The same goes with Debian packaging: programs that can be used by more than one program, SHOULD NOT be packaged together but instead packaged separately and this relation of dependency stated as so: assuming that a program A exists, the program B says that depends on A (for the build and/or execution process).

In order to accomplish that in Debian, Java libraries MUST comply with the following rules:

1. The package must be named as libNAME[VERSION]-java (without the brackets), where the VERSION part is optional and should only be used to avoid collisions.
2. The JAR archive(s) must be placed at /usr/share/java/ and named NAME[-EXTRANAME]-FULLVERSION.jar
   The EXTRANAME is optional and used internally within the package to separate the different jars provided by the package.
   The FULLVERSION is the version of that JAR file. In some cases that is not the same as the package version.
3. Provide a symbolic link from NAME[-EXTRANAME].jar to the most compatible version of the available NAME[-EXTRANAME]-FULLVERSION.jar files.
4. Have a well-defined/documented CLASSPATH, so developers know how to add them to their programs.

Java programs

As Java programs are meant to be executed, they should comply with Debian specific executable rules here adapted to Java executables. So:

1. MUST have one or more executables, placed traditionally under /usr/bin or /bin, either by providing a wrapper script or a symbolic link to the executable JAR. They should not depend on environment variables, like CLASSPATH, and they must be compliant with Debian rules about executables (e.g. one man page for each executable).
2. JARs, or symlink to JARs, MUST be executable directly from the PATH like normal programs do. Usually, to achieve this, the JAR main-class must be defined in the manifest in order to correctly determine which is the class that turns the jar into an executable.
3. Additional classes in the package must be packaged in one or more JARs, that can be placed under /usr/share/java (if they are intended to be shared by other programs) or /usr/share/PACKAGENAME/ to be private.
4. Programs must depend on one or more java runtimes (e.g. java6-runtime)

Packaging strategies

TO WRITE: 2 options, so far: package all (program and dependencies) together package only the program, relying on Debian dependencies (requires a previous search to determine if the Java dependencies exist as a Debian package and then correctly setup the CLASSPLATH to /usr/share/java/...) and if any of the Debian dependencies doesn't exists, also package them and put them available see also: https://wiki.ubuntu.com/JavaTeam/Specs/MavenSupportSpec

This section exposes some strategies for packaging Java programs and libraries. They aren't part of any Debian policy but they are meant to be helpful in the packaging process.

Packaging strategies is probably the more non-consensual topic of Java packaging. This happens mainly because there are some tools used to build Java programs that do not comply in a very straight way fashion with the "Debian way" of packaging.

"Practical" Java packaging

In this section, both tools and examples of Java packaging will be explained.

Java packaging tools

Even if it's possible to only use the tools referred in the main page Building Your Debian Package, there are some tools that are Java specific in what concerns packaging. They are:

• javahelper: set of helpers with the prefix jh_
• maven-debian-helper and maven-repo-helper: set of helpers with the prefix mh_

Example

One of the tasks that need to be done in Action Services (WP10), more particularly in task 2, is to adapt existing action tools identified in the previous task in order to fit the SCAPE architecture. One of those tools is Apache Sanselan, which is a pure Java image library. But as a library, by its own, doesn't do much because it only exposes a set of functionalities accessible from a Java program but there isn't a way to access those same functionalities, for example, through the command-line. So, a wrapper needs to be implemented, in order to accomplish that.

The idea is more or less simple: Sanselan, as a library, must exist as a Debian package. Then a Sanselan wrapper, as a program, can be created and packaged, depending on the library.

libsanselan-java

sanselan-wrapper