[PROPOSAL] 4. RfD for a new debian java policy
Hallo,
This is the forth attempt of a rewrite of the current debian java
policy. The chanegs to the third version are:
* droped the 'unfree' interfaces
* dropped all the virtual package names (apart from browser plugin)
* a 'java virtual machine' is no handled by a 'findjava' script, which
will be included in java-common. Packages must use this script.
* added ANT_BOOTCLASPATH to be used with ant.
* made some clarifications:
. apps, which incldue the possibility of plugins must use the
java-config system to set their CP.
. Packages must depend on all tested JVMs
. API version in packages
* mention python instead of 'only other' in the preface.
* other minor changes, which I can't remember...
I would like to include somewhere teh naming and way to include
'unfree' JVM, but I haven't found a proper place. I would like to make
that a little more specific, so that we only use one way to access
them (otehrwise there will be some people, who alien a rpm). Any
suggestions welcome.
My next step will be the findjava script, which will start out very
basic, e.g. without any other options.
If this text meets the expectations, I will file a bugreport against
java-common and the rest can be handled via the BTS.
The proposal:
--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. Java virtual machines and runtime environments
2.1.1. bin/java
2.1.2. JNI library path
2.2. Java Development Tools
2.2.1. Ant Environment
2.2.2. 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. There are subpolicy for a
programming language: Perl, Python
Feel free to report comments, suggestions and/or disagrements
to the java-common package (<java-common@packages.debian.org>)
or the Debian Java mailinglist <debian-java@lists.debian.org>.
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
As we can't make sure, that a java programm or library will
run with all available java virtual machines all java virtual
machine are treated seperatly.
_________________________________________________________
2.1.1. bin/java
Packages, which provide a java virtual machine have to setup a
java-config file (see below) for this virtual machine. The
java-config file must include the variable declaration for
JAVA_COMMAND, which has to point to the java virtual machine
binary/wrapper. Other variables, as stated in the findjava man
page, may be added, if the java virtual machine can fullfill
the requirements for this variables.
A alternative for /usr/bin/java and the corresponding manpage
may be setup by every package, which provides a java virtual
machine. The priority should be set to 200. This command must
not be used by any debian package.
All java virtual machines must setup a dir structure in
/usr/lib/name (where name is the name of the java virtual
machine) with this content: bin/java, which starts the java
virtual machine. They must set the java.home property to
/usr/lib/name.
All java virtual machines must depend on java-common.
_________________________________________________________
2.1.2. 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 java 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 either use /usr/bin/ant to compile and build
java packages, or directly access the required tools. They
must not use the alternative managed /usr/bin/javadoc or
/usr/bin/javac. The ant environement is handled via the
java-config system (see below).
_________________________________________________________
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 java virtual machine (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 short name or
full qualified classname of the java compiler,
ANT_BOOTCLASSPATH, which is a JARS-like list of the
bootclasspath jars 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
accordingly.
Packages must depend on java-common.
_________________________________________________________
2.2.2. javac and javadoc tools
Packages, which include a Java compilers may setup a
alternative for /usr/bin/javac and its manpage. Packages may
setup a alternative for /usr/bin/javadoc. In both cases, the
priority should be 200. Packages must not use this filenames
to access a java compiler or 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. In the case of a library package, it must set JARS
and DEPENDS, even if they are empty. It may also add CONTRIB.
ANT_BUILD_COMPILER, ANT_BOOTCLASSPATH 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 colon 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 API version
refers to the version of the public API of that package. 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.
A package must depend on the disjunction of all JVMs with
which it has been tested succesfully.
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).
Packages, which need to find a java virtual machine in the
startscript of their programm must use the /usr/bin/findjava
programm for this task.
The /usr/bin/java-config programm should be used to setup the
classpath.
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
this part of the classpath. In case of programms, which can be
enchanced by plugins, they must use the java-config file
system.
A package must depend on the disjunction of all JVMs with
which it has been tested succesfully.
Applications may honor the user set JAVA_HOME evironment
variable. 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.
Application, which allow to pre-set or overwrite the CLASSPATH
need to state this in the manpage and, if possible, at
runtime.
There is no naming rules for programs, they are ordinary
programs, from the user point of view.
_________________________________________________________
2.7. Building Java packages
If a package uses ant to build a package it must build depend
on the required ant environments and 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 (correctly) only with
non-free java virtual machine 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<--
Nice greetings, Jan
--
Jan Schulz jasc@gmx.net
"Wer nicht fragt, bleibt dumm."
Reply to: