Hallo,
This is a significant rewrite of my previous proposal. To make
discussion alittle easier, I've broken the subject line to tell, that
this is the third request for discussion.
The changes to the second try are
* unfree interfaces are now 'additional to' the normal (free) debian
packages, which provide a certain functionality
* java compilers are now use via ant, via an 'ant environment' or must
be referenced directly (i.e. you need to Build-Depends: on jikes
and not on java2-compiler)
* interfaces to unfree VM and ant environments are now named "unfree",
at least in the policy.
* /usr/bin/java and /usr/bin/javac are described, but should not be
used in packages
* Packages should use a java.home like dir structure, for ants sake
(see my other posting about how ant handles javadoc and java tasks)
This has IMO the advantage, that you know the build environment and
the runtime "bin/java", so that policy doesn't need to make any
requirements to the comandline syntax.
The only addition I've thought of would be make bin/java and
bin/javadoc failsave in case of a unknown comandlien option, so tht
calls from ant will work.
* rename JarDF to java config files and use the name java-config to
access that data.
This was nessesary, as this files handle now the ant environment as
well. java-config will be written by me and should be added to
java-common.
* droped BOOTCLASSPATH and PROPERTIES
* added a chapter on 'building java package', which should make
'testing' with new VM easier.
* deleted stuff, which seems "out of date" like the 'open questions',
which are handled in the java FAQ.
* metions 'to be written' dh_java and the ant classes in the CDBS
As a brief idea, how I think a transition should take place (after and
if we have agreed upon a new debian java policy)
* write all the needed scripts and infrastructure
* write patches for mpkg-j2sdk and include it in debian
* write patches for all runtime environments and setup 'ant environments'
* add the java-config files to libraries and change to the new build
system.
[until here, we shouldn't have any breaking changes]
* convert the applications to the new system
and her enow the 3 attempt for a new debian java policy:
--8<---------:- snip -:---------8<---------:- snip -:---------8<--
Debian policy for Java
Ola Lundqvist
Stephane Bortzmeyer
Abstract
This is the java policy for Debian. It begins with a
background description, continues with the real policy, some
issues to discuss and ends with some advices to java
packagers.
The policy covers java virtual machines, java compilers, java
programs and java libraries.
_______________________________________________________________
Table of Contents
1. Background
2. Policy
2.1. Virtual machines and runtime environments
2.1.1. bin/java
2.1.2. bin/java "unfree" interface
2.1.3. JNI library path
2.2. Java Development Tools
2.2.1. Ant Environment
2.2.2. Ant environment "unfree" interface
2.2.3. javac and javadoc tools
2.3. Java Browser Plugin
2.4. Classpath
2.5. Java libraries
2.6. Java programs
2.7. Building Java packages
2.8. Main, contrib or non-free
3. Advices to Java packagers
_________________________________________________________
Chapter 1. Background
There are several "subpolicies" in Debian. They all want to make the
Debian Policy 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
Perl.
Feel free to report comments, suggestions and/or disagrements to the
java-common package (<[EMAIL PROTECTED]>) or the
Debian Java mailinglist <[EMAIL PROTECTED]>. Change
requests should be sent as a bug to the java-common package.
_________________________________________________________
Chapter 2. Policy
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 package.
This policy does not yet address the issue of documentation (for
instance HTML pages made with javadoc).
_________________________________________________________
2.1. Java virtual machines and runtime environments
Java virtual maschines and java runtimes environments are tightly
linked, so it makes no sense to seperate them. Therefore only the java
runtime environment is used to describe the command java.
As it is nearly impossible to treat all java virtual maschines the
same, JVMs are seperated into two kinds: sun compatible and not.
Packages should access sun compatible java virtual maschiens via the
described "unfree" interfaces below.
Other virtual maschines should be tested seperatly and, if the VM
can be used to run the code, then accesed via their main binary, not
via the alternative system.
_________________________________________________________
2.1.1. bin/java
A alternative for /usr/bin/java and the corresponding manpage should
be setup by every package, which provides java2-runtime. This comand
should not be used by any debian package.
All java virtual maschines must setup a dir struckture in
/usr/lib/name (where name is the version of the virtual maschine)
with this content: bin/java, which is a symlink to the virtual
maschine binary. They must set the java.home property to
/usr/lib/name.
All java virtual maschines must depend on java-common.
_________________________________________________________
2.1.2. bin/java "unfree" interface
To make it poosible to use java virtual maschines, which can't be
distributed by debian, a "unfree" interface is added, which should
be used to access such java virtual maschines.
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 may add a
alternative for /usr/bin/java and its manpage and provide
java2-runtime.
Priorities should be set as follows: highest spec/API version
multiplied with 100 (1.4 -> 140), free VM may add 30 points, for
incomplete spec/API compatibility subtract 40. Revisions may add 1
point, as appropiate.
_________________________________________________________
2.1.3. JNI library path
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, even if
that has to be setup via a wrapper scripts.
_________________________________________________________
2.2. Java Development Tools
As there is almost no control over different java compilers, package
should only use ant to compile and build java packages, but not
javac directly. The ant build.compiler is handled via the
java-config system (see below). For java development kits, which
aren't distributable by debian the "unfree" interface for ant
environments should be used.
_________________________________________________________
2.2.1. Ant Environment
Packages, which can be used with ant to compile java code must setup
a directory structure in /usr/lib/name (where name is the name of
the corresponding virtual maschine (see above)), which includes
bin/javadoc, which should be of the same API version as the virtual
maschine, includes and includes/linux, with the JNI header files.
They also must include a java-config file (see below) which includes
the variable declaration for JAVA_HOME, which points to
/usr/lib/name, ANT_BUILD_COMPILER with the name or full qualified
classname of the java compiler and the JARS entry, with the jars
needed to run this java compiler.
If the package can't satisfy everything of this requirements by
themself, it must depend on other packages, which include the
missing functionality, and setup the directory structure and
alternatives accordingly.
Packages must depend on java-common.
_________________________________________________________
2.2.2. Ant environment "unfree" interface
Sun compatible Java development environments, which can't be
distributed by debian and which satisfy the above requirements for
the ant environment, should setup their java-config file as a
alternative for /usr/share/java-config/ant-unfree-dev-env-version
and provide java-ant-environment-version (where version indicates,
that java files developed for this java version can be compiled).
_________________________________________________________
2.2.3. javac and javadoc tools
Packages, which include a Java compilers may provide java2-compiler
in which case they must setup a alternative for /usr/bin/javac and
its manpage. They must depend on java-common.
Packages which setup a alternative for /usr/bin/javadoc must provide
javadoc.
_________________________________________________________
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. Classpath
To make classpath issues as easy as possible, each package, which
includes public (library) jar files must add a java-config file in
/var/share/java-config and place this jars in /usr/share/java. The
java-config file must be named the same as the package, which
contains it. Example: libant1.5-java includes the java-config file
/var/share/java-config/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 java-config file with that name.
A java-config file 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. ANT_BUILD_COMPILER, and every variable
beginning with "JAVA_" are reserved. Other variables may be used
privatly.
The content of a java-config file is as follows:
* JARS must be set with all public jar files, seperated by
':'
JARS="/usr/share/java/first.jar:/usr/share/java/second.jar
"
* 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.
_________________________________________________________
2.5. 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 working runtime
environments, including the virtual package names of working
versions of the "unfree" bin/java interface.
This applies only to libraries, not to the core classes provied by
the runtime environments.
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.6. Java programs
Programs must have executable(s) in /usr/bin and be executable. 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).
java-common includes the java-config programm, which should be used
to setup the CLASSPATH environment variable.
If programms have their own auxiliary classes, they may be in a jar
file in /usr/share/java. The name of the jar should then follow the
same naming conventions as for libraries. Packages should not have
public (library) jars and private jars together in one package.
Instead, the package should be split into the reusable library
package and a application package. Java programms may use the
java-config file system to handle their classpath.
Programs must depend on the needed runtime environments, including
working versions if the bin/java unfree interfaces.
As "unfree" virtual maschines of a certain version almost certainly
will run code developed for this version, all packages must also use
kown working "unfree" interfaces, when they search for a possible
java binary. Other java virtual maschines should be used as tightly
as possible (use /usr/bin/kaffe-1.1 instead of /usr/bin/kaffe).
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 not.
There is no naming rules for programs, they are ordinary programs,
from the user point of view.
_________________________________________________________
2.7. Building Java packages
A package should use ant to build a package and build depend on the
required ant environments, including virtual packages for the
"unfree" environments. They should use /usr/bin/java-config to
access this ant build environment.
If a package doesn't used ant to build the package, it needs to
build depend on a specific package for each required tool and call
this tools directly.
_________________________________________________________
2.8. Main, contrib or non-free
About politics: packaging Java stuff changes nothing to the rules
Debian uses to find if a program is free or not. 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.
* 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.
_________________________________________________________
Chapter 3. Advices to Java packagers
Warning: These are just advices, they are not part of the policy.
* Be sure to manage all build and runtime dependencies by
hand in debian/control. dh_java makes this task a little
easier. It can also setup the java-config file. The CDBS
includes helper classes to handle ant based sources.
* 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 day).
--8<---------:- snip -:---------8<---------:- snip -:---------8<--
Thanks for reading through it :)
Jan
--
Jan Schulz [EMAIL PROTECTED]
"Wer nicht fragt, bleibt dumm."
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
