2.4. Java libraries

Libraries are not separated between developers (-dev) and users versions, since this is meaningless in Java.

Libraries must not depend on a Java runtime.

Java libraries packages must be named libXXX[version]-java (without the brackets), where the version part is optional and should only contain the necessary part. The version part should only be used to avoid naming collisions. The XXX part is the actual package name used in the text below.

Their classes must be in jar archive(s) in the directory /usr/share/java, with the name packagename[-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.

Some package must also provide a symbolic link from packagename-extraname.jar to the most compatible version of the available packagename-extraname-version.jar files.

Class files in a Java library must be built with debug symbols.

All jar files must have a well-documented CLASSPATH, so that developers should know what to add to their wrappers.

This applies only to libraries, not to the core classes provided by a the runtime environment.

Some Java libraries rely on code written in a "native" language, such as JNI (Java Native Interface) code. This native code is compiled into separate dynamic libraries which are loaded by the Java virtual machine at runtime.

If a Java library relies on native code, the dynamic libraries containing this compiled native code should be installed into the directory /usr/lib/jni. These dynamic libraries should be shipped in a separate architecture-specific package named libXXX[version]-jni. The package containing the Java bytecode (generally libXXX[version]-java) should depend on this package.

There may be situations, such as with very small packages, where it is better to bundle the Java code and the native code together into a single package. Such packages should be architecture-specific and follow the usual libXXX[version]-java naming convention.

Java library packages should compile the javadoc API of the library. The API must link against the javadoc API of the libraries it depends on. This includes the core Java classes, which are provided by default-jdk-doc. The API must be registered with doc-base and must be installed in /usr/share/doc/<package>/api/ or /usr/share/doc/<package>/api-<component>/.

The API must be placed in a separate doc package. This package must recommend the doc packages it was linked against.