Hi all, We had two BoF meetings at DebConf to discuss Java packaging. Here's a summary of what we discussed. I've also attached a diff to the Java policy that we agreed on. There are other changes which need some more discussion first. Non-controversial changes ------------------------- First on the agenda was finally merging things from the FOSDEM draft[0] into policy: Java libraries - default build (via ant options / jh_build default) to java 5 bytecode - Depends need more discussion (see later) - happy with the rest GCJ-native - fine Javadoc - javadoc in /usr/share/doc/package/api even if it's in package-doc - non-doc packages don't depend on classpath-doc - depends/links not in policy but best practice Tests - don't specify 'junit' just 'automated tests - may cause package build failure if you are sure about no false positives arch-dependent jars - fine Other simple policy changes: - we can expand location of wrappers to anywhere approved by the FHS - drop the section about executable classes and replace it with executable jars, or symlinks to executable jars which required depending on jarwrapper to get the appropriate binfmt_misc magic - Allow private jars in /usr/share/$package/ I've integrated the above changes with policy (see attached diff), but I've not committed it to svn yet since people are making other changes to java-common. Diff is attached. Javahelper ---------- Any package changes required by these policy changes will be supported by Javahelper. I've put the tutorial for it on the wiki[1]. In most cases it will just be a case of adding the appropriate include if the package uses CDBS. Issues which require some more discussion ----------------------------------------- Recursive classpath detection: It was agreed that some way of automatically generating recursive classpaths so that applications don't need to know about the depends of their depends is desirable. In the long run this will be solved by the Jigsaw project[2,3]. For now, however, the best way to do this is using the Class-path manifest entry. In a few cases (eclipse) the OSGi system is used to load classes. Therefore, it was agreed that helper tools would use any of the above sources (or manually specifying it in the packaging) to retrieve the dependency information and populate all forms. This information can also be used to populate Depends. Transitions/library versioning: Currently we have no coherent plan for orderly transitions when APIs change backward-incompatibly. The versioning in jar names is useless for this. I proposed that either we should drop the versioning requirement or (preferably) move to something more like C library sonaming. This would be in line with what other languages do, for example .NET. This would involve: - an 'API' version, rather than upstream source version - including this version in filenames - including this version in package names - build-depend on something with an unversioned symlink - packaging tools would turn the unversioned path into a versioned path and include the correct package in the depends. This would allow the binary packages to be co-installed so that transitions don't cause flag days and the correct jar would be picked up through the classpath. Most transitions could be handled with binnmus. I've already talked to the FTP masters about this and they are fine with any sensible change along these lines. A proper library system would mean that we can handle backwards-incompatible changes better without having a flag day and most of the required changes can be handled by javahelper and similar tools. Multiarch: Multiarch was presented at debconf this year (see [4] for details). A few changes need to be made to support multiarch (although not many of them need to be made now, multiarch is being staged over a couple of releases). - /usr/lib/jni => /usr/lib/<triple>/jni (path needs to be supported by VMs in squeeze and may be made by packages) - JVMs remain in /usr/lib/jvm - because there may be pure-java packages with cross-arch depends on a JVM and also JNI-using packages with same-arch depends we need to use multi-arch: allowed on the VMs so that we can mark depends arcs on them. This is not something to be done for squeeze. These differences in depends means that we probably will need to keeps depends from library packages to indicate if they require a JVM of the same architecture as the package. I'm not 100% yet how required this is (given that the pure-java ones are arch:all and the others are arch:any). In any case, it's not required for squeeze. ToDos ----- - maven2 needs to be coordinated with Joey Hess to include it as a build class in dh 7. - lintian needs to be updated to avoid warnings about executable jars (I'm about to file a bug) - find unmaintained libraries with no rdeps and propose removal - search for packages which will be rcbuggy with the new changes - doko to find out what the minimum amount of osgi information is Other FYIs: There is a also a beta for jigsaw on PPA[5] Comments please, Matt 0. http://wiki.debian.org/Java/Draft 1. http://wiki.debian.org/Java/Packaging 2. http://openjdk.java.net/projects/jigsaw/ 3. http://openjdk.java.net/projects/modules/samples.html 4. http://lists.debian.org/debian-devel/2009/07/msg00861.html 5. https://edge.launchpad.net/~openjdk/+archive/ppa -- Matthew Johnson
Index: policy.xml
===================================================================
--- policy.xml (revision 9398)
+++ policy.xml (working copy)
@@ -5,11 +5,10 @@
<!ENTITY must "<emphasis>must</emphasis>">
<!ENTITY may "<emphasis>may</emphasis>">
<!ENTITY should "<emphasis>should</emphasis>">
-<!ENTITY jvm "<emphasis>java-virtual-machine</emphasis>">
<!ENTITY j1r "<emphasis>java1-runtime</emphasis>">
<!ENTITY j2r "<emphasis>java2-runtime</emphasis>">
-<!ENTITY jc "<emphasis>java-compiler</emphasis>">
-<!ENTITY j2c "<emphasis>java2-compiler</emphasis>">
+<!ENTITY j5r "<emphasis>java5-runtime</emphasis>">
+<!ENTITY j6r "<emphasis>java6-runtime</emphasis>">
]>
<book>
@@ -93,8 +92,7 @@
<title>Policy</title>
<para>
- Virtual packages are created: &jc;, &j2c;,
- &jvm;, &j1r; and &j2r;.
+ Virtual packages are created: &j1r;, &j2r;, &j5r; & &j6r;.
</para>
<para>
@@ -126,11 +124,9 @@
<title>Virtual machines</title>
<para>
- Java virtual machines &must; provide &jvm; and
- depend on java-common. They can also provide the runtime environment
- that the package contains (&j1r; and/or &j2r;). If it does not
- provide the files itself it &must; depend on the needed runtime
- environment.
+ Java virtual machines &must; depend on java-common and either provide the runtime environment
+ that the package contains (&j1r;, &j2r;, &j5r; and/or &j6r;) or depend on a package
+ which does.
</para>
<para>
@@ -139,7 +135,8 @@
conforming to the Java 2 specification should provide &j2r;.
If a package conforms to both, then it should provide both; however,
packages that do not implement the methods from Java 1.1 that have been
- deprecated in Java 2 must not provide &j1r;.
+ deprecated in Java 2 must not provide &j1r;. Similar rules apply to
+ &j5r; and &j6r;.
</para>
<para>
@@ -171,9 +168,8 @@
<title>Java compilers</title>
<para>
- Java compilers &must; provide &jc; and/or &j2c; and depend on
- java-common. They &must; also depend on the needed runtime environment
- (&j1r; and/or &j2r;).
+ Java compilers &must; depend on
+ java-common. They &must; also depend on the needed runtime environment.
</para>
<para>
@@ -189,25 +185,34 @@
<title>Java programs</title>
<para>
- Programs &must; have executable(s) in
- <filename>/usr/bin</filename> and be executable. They can be Java
- classes (using binfmt_misc) or wrappers. In any case, they &must; run
- without specific environment variables (see
+
+ Programs &must; have executable(s) in one of the directories defined by
+ <ulink
+ url="http://www.debian.org/doc/debian-policy/ch-opersys.html#s9.1";>Policy
+ 9.1</ulink> and be executable. These must either be a wrapper script
+ or a symlink to an executable jar, in which case
+ they must depend on jarwrapper and have a Main-Class attribute in the
+ jar Manifest. In any case, they must run without specific environment
+ variables (see
<ulink url="http://www.debian.org/doc/debian-policy/ch-opersys.html#s10.9";>Policy
- 10.9</ulink>), for instance CLASSPATH. They &must; respect the Policy
- rules for executables (for instance a manual page per executable, see
- <ulink url="http://www.debian.org/doc/debian-policy/ch-docs.html#s13.1";>
- Policy 13.1</ulink>).
+ 10.9</ulink>), for instance CLASSPATH. They must respect
+ the Policy rules for executables (for instance a manual page per
+ executable, see
+ <ulink url="http://www.debian.org/doc/debian-policy/ch-opersys.html#s10.9";>Policy
+ 13.1</ulink>)
</para>
<para>
If they have their own auxiliary classes, they
- &must; be in a jar file in <filename>/usr/share/java</filename>. The
+ &must; either be in a jar file in <filename>/usr/share/java</filename>
+ if they are expected to be used by other packages or in a jar file in
+ <filename>/usr/share/packagename/</filename>. The
name of the jar &should; follow the same naming conventions as for
libraries.
</para>
<para>
- Programs &must; depend on &jvm; and the needed
- runtime environment (&j1r; and/or &j2r;).
+ Programs &must; depend on a concrete runtime implementation with
+ alternate depends for all suitable virtual runtime packages
+ (&j1r;, &j2r;, &j5r; and/or &j6r;).
</para>
<para>
There is no naming rules for programs, they are ordinary programs,
@@ -232,7 +237,7 @@
</para>
<para>
- Their classes &must; be in <filename>jar</filename> archive(s) in
+ Their classes &must; be in jar archive(s) in
the directory <filename>/usr/share/java</filename>,
with the name
<filename>packagename[-extraname]-fullversion.jar</filename>.
@@ -247,6 +252,15 @@
version of the available
<filename>packagename-extraname-version.jar</filename> files.
</para>
+ <para>
+ If a package ships pure-java which is still architecture dependent then
+ the jars &must; be put in the directory
+ <filename>/usr/lib/java</filename>. Very few java packages goes to
+ this category, before doing this, the packager MUST ask on
+ debian-java@lists.debian.org and reach a concensus. This is for example
+ the case for Eclipse SWT which stores native pointer in java types and
+ uses int for that on 32 bit archs and long for 64 bit archs.
+ </para>
<para>
Java libraries &must; depend on the needed runtime environment
@@ -273,36 +287,55 @@
<para>
If a Java library relies on native code, the dynamic libraries
- containing this compiled native code &should; be installed into
+ containing this compiled native code &must; be installed into
the directory <filename>/usr/lib/jni</filename>. 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
+ bytecode (generally libXXX[version]-java) &must; depend on
this package.
</para>
<para>
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
+ together into a single package. Such packages &must; be
architecture-specific and follow the usual libXXX[version]-java
naming convention.
</para>
</sect1>
+ <sect1 id="policy-building">
+ <title>Building Java Packages</title>
+ <para>
+ Java packages &must; Build-Depend on a specific implementation of
+ a JDK and their rules files &must; ensure that the package is built
+ with that JDK, regardless of the current state of the alternatives.
+ </para>
+
+ <para>
+ Unless otherwise not possible, Java libraries &should; be compiled
+ to target Java 5 class-file version.
+ </para>
+
+ <para>
+ Java libraries &should; be compiled with debug symbols enabled.
+ </para>
+
+ </sect1>
+
<sect1 id="policy-politics">
<title>Main, contrib or non-free</title>
<para>
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:
+ rules Debian uses to find if a program is free or not. Most
+ Java libraries/programs should be able to compile and run
+ with at least openjdk. However, keep in mind the following:
</para>
<itemizedlist>
<listitem>
<para>
If your source package can compile (correctly) only
- with non-free tools (the only free Java compilers seem to be
- guavac, gcj and jikes, it cannot go to main. If your package itself
+ with non-free tools, it cannot go to main. If your package itself
is free, it &must; go to contrib.
</para>
</listitem>
@@ -310,16 +343,53 @@
<listitem>
<para>
If your binary package can run only with non-free
- virtual machines
- (<ulink
- url="http://www.gnu.org/software/classpath";>GNU-Classpath</ulink> has
- a list of free versions), it cannot go to main. If
+ virtual machines, it cannot go to main. If
your package itself is free, it &must; go to contrib.
</para>
</listitem>
+ <listitem>
+ <para>
+ Java libraries may go in main if they can compile (correctly)
+ with free tools even if some features require a non-free VM.
+ Programs which use those libraries may only go in main if
+ they can run without using those features.
+ </para>
+ </listitem>
+
</itemizedlist>
</sect1>
+
+ <sect1 id="policy-javadoc">
+ <title>Javadoc</title>
+ <para>
+ Libraries &should; build API documentation in the form of Javadoc. If it is built
+ it &must; be installed in <filename>/usr/share/doc/packagename/api</filename>
+ and &must; be registered with doc-base.
+ </para>
+ <para>
+ Libraries &may; ship the documentation in a separate -doc package, however, the API
+ documentation &must; still be installed to or referenced from
+ <filename>/usr/share/doc/packagename/api</filename> (as opposed to
+ <filename>/usr/share/doc/packagename/api-doc</filename>).
+ </para>
+ </sect1>
+
+ <sect1 id="policy-tests">
+ <title>Automated test suites</title>
+ <para>
+ This refers to both junit tests and other test suites.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Automated tests &should; be run during package builds</para>
+ </listitem>
+ <listitem>
+ <para>Failing tests should only lead to a failing build if the maintainer is sure it is free of false-positives</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
</chapter>
<chapter id="to-discuss">
Attachment:
signature.asc
Description: Digital signature