Package: java-common
Version: 0.22
Severity: wishlist
Tags: patch
Here is the discussed proposal java policy as txt and also as tar.gz archive,
including all written scripts and manpages
java-config and java-config(1)
java-config-update and java-config-update(1)
java-config-file(5)
findjava, findjava(1), findjavarc(5) and a test script
dh_java (with inline manpage)
As it is a complete rewrite, I don't include the diff of the policy.xml
Changes to tha last discussed version are minor:
* ant-environment: droped include/linux and added a sentence, that the
JNI Header files should be includeable from there.
* cosmetical errors
* added my name to the author list.
And now the proposed and discussed policy:
-------------------------------------------------------------
Debian policy for Java
Jan Schulz
Ola Lundqvist
Stephane Bortzmeyer
the debian java mailinglist
Abstract
This is the java policy for Debian. It begins with a
background description, continues with the real policy and
ends with some advices to java packagers.
The policy covers java virtual machines, an environment to
compile java programms, 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 other subpolicies for
programming languages: 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
Debian package managment relies havily on the fact that if you
install a piece of software, it will work. This can't be
satisfied by different java virtual machines, even sun derived
ones, so that all java virtual machines 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 with the
JNI header files includeable from there.
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.
If you need jars, which are not in the same package as
programm, 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 should be clearly stated in the manpage and may
state it 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
should state this in the manpage and may state it 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 use ant to build the package, it must
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).
-------------------------------------------------------------
Enjoy, Jan
--
Jan Schulz "Wer nicht fragt, bleibt dumm."
Attachment:
java-policy.tar.gz
Description: Binary data