[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: [PROPOSAL] New Virtual Packages and way to handle Classpath

Hallo debian-java,

After getting all the resonses for the first part of this proposal, I
will try to modify the aproach. I don't think that this will make it
for the sarge release, so I went for a some more changes, which should
be discussed before implemented...

I still think that we can do a policy change before chnaging the
packages, as we donT' have that many packages and patches for the
packages should be easy.

To summarise the changes:

* There will now two ways to get a working JVM:
  . Via a welldefined interface (see below). This interface is
    hopefully as strict enought to work with all unfree VMs
  . by explecitly testing for other know working VMs

I think there is just no way to treat the free ones the same as the
unfree -- sun licensed -- ones.
* To make integration with ant easier, a virtual package
  "ant-buildcompiler" will be added, together with a file, which has
  the required setting (under update alternative).
  JNI header access is now like classpath issues.
  Additionally, a /usr/bin/javac, with certain comandline options
  (just a few) may be added (and java2-compiler virtual package). 
I hope Stephan will add his comments to this, as he maintains ant
and also the CDBS ant classes. Especially, if that handling in 'java
development tools' is enough. I'm not that firm with ant.

IMO, /usr/bin/javac is mainly used for hello world programms and
almost nowher ein scripts, so it's not really nessesary to have
strictly the same comandline options (man pacges will be under update
alternatives as well)

As noone has commented on the 'Jars Description Files' interface, I
suspect that this is good and I will try to implement the 'backend'
until I setup the final proposal for that. PLEASE object NOW, if you
don't agree with this (and not when I've done all the work :).

So, after some trying because of a non working jade, here is the plain
text of my policy editing... enjoy :)

--8<---------:- snip -:---------8<---------:- snip -:---------8<--

   Table of Contents
   1. [1]Background
   2. [2]Policy

        2.1. [3]Virtual machines
        2.2. [4]Java Development Tools
        2.3. [5]Java Browser Plugin
        2.4. [6]Java programs
        2.5. [7]Classpath
        2.6. [8]Java libraries
        2.7. [9]Main, contrib or non-free

   3. [10]Issues to discuss
   4. [11]Advices to Java packagers

Chapter 1. Background

Chapter 2. Policy

All Java code must be shipped as Java bytecode (*.class files, packaged in a
*.jar archive) and with "Architecture: all".

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 are shipped as Java bytecode (*.class files, packaged in a *.jar
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 by the GNU Compiler for Java, in a separate architecture-specific

This policy does not yet address the issue of documentation (for instance
HTML pages made with javadoc).

2.1. Virtual machines

As it is nearly impossible to treat all java virtual maschines the same,
JVMs are seperated into two kinds: sun compatible and not. The first ones
should be used via the below interface, every other virtual maschine has to
be called seperatly.

Sun compatible virtual maschines of a certain java spec version have to
provide the virtual package java-runtime-version (where version is the
curent spec version number) and setup alternatives for /usr/bin/java-version
and the corresponding manpage. They must depend on java-common.

Packages, which want to contribute a alternative for /usr/bin/java and its
manpage must provide java-runtime. The alternative must accept the option
'-classpath', which sets the classpath and autmatically adds the right
rt.jar. The must depend on java-common.

Priorities should be set as follows: highest Spec version multiplied with
100 (1.4 -> 140), free VM may add 30 points, for incomplete spec
compatibility subtract 30. Revisions may add 1 point, as appropiate.

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.

2.2. Java Development Tools

Packages, which supply a java compiler, which can be used with ant, must add
a alternative for /var/lib/java/java-compiler which must be a Jar Descripton
File (see below) and include the variable declaration for ANT_BUILD_COMPILER
with the right value and JNI_INCLUDE, which must point to a dir, which
includes the JNI header files.

Java compilers may provide java2-compiler in which case they must setup a
alternative for /usr/bin/javac and its manpage. They must also depend on the
needed runtime environment and include it automatically on its classpath.
They must depend on java-common.

Packages which setup a alternative for /usr/bin/javadoc must provide

2.3. Java Browser Plugin

If a package provide a Browser plugin, it needs to setup a alternative for
/usr/lib/mozilla/plugins/javaplugin_oji.so and provide java-browser-plugin

2.4. Java programs

Programs must have executable(s) in /usr/bin and be executable. They must
run without specific environment variables (see [16]Policy 10.9), for
instance CLASSPATH. They must respect the Policy rules for executables (for
instance a manual page per executable, see [17]Policy 13.1).

java-common will include a programm, which can be used to setup the
classpath, bootclasspath and properties based on a given packagename. See
the Jar Description File section below.

If they have their own auxiliary classes, they may be in a jar file in
/usr/share/java. The name of the jar should then folow the same naming
conventions as for libraries. Packages should not have public (library) and
private jars together in one package. Instead, the package should be split
in the reusable library jars and a application package. Packages may use the
Jar Description File system to handle their classpath as well.

Programs must depend on the needed runtime environment.

Applications may honor the user set JAVA_HOME evironment variable, while
looking for a useable java virtual maschine. If so, this must be clearly
stated in the manpage and, if possible, at runtime. The programm does not
need to make sanity checks, whether this java virtual maschine will work or

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

2.5. Classpath

To make classpath issues as easy as possible, each package, which includes
public (library) jar files must add a Jar Description File (JarDF) in
/var/lib/java/ and place this jars in /usr/share/java. The JarDF must be
named the same as the package, which contains it. libant1.5-java -

If more than one package includes certain functionality/API, this packages
should use a agreed upon virtual package name and the alternative system to
handle the JarDF with that name.

A JarDF is a sh compatible file, which only sets variables. It must set JARS
and DEPENDS, even if they are empty. It may also add CONTRIB, BOOTCLASSPATH,
PROPERTIES. ANT_BUILD_COMPILER, JNI_INCLUDE and everything which begins with
JAVA_ are reserved. Other variables may be used privatly.

     * JARS must be set with all public jar files, seperated by ':'
     * DEPENDS must be a space or ':' seperated list of packages, which
       this jar needs to have on the classpath at runtime.
       DEPENDS="otherpackage-java libant1.5-java"
     * CONTRIB is a likewise list o packages, to which classpath this
       jars should be added (plugin system). Example: a package adds a
       task to ant. This package would then set CONTRIB="libant1.5-java".
     * Packages, which have contributed their jars to other packages need
       to call the appropiated update-* script in the postrm (in case of
       removal) and postinst (update and install) scripts.
     * BOOTCLASSPATH is a list of jars, as in JARS, which should be added
       to the bootclasspath. This is used to replace JVM API jars, like a
       newer XML parser.
     * PROPERTIES is a list of properties, which should be passed to the
       virtual package and on which this jars depend to be set on

2.6. Java libraries

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

Java libraries packages must be named libXXX[API 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
colisions. 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[API version][-extraname].jar. The extraname is
optional and used internaly within the package to separate the different
jars provided by the package.

Java libraries must depend on the needed runtime environment.

This applies only to libraries, not to the core classes provied 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.

2.7. Main, contrib or non-free


Chapter 3. Issues to discuss

The following points are discussions about the policy, either because they
have to be studied more, or are controversial.

     * Name and existance of the repository. It was removed in the latest
     * Core classes (java.*). More study needed.
     * Sun's Community Source Licence. Can we use it? How? The 2.3
       version of the text can be found [19]here.
     * Should there be a default classpath, similar to a repository?
       Which jars should be included in that? A standard and one optional
       part? If there are a default classpath (in the wrapper) how should
       it be overridden?

Chapter 4. Advices to Java packagers

Warning: These are just advices, they are not part of the policy.

     * Be sure to manage all dependencies by hand in debian/control.
       dh_java makes this a little easier. It can also setup the JarDF.
     * You can suppress many calls in debian/rules which are meaningless
       for Java, like dh_strip and dh_shlibdeps.
     * Source package handling is painful, since most Java upstream
       programs come with .class files. I suggest to make a new .orig
       tarball after cleaning them, otherwise, dpkg-source will complain.
     * Java properties files are probably better under /etc and flagged
       as configuration files (this will be integrated in the policy, one
--8<---------:- snip -:---------8<---------:- snip -:---------8<--

I can also send the diff, but thats not really helpfull, as it is basicly
'rm old, add new'.

Jan Schulz                     jasc@gmx.net
     "Wer nicht fragt, bleibt dumm."

Reply to: