<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD Simplified DocBk XML V3.1.3.6//EN"
 "/usr/lib/sgml/dtd/docbook-xml/sdocbook.dtd"[
<!ENTITY must "<emphasis>must</emphasis>">
<!ENTITY may "<emphasis>may</emphasis>">
<!ENTITY should "<emphasis>should</emphasis>">
<!ENTITY repository "<filename>/usr/share/java/repository</filename>">
]>

<!-- I need a good way to add a <package> tag for names of the Debian
     packages. XML experts may apply. -->

<article>
  <title>PROPOSED Debian policy for Java</title>
  <artheader>
    <author>
      <surname>Bortzmeyer</surname>
      <firstname>Stephane</firstname>
      <authorblurb>
	<para><email>bortzmeyer@debian.org</email></para>
      </authorblurb>
    </author>
    <edition>Version 0.2, 2 september 1999</edition>
  </artheader>

<section><title>Background and metainfo</title>

<para>An important warning: this text is
a <emphasis>proposal</emphasis>. 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.</para>

<para>Feel free to report me (Stephane Bortzmeyer
<email>bortzmeyer@debian.org</email>) comments and disagrements. I'll
put them on this text, if you don't object.</para>

<para>There are several "subpolicies" in Debian. They all want to make
the <ulink url="http://www.debian.org/doc/debian-policy/">Debian
Policy</ulink> 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
<ulink url="http://non-us.debian.org/~hertzog/perl-policy.html/">Perl</ulink>.
</para>

<para>This policy is intended to be in a package java-common, whose maintainer 
will be Java Debian <email>debian-java@lists.debian.org</email>.</para>

</section>

<section><title>The policy</title>

<para>A package java-common is created, containing this policy.</para>

<para>Two virtual packages are created, java-compiler and 
java-virtual-machine.</para>

<para>Java compilers &must; provide java-compiler and depends on
java-common.  They &should; use <filename>/etc/alternatives</filename>
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;.</para>

<para>Java virtual machines &must; provide java-virtual-machine and
depends on java-common and use <filename>/etc/alternatives</filename>
for the name 'java'. They &should; have a CLASSPATH predefined which
includes &repository;.</para>

<para>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.)</para>

<para>If a given source (like the JDK does) brings both a compiler and a
virtual machine, you MAY name the compiler package xxxx-dev.</para>

<para>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. </para>

<para>Both are shipped as Java bytecode (<filename>*.class</filename> files, may
be packaged in a <filename>*.jar</filename> archive) and with an 
"Architecture: all" since Java bytecode is supposed to be portable.</para>

<para>Programs must have executable(s) in
<filename>/usr/bin</filename> and be executable. They can be Java
classes (using binfmt_java, in Debian &lt;= 2.1 or binfmt_misc, in
Debian &gt; 2.1) or wrappers. In any case, they &must; run without
specific environment variables (see <ulink
url="http://www.debian.org/doc/debian-policy/ch3.html#s3.8">Policy
3.8</ulink>), for instance CLASSPATH. They must respect the Policy
rules for executables (for instance a manual page per executable, see
<ulink
url="http://www.debian.org/doc/debian-policy/ch6.html#s6.1">Policy
6.1</ulink>). If they have their own auxiliary classes, they MUST be
either in a <filename>.jar</filename> in
<filename>/usr/share/java/PACKAGE-NAME.jar</filename> or use
the General Java Repository described below. Programs &must; depend on
java-virtual-machine.</para>

<para>Libraries are not separated between developers (-dev) and users
versions, since it is meaningless in Java. Their classes MUST be either:</para>

<itemizedlist>
<listitem><para>in a <filename>.jar</filename> archive 
	  in <filename>/usr/share/java/PACKAGE-NAME.jar</filename></para>
      </listitem>
<listitem><para>or in the General Java Repository.</para></listitem>
</itemizedlist>

<para>In the first case, they &must; have a well-documented CLASSPATH, so 
that developers should know what to add to their wrappers.</para>

<para>This applies only to libraries, <emphasis>not</emphasis> to the core classes.</para>

<para>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).</para>

<para>This policy does not address the issue of documentation (for instance
HTML pages made with javadoc).</para>

<para>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.</para>

<para>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:</para>

<itemizedlist>

<listitem><para>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.</para></listitem>

<listitem><para>If your binary package can run only with non-free
virtual machines (the only free Java virtual machine seems to be
kaffe), it cannot go to main.  If your package itself is free, it must
goes to contrib.</para></listitem>

</itemizedlist>

</section>

<section><title>Issues to discuss</title>

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

<itemizedlist>

<listitem><para>Name of the Repository. There is a proposal to replace
it by simply <filename>/usr/share/java</filename>. (Per Bothner
<email>per@bothner.com</email>)</para></listitem>

<listitem><para>Core classes (<filename>java.*</filename>). More study
needed.</para></listitem>

<listitem><para>Versioned dependencies. Programs may have the need to
depend on a VM &gt;= 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
<email>adam@onshore.com</email>).</para></listitem>

<listitem><para>Sun's Community Source Licence. Can we use it? How?
Where can we <ulink url="http://www.sun.com/software/communitysource/faq.html">
find the text</ulink>?
</para></listitem>

</itemizedlist>

</section>

<section><title>Advices to Java packagers</title>

<para>Warning: they are just advices, they are not part of the policy.</para>

<itemizedlist>

<listitem><para>At the present time, there is no recommandation on
wether a library should use a <filename>.jar</filename> 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).</para></listitem>

<listitem><para>Be sure to manage all dependencies by hand in
<filename>debian/control</filename>. 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).</para></listitem>

<listitem><para>You can suppress many calls in
<filename>debian/rules</filename> which are meaningless for Java, like
dh_strip or dh_shlibdeps.</para></listitem>

<listitem><para>Source package handling is painful, since most Java
upstream programs come with <filename>.class</filename> files. I
suggest to make a new <filename>.orig</filename> tarball after
cleaning them, otherwise, dpkg-source will complain.</para></listitem>

<listitem><para>Java properties files are probably better under
<filename>/etc</filename> and flagged as configuration files (this
will be integrated in the policy, one day).</para>
</listitem>

</itemizedlist>

</section>

</article>