Bug#548755: [Policy Update] Updating the java-policy to reflect current practices + small changes.
Package: java-common
Version: 0.33
Severity: normal
Tags: patch
Hi
I have made an attempt to bring the java policy up to date and made some
small changes to make it more compatible with the Debian Policy.
Attached is a patch and a list of the changes. I have also provided these
along with how it would look if this patch is applied at the following
website [#1].
To those of you, who already read my previous draft, please note that I
modified section [2] and [2.1] to [2.4]. The modifications done to
[2] and [2.2] to [2.4] is merely to mention the "headless" counterpart of
the javaX-runtime packages. However [2.1] has received a few more
modifications, where I have spelled out when a VM providing package may
provide a headless vs a non-headless.
~Niels
[#1] http://www.student.dtu.dk/~s072425/debian/policy/
-- System Information:
Debian Release: squeeze/sid
APT prefers testing
APT policy: (990, 'testing'), (500, 'unstable'), (500, 'stable'), (1, 'experimental')
Architecture: i386 (i686)
Kernel: Linux 2.6.30-1-686 (SMP w/2 CPU cores)
Locale: LANG=en_DK.UTF-8, LC_CTYPE=en_DK.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
java-common depends on no packages.
java-common recommends no packages.
Versions of packages java-common suggests:
ii default-jre 1.6-33 Standard Java or Java compatible R
ii equivs 2.0.7-0.1 Circumvent Debian package dependen
-- no debconf information
Index: policy.xml
===================================================================
--- policy.xml (revision 10638)
+++ policy.xml (working copy)
@@ -2,14 +2,21 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"/usr/share/sgml/docbook/dtd/4.1/docbook.dtd"
[
+<!ENTITY may "<emphasis>may</emphasis>">
<!ENTITY must "<emphasis>must</emphasis>">
-<!ENTITY may "<emphasis>may</emphasis>">
+<!ENTITY mustnot "<emphasis>must not</emphasis>">
+<!ENTITY not "<emphasis>not</emphasis>">
<!ENTITY should "<emphasis>should</emphasis>">
-<!ENTITY jvm "<emphasis>java-virtual-machine</emphasis>">
<!ENTITY j1r "<emphasis>java1-runtime</emphasis>">
+<!ENTITY j1rhless "<emphasis>java1-runtime-headless</emphasis>">
<!ENTITY j2r "<emphasis>java2-runtime</emphasis>">
-<!ENTITY jc "<emphasis>java-compiler</emphasis>">
-<!ENTITY j2c "<emphasis>java2-compiler</emphasis>">
+<!ENTITY j2rhless "<emphasis>java2-runtime-headless</emphasis>">
+<!ENTITY djdk "<emphasis>default-jdk</emphasis>">
+<!ENTITY djdkbd "<emphasis>default-jdk-builddep</emphasis>">
+<!ENTITY djhless "<emphasis>default-jre-headless</emphasis>">
+<!ENTITY djre "<emphasis>default-jre</emphasis>">
+<!ENTITY debpol "http://www.debian.org/doc/debian-policy";>
+<!ENTITY d-j-list "<email>debian-java@lists.debian.org</email>" >
]>
<book>
@@ -18,6 +25,18 @@
<edition>$Revision:$ $Date:$</edition>
<authorgroup>
<author>
+ <surname>Thykier</surname>
+ <firstname>Niels</firstname>
+ <authorblurb>
+ <para>
+ <email>niels@thykier.net</email>
+ </para>
+ <para>
+ The current author of the java policy.
+ </para>
+ </authorblurb>
+ </author>
+ <author>
<surname>Lundqvist</surname>
<firstname>Ola</firstname>
<authorblurb>
@@ -25,7 +44,7 @@
<email>opal@debian.org</email>
</para>
<para>
- The current author of the java policy.
+ The previous author of the java policy.
</para>
</authorblurb>
</author>
@@ -69,21 +88,15 @@
<para>
There are several "subpolicies" in Debian. They all want to make
- the
- <ulink url="http://www.debian.org/doc/debian-policy/";>Debian
- Policy</ulink>
- more precise when it comes to a specific subject. See
- the Emacs subpolicy in package emacsen-common for instance. As far as
- I know, the only subpolicy for a programming language, is that of
- <ulink
- url="http://non-us.debian.org/~hertzog/perl-policy.html/";>Perl</ulink>.
+ the <ulink url="&debpol;">Debian Policy</ulink> more precise
+ when it comes to a specific subject. See the Emacs subpolicy in
+ package emacsen-common for instance.
</para>
<para>
Feel free to report comments, suggestions and/or disagreements to the
java-common package (<email>java-common@packages.debian.org</email>)
- or the Debian Java mailing list
- <email>debian-java@lists.debian.org</email>. Change requests should
+ or the Debian Java mailing list &d-j-list;. Change requests should
be sent as a bug to the java-common package.
</para>
@@ -93,12 +106,38 @@
<title>Policy</title>
<para>
- Virtual packages are created: &jc;, &j2c;,
- &jvm;, &j1r; and &j2r;.
+ Virtual packages are created: &j1r;, &j1rhless;, &j2r; &
+ &j2rhless;.
</para>
<para>
- All Java code must be shipped as Java bytecode (*.class files, packaged
+ The Java Team maintain a set of non-virtual packages providing a
+ default-java and &may; be used as a concrete jave
+ implementation. They depend on a java implementation and provide
+ a symlink from <filename>/usr/lib/jvm/default-java</filename> to
+ the selected java implementation.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ &djre; - Provides a Java Runtime with X11 support.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ &djhless; - Provides a Java Runtime without X11 support.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ &djdk; - Provides Java Development Kit.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ All Java code &must; be shipped as Java bytecode (*.class files, packaged
in a *.jar archive) and with <quote>Architecture: all</quote>.
</para>
@@ -112,7 +151,7 @@
Both are shipped as Java bytecode (<filename>*.class</filename>
files, packaged in a <filename>*.jar</filename> archive) and with
an "Architecture: all" since Java bytecode is supposed to be portable.
- It may additionally be shipped as machine code, as produced for example
+ It &may; additionally be shipped as machine code, as produced for example
by the GNU Compiler for Java, in a separate architecture-specific
package.
</para>
@@ -126,25 +165,38 @@
<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;, &j1rhless;, &j2r; or/and &j2rhless;) or depend on a
+ package which does.
</para>
<para>
Packages that contain a runtime conforming to the Java 1.1
- specification should provide &j1r;. Packages that contain a runtime
- 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;.
+ specification &should; provide &j1r; or &j1rhless;. Packages
+ that contain a runtime conforming to the Java 2 specification
+ &should; provide &j2r; or &j2rhless;. If a package conforms to
+ both, then it &should; provide both java versions; however,
+ packages that do not implement the methods from Java 1.1 that
+ have been deprecated in Java 2 &mustnot; provide &j1r; nor
+ &j1rhless;.
</para>
-
+
<para>
- They &should; use <filename>/etc/alternatives</filename>
- for the name 'java' if they are command-line compatible with the
+ A package that provides &j1r; &must; also provide &j1rhless;
+ or depend on a package that does. This rule applies
+ analogously to &j2r; and &j2rhless;.
+ </para>
+
+ <para>
+ A package that does not support running X11 java applications
+ &mustnot; provide &j1r; nor &j2r;. Instead it &should; provide
+ the headless versions.
+ </para>
+
+ <para>
+ They &should; use <filename>/etc/alternatives</filename> for
+ the name 'java' if they are command-line compatible with the
Sun's java program.
</para>
<para>
@@ -171,15 +223,14 @@
<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>
- They &should; use <filename>/etc/alternatives</filename>
- for the name 'javac' if they are command-line compatible
- with Sun's JDK javac. They &should; have a CLASSPATH predefined to
+ They &should; use <filename>/etc/alternatives</filename> for
+ the name 'javac' if they are command-line compatible with
+ Sun's JDK javac. They &should; have a CLASSPATH predefined to
include the java core classes need for the compiler.
</para>
@@ -189,41 +240,56 @@
<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
- <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>).
+ Programs &must; have executable(s) in one of the directories defined by
+ <ulink url="&debpol;/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="&debpol;/ch-opersys.html#s9.9">Policy
+ 9.9</ulink>), for instance CLASSPATH. They must respect the
+ Policy rules for executables (for instance a manual page per
+ executable, see
+ <ulink url="&debpol;/ch-opersys.html#s12.1">Policy 12.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
- name of the jar &should; follow the same naming conventions as for
- libraries.
+ If they have their own auxiliary classes, they &must; either
+ be in a jar file in
+ <filename>/usr/share/packagename</filename> or - if they are
+ expected to be by other packages - in
+ <filename>/usr/share/java</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;, &j1rhless;, &j2r; and/or &j2rhless;).
</para>
<para>
- There is no naming rules for programs, they are ordinary programs,
- from the user point of view.
+ There is no naming rules for programs, they are ordinary
+ programs, from the user point of view.
</para>
+ <para>
+ Programs &must; be in the Section appropiate for the given
+ program. (See <ulink url="&debpol;/ch-archive.html#s-subsections">
+ Policy 2.4</ulink> for the list of sections).
+ </para>
</sect1>
<sect1 id="policy-libraries">
<title>Java libraries</title>
<para>
- Libraries are not separated between developers (-dev) and users
- versions, since this is meaningless in Java.
+ Libraries are not separated between developers (-dev) and
+ users versions, since this is meaningless in Java.
</para>
<para>
+ Libraries &must; be in the "java" section.
+ </para>
+
+ <para>
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
@@ -232,26 +298,35 @@
</para>
<para>
- Their classes &must; be in <filename>jar</filename> archive(s) in
- the directory <filename>/usr/share/java</filename>,
- with the name
+ 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>.
- 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.
+ 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.
</para>
<para>
Some package &must; also provide a symbolic link from
- <filename>packagename-extraname.jar</filename> to the most compatible
- version of the available
- <filename>packagename-extraname-version.jar</filename> files.
+ <filename>packagename[-extraname].jar</filename> to the most
+ compatible 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 &d-j-list; 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
- (&j1r; and/or &j2r;) but &should; not depend (only suggest)
- java-virtual-machine.
+ Java libraries &must; depend on a concrete runtime
+ implementation with alternate depends for all suitable virtual
+ runtime packages (&j1r;, &j1rhless;, &j2r; and/or &j2rhless;).
</para>
<para>
@@ -260,7 +335,7 @@
</para>
<para>
- This applies only to libraries, <emphasis>not</emphasis> to the core
+ This applies only to libraries, ¬ to the core
classes provided by a the runtime environment.
</para>
@@ -273,51 +348,108 @@
<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
+ Very small packages &may; bundle the Java code and the native code
+ 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>
+ Java libraries &should; be compiled with debug symbols enabled.
+ </para>
+ <sect2 id="policy-building-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; either
+ install a symlink in
+ <filename>/usr/share/doc/libpackagename/api</filename>
+ and depend on the library package or install the javadoc
+ directly into
+ <filename>/usr/share/doc/libpackagename/api</filename>.
+ </para>
+
+ </sect2>
+ <sect2 id="policy-building-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 &may; lead to a failing build if the
+ maintainer is sure it is free of false-positives.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </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
- is free, it &must; go to contrib.
+ 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.
</para>
</listitem>
<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
- your package itself is free, it &must; go to contrib.
+ If your binary package can run only with non-free 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>
</chapter>
@@ -354,20 +486,21 @@
<para>
Sun's Community Source Licence. Can we use it? How?
The 2.3 version of the text can be found
- <ulink url="http://wwws.sun.com/software/java2/license.html";>here</ulink>.
+ <ulink url="http://java.sun.com/j2se/1.5.0/scsl_5.0-license.txt";>here</ulink>.
</para>
</listitem>
<listitem>
- <para>All jars must have a good CLASSPATH documentation, but
+ <para>All jars &must; have a good CLASSPATH documentation, but
how should it be documented. The best solution is probably in some
computer parsable format to make it even easier for the developer.
</para>
<para>It should exist some tool to parse this. How should it
work?
</para>
- <para>Should the tool also be used to create the necessary symbolic
- links needed by servlets under tomcat?
+ <para>
+ Should the tool also be used to create the necessary
+ symbolic links needed by servlets under tomcat?
</para>
</listitem>
@@ -381,8 +514,9 @@
</listitem>
<listitem>
- <para>How to check for a good enough jvm, and to select a
- proper one to use. Are /etc/alternatives not good enough?
+ <para>
+ How to check for a good enough jvm, and to select a proper
+ one to use. Are /etc/alternatives not good enough?
</para>
</listitem>
@@ -424,8 +558,8 @@
<listitem>
<para>
Source package handling is painful, since most Java
- upstream programs come with <filename>.class</filename> files. I
- suggest to make a new <filename>.orig</filename> tarball after
+ upstream programs come with <filename>.class</filename> files. It
+ is suggested to make a new <filename>.orig</filename> tarball after
cleaning them, otherwise, dpkg-source will complain.
</para>
</listitem>
Java-Policy:
[Suggested Changes]
* Added new section [2.5] about building java packages,
handling javadoc and test suites. The previous [2.5]
"Main, contrib or non-free" is now [2.6].
* Mentioned the default-java packages, what the
provide and that they may be used as an concrete
java implementation. [2]
* Mentioned the headless versions of java1-runtime
and java2-runtime. [2], [2.1], [2.2], [2.3], [2.4]
* Added that Libraries must go in the java section,
while java programs are not limited to the java
section. [2.3], [2.4]
* Removed the virtual packages "java-compiler",
"java2-compiler" and "java-virtual-machine"; none of
them are used anymore.
[2], [2.1], [2.2], [2.3], [2.4]
* Programs may now be installed in any place the Debian
Policy allows it rather than just /usr/bin. [2.3]
(Closes: #395372)
* Programs must either install wrapper scripts or symlink
to an executable jar with a Main-Class attribute
and depend on jarwrapper. [2.3]
(Closes: #227594)
* Added note that java code may be installed in
/usr/lib/java rather than /usr/share/java only if
there has been a concensus about it in
debian-java@l.d.o and the java code is arch-dependent.
[2.4]
* Java libraries depending on native code must install
them into /usr/lib/jni. (Up from a should) [2.4]
* Arch-independent library packages must depend on
the arch-dependent part. (Up from a should) [2.4]
* Small libraries may still ship the native code
together with the bytecode but must be
architecture-specific. (Up from should) [2.4]
* Packages must Build-Depend on a specific implementation
of a JDK and must ensure that the build uses that JDK.
[2.4]
* Libraries should be built with debug symbols. [2.4]
* Libraries may go into main, if there core functionality
can be compiled with a free java implementation.
Related programs may only go into main, if they can
run without features that requires a non-free java
implementation. [2.6]
* Updated and removed some links.
* Various cosmetic changes.
[Notes]
* This implements most of the modifications changes suggested
by Matthew Johnson <mjj29@debian.org>. See
http://lists.debian.org/debian-java/2009/07/msg00067.html
* This modification is intended to minimize the difference
between the current policy and our current packaging
methods.
-- Niels Thykier <niels@thykier.net> Sat, 28 Sep 2009 17:40:00 +0200
Reply to: