Chapter 2. Policy

Table of Contents

2.1. Virtual machines
2.2. Building Java packages
2.3. Java programs
2.4. Java libraries
2.5. Native Java Bytecode (gcj packages)
2.6. Main, contrib or non-free

Virtual packages are created: java1-runtime, java2-runtime, java5-runtime, java5-runtime-headless, java6-runtime, java6-runtime-headless, java7-runtime, java7-runtime-headless, java8-runtime and java8-runtime-headless.

Packages written in Java are separated in two categories: programs and libraries. Programs are intended to be run by end-users. Libraries are intended to help programs to run and to be used by developers.

Both must be shipped as Java bytecode (*.class files, packaged in a *.jar archive) and with an "Architecture: all". There are rare exceptions to this such as Eclipse SWT. Exceptions to this rule can only be granted by the Java Team. Requests must be sent to .

The Java bytecode may additionally be shipped as machine code, as produced for example by the GNU Compiler for Java, in a separate architecture-specific package.

Programs and libraries should enable unit tests, if these are present. The build may ignore test failures.

Java virtual machines must depend on java-common. They can also provide the runtime environment that the package supports (java1-runtime, java2-runtime, java8-runtime, java8-runtime-headless, etc). If it does not provide the files itself it must depend on the needed runtime environment.

They should use /etc/alternatives for the name 'java' if they are command-line compatible with the Oracle's java program.

They should have a CLASSPATH predefined which include the needed runtime environment.

If a given source (like the JDK does) brings both a compiler and a virtual machine, you may name the compiler package xxxx-dev.

Some Java classes implement their routines using a "native" language (such as C). This native code is compiled and stored in dynamic libraries (such as JNI modules) that are loaded at runtime. If a virtual machine supports native code, it must include the directory /usr/lib/jni in its search path for these dynamic libraries.

Since it is common for Java source tarball to ship jar files of third party libraries, creating a repack script to remove them from the upstream tarball is mandatory.

Packages must be built with default-jdk. This package provides a dependency on the recommended Java Development Kit. If needed, the right JAVA_HOME is /usr/lib/jvm/default-java/

The javahelper package provides helper to build either with CDBS or dh. They are strongly recommended for Java packaging.

For Maven based packages, the usage of maven-debian-helper is recommended.

Programs must have one or more executables in one or more of the directories defined by 9.1 of the Debian Policy. These must either be a wrapper script or a symlink to an executable jar. In any case, they must run without specific environment variables (see Policy 10.9), for instance CLASSPATH. They must respect the Policy rules for executables (for instance a manual page per executable, see Policy 13.1).

If the package installs a jar (or a symlink to a jar) as an executable the package must have an absolute dependency on jarwrapper or an equivalent package, which allows jar files to be executed directly from PATH like a normal program. The package must also ensure that the correct class is used as main-class. As an example jarwrapper uses the Main-Class attribute from the main part of the Manifest of the jar file to determine this.

Additional classes in the package must be packaged in one or more JARs which can be put into /usr/share/java (if they are intended to be used by other programs) or into a private directory in /usr/share/<package>.

Programs must depend on the needed runtime environment (default-jre or default-jre-headless if need a GUI or not, and java<N>-runtime or java<N>-runtime-headless as provided by alternative Java environments).

There is no naming rules for programs, they are ordinary programs, from the user point of view.

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.

Java bytecode compiled into native code is referred to as gcj-code and packages containing gcj-code as gcj-packages.

gcj-packages has been added in order to improve performance of Java libraries and programs. This is particularly useful on architectures where the JVM does not have a JIT. However, this performance comes at the cost of size, extra compilation time and creates architecture dependent packages.

Packages must not ship gcj-code without the permission of the Java team (). Source packages that shipped gcj-packages as of March 22nd,2010, have been given this permission through the ratification of this policy.

A request for permission to add gcj should convince the Java Team that the performance boost of adding the gcj-packages out-weights the disadvantages.

Source packages compiling gcj-packages must Build-Depend on gcj-native-helper (formerly known as default-jdk-builddep). The gcj-code should only be shipped for a selected set of architectures.

The gcj-code must be installed in /usr/lib/gcj/ and shipped separately from the original jar file. The gcj-package must also install the classmap file generated by aot-compile in /usr/share/gcj/classmap.d/.

The gcj-package must call rebuild-gcj-db in the postinst and postrm script, if rebuild-gcj-db is present.

The gcj-package must depend on the package providing the jar file, it is a native compilation. The package containing the jar file must declare either a Suggests or a Recommends relationship on the gcj-package.

About politics: packaging Java stuff changes nothing to the rules Debian uses to find if a program is free or not. Since there are not many free Java tools, keep in mind the following:

  • If your source package can compile (correctly) only with non-free tools, it cannot go to main. If your package itself is free, it must go to contrib.