Bortzmeyer Stephane bortzmeyer@debian.org Version 0.3, 12 July 2000

An important warning: this text is a proposal. I put it here, publically, so it can be read, discussed, implemented, ignored, etc. It has no sort of endorsement from any authority in Debian or elsewhere. Feel free to report me (Stephane Bortzmeyer bortzmeyer@debian.org) comments and disagrements. I'll put them on this text, if you don't object. 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. This policy is intended to be in a package java-common, whose maintainer will be Java Debian debian-java@lists.debian.org.

A package java-common is created, containing this policy. Two virtual packages are created, java-compiler and java-virtual-machine. Java compilers &must; provide java-compiler and depends on java-common. They &should; use /etc/alternatives for the name 'javac' if they are more or less command-line compatible with Sun's JDK javac. They &should; have a CLASSPATH predefined which includes &repository;. Java virtual machines &must; provide java-virtual-machine and depends on java-common and use /etc/alternatives for the name 'java'. They &should; have a CLASSPATH predefined which includes &repository;. The problem of Java core classes is put on hold. In the mean time, Java virtual machines are requested to come with their own core classes. (Or to depends on another VM, like jikes does.) If a given source (like the JDK does) brings both a compiler and a virtual machine, you MAY name the compiler package xxxx-dev. 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 &must; depend on java-virtual-machine. Both are shipped as Java bytecode (*.class files, may be packaged in a *.jar archive) and with an "Architecture: all" since Java bytecode is supposed to be portable. Programs must have executable(s) in /usr/bin and be executable. They can be Java classes (using binfmt_java, in Debian <= 2.1 or binfmt_misc, in Debian > 2.1) or wrappers. In any case, they &must; run without specific environment variables (see Policy 3.8), for instance CLASSPATH. They must respect the Policy rules for executables (for instance a manual page per executable, see Policy 6.1). If they have their own auxiliary classes, they MUST be either in a .jar in /usr/share/java/PACKAGE-NAME.jar or use the General Java Repository described below. Programs &must; depend on java-virtual-machine. Libraries are not separated between developers (-dev) and users versions, since it is meaningless in Java. Their classes MUST be either: in a .jar archive in /usr/share/java/PACKAGE-NAME.jar or in the General Java Repository. In the first case, they &must; have a well-documented CLASSPATH, so that developers should know what to add to their wrappers. This applies only to libraries, not to the core classes. A General Java Repository is created by java-common in &repository;. Classes which comply with the hierarchical packages naming (for instance, gnu.getopt, com.foo.bar), &may; install classes under it. It is expected that adding &repository; to the CLASSPATH is enough to run any Java program which depends on such classes (this &should; be done by Java virtual machines or compilers). This policy does not address the issue of documentation (for instance HTML pages made with javadoc). There is no naming rules for programs, they are ordinary programs, from the user point of view. Libraries packages &must; be named lib-XXX-java. 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: If you source package can compile (correctly) only with non-free tools (the only free Java compilers seems to be guavac and gcj and may be jikes if it changes its licence), it cannot go to main. If your package itself is free, it must goes to contrib. If your binary package can run only with non-free virtual machines (the only free Java virtual machine seems to be kaffe - and the one included in libgcj), it cannot go to main. If your package itself is free, it must goes to contrib.

The following points are discussions about the policy, either because they have to be studied more, or are controversial. Name of the Repository. There is a proposal to replace it by simply /usr/share/java. (Per Bothner per@bothner.com) Core classes (java.*). More study needed. Versioned dependencies. Programs may have the need to depend on a VM >= 1.2, for instance. Since dpkg does not have versioned provides, it is difficult. Also, many people mistake JDK versions for language versions. More studies of the Java Language Specification needed (Adam Di Carlo adam@onshore.com). Sun's Community Source Licence. Can we use it? How? Where can we find the text?

Warning: they are just advices, they are not part of the policy. At the present time, there is no recommandation on wether a library should use a .jar or the General Java Repository. Some tools may require jars (for instance, for their cryptographical signatures). It is the advice of the original author of this policy that jars are almost useless for a local system (applets on a network are a different thing). Be sure to manage all dependencies by hand in debian/control. Debian development tools cannot find them automatically like they do with C programs and libraries (or like dh_perl does it for Perl, a volunteer to write dh_java would be welcome). You can suppress many calls in debian/rules which are meaningless for Java, like dh_strip or 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).