<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"/usr/share/sgml/docbook/dtd/4.1/docbook.dtd"
[
<!ENTITY must "<emphasis>must</emphasis>">
<!ENTITY may "<emphasis>may</emphasis>">
<!ENTITY should "<emphasis>should</emphasis>">
<!ENTITY jvm "<emphasis>java-virtual-machine</emphasis>">
<!ENTITY j1r "<emphasis>java1-runtime</emphasis>">
<!ENTITY j2r "<emphasis>java2-runtime</emphasis>">
<!ENTITY jc "<emphasis>java-compiler</emphasis>">
<!ENTITY j2c "<emphasis>java2-compiler</emphasis>">
]>

<book>
  <bookinfo>
    <title>Debian policy for Java</title>
    <edition>$Revision:$ $Date:$</edition>
    <authorgroup>
      <author>
	<surname>Lundqvist</surname>
	<firstname>Ola</firstname>
	<authorblurb>
	  <para>
	    <email>opal@debian.org</email>
	  </para>
	  <para>
	    The current author of the java policy.
	  </para>
	</authorblurb>
      </author>
      <author>
	<surname>Bortzmeyer</surname>
	<firstname>Stephane</firstname>
	<authorblurb>
	  <para>
	    <email>bortzmeyer@debian.org</email>
	  </para>
	  <para>
	    The original author of the java policy.
	  </para>
	</authorblurb>
      </author>
      <author>
	<authorblurb>
	  <para>
	    Most issues of the java policy have been discussed on the
	    <email>debian-java@lists.debian.org</email> mailinglist.
	  </para>
	</authorblurb>
      </author>
    </authorgroup>
    <abstract>
      <title>Abstract</title>
      <para>
	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.
      </para>
      <para>
	The policy covers java virtual machines, java compilers, java
	programs and java libraries.
      </para>
    </abstract>
  </bookinfo>
  
  <chapter id="background">
    <title>Background</title>
    
    <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>
      Feel free to report comments, suggestions and/or disagrements to the
      java-common package (<email>java-common@packages.debian.org</email>)
      or the Debian Java mailinglist
      <email>debian-java@lists.debian.org</email>. Change requests should
      be sent as a bug to the java-common package.
    </para>

  </chapter>
  
  <chapter id="policy">
    <title>Policy</title>
    
    <para>
      Virtual packages are created: &jc;, &j2c;,
      &jvm;, &j1r; and &j2r;.
    </para>

    <para>
      All Java code must be shipped as Java bytecode (*.class files, packaged
      in a *.jar archive) and with <quote>Architecture: all</quote>.
    </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.
    </para>

    <para>
      Both are shipped as Java bytecode (<filename>*.class</filename>
      files, packaged in a <filename>*.jar</filename> 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.
    </para>

    <para>
      This policy does not yet address the issue of documentation (for instance
      HTML pages made with javadoc).
    </para>
    
    <sect1 id="policy-vm">
      <title>Virtual machines</title>
      
      <para>
	Java virtual machines &must; provide &jvm; and
	depend on java-common. They can also provide the runtime environment
	that the package contains (&j1r; and/or &j2r;). If it does not
	provide the files itself it &must; depend on the needed runtime
	environment.
      </para>

      <para>
        Packages that contain a runtime conforming to the Java 1.1
	specification should provide &j1r;. Packages that contain a runtime
	conforming to the Java 2 specification should provide &j2r;.
	If a package conforms to both, then it should provide both; however,
	packages that do not implement the methods from Java 1.1 that have been
	deprecated in Java 2 must not provide &j1r;.
      </para>
	
      <para>
	They &should; use <filename>/etc/alternatives</filename>
	for the name 'java' if they are command-line compatible with the
	Sun's java program.
      </para>
      <para>
	They &should; have a CLASSPATH predefined which include the needed
	runtime environment.
      </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>
	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 <filename>/usr/lib/jni</filename> in its
	search path for these dynamic libraries.
      </para>
    </sect1>
    
    <sect1 id="policy-compiler">
      <title>Java compilers</title>
      
      <para>
	Java compilers &must; provide &jc; and/or &j2c; and depend on
	java-common. They &must; also depend on the needed runtime environemnt
	(&j1r; and/or &j2r;).
      </para>

      <para>
	They &should; use <filename>/etc/alternatives</filename>
	for the name 'javac' if they are command-line compatible
	with Sun's JDK javac. They &should; have a CLASSPATH predefined to
	include the java core classes need for the compiler.
      </para>

    </sect1>
    
    <sect1 id="policy-programs">
      <title>Java programs</title>
      
      <para>
	Programs &must; have executable(s) in
	<filename>/usr/bin</filename> and be executable. They can be Java
	classes (using binfmt_misc) or wrappers. In any case, they &must; run
	without specific environment variables (see
	<ulink url="http://www.debian.org/doc/debian-policy/ch-opersys.html#s10.9">Policy
	  10.9</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/ch-docs.html#s13.1">
	  Policy 13.1</ulink>).
      </para>
      <para>
        If they have their own auxiliary classes, they
	&must; be in a jar file in <filename>/usr/share/java</filename>. The
        name of the jar &should; folow the same naming conventions as for
        libraries.
      </para>
      <para>
        Programs &must; depend on &jvm; and the needed
	runtime environment (&j1r; and/or &j2r;).
      </para>
      <para>
        There is no naming rules for programs, they are ordinary programs,
	from the user point of view.
      </para>
    </sect1>
    
    <sect1 id="policy-libraries">
      <title>Java libraries</title>
      
      <para>
	Libraries are not separated between developers (-dev) and users
	versions, since this is meaningless in Java.
      </para>
      
      <para>
	Java libraries packages &must; be named libXXX[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.
      </para>
      
      <para>
	Their classes &must; be in <filename>jar</filename> archive(s) in
	the directory <filename>/usr/share/java</filename>,
	with the name
	<filename>packagename[-extraname]-fullversion.jar</filename>.
	The extraname is optional and used internaly within the package to
	separate the different jars provided by the package. The fullversion
	is the version of that jar file. In some cases that is not the same as
	the package version.
      </para>
      <para>
	Some package &must; also provide a symbolic link from
	<filename>packagename-extraname.jar</filename> to the most compatible
	version of the available
	<filename>packagename-extraname-version.jar</filename> files.
      </para>

      <para>
        Java libraries &must; depend on the needed runtime environment
	(&j1r; and/or &j2r;) but &should; not depend (only suggest)
	java-virtual-machine.
      </para>

      <para>
	All jar files &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 provied by a the runtime environment.
      </para>

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

      <para>
	If a Java library relies on native code, the dynamic libraries
	containing this compiled native code &should; be installed into
	the directory <filename>/usr/lib/jni</filename>.  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.
      </para>
      <para>
	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.
      </para>
    </sect1>

    <sect1 id="policy-politics">
      <title>Main, contrib or non-free</title>
      <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 your source package can compile (correctly) only
	    with non-free tools (the only free Java compilers seem to be
	    guavac, gcj and jikes, it cannot go to main. If your package itself
	    is free, it &must; go to contrib.
	  </para>
	</listitem>
	
	<listitem>
	  <para>
	    If your binary package can run only with non-free
	    virtual machines
	    (<ulink
	    url="http://www.gnu.org/software/classpath">classpath</ulink> has
	    a list of free versions), it cannot go to main. If
	    your package itself is free, it &must; go to contrib.
	  </para>
	</listitem>
      
      </itemizedlist>
    </sect1>
  </chapter>
  
  <chapter id="to-discuss">
    <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 and existance of the repository. It was removed
	  in the latest version.
	</para>
      </listitem>

      <listitem>
	<para>
	  The symbolic links in /usr/share/java be made by a script
	  instead, similar to the c-libraries.
	</para>
      </listitem>

      
      <listitem>
	<para>Core classes (<filename>java.*</filename>). More study
	  needed.</para>
      </listitem>
      
      <listitem>
	<para>
	  Sun's Community Source Licence. Can we use it? How?
	  The 2.3 version of the text can be found 
	  <ulink url="http://wwws.sun.com/software/java2/license.html">here</ulink>.
	</para>
      </listitem>

      <listitem>
	<para>All jars must have a good CLASSPATH documentation, but
	  how should it be documented. The best solution is probably in some
	  computer parsable format to make it even easier for the developer.
	</para>
	<para>It should exist some tool to parse this. How should it
	  work?
	</para>
	<para>Should the tool also be used to create the necessary symbilic
	  links needed by servlets under tomcat?
	</para>
      </listitem>
      
      <listitem>
	<para>
	  Should there be a default classpath, similar to a
	  repository? Which jars should be included in that? A standard and
	  one optional part? If there are a default classpath (in the
	  wrapper) how should it be overridden?
	</para>
      </listitem>      

      <listitem>
	<para>How to check for a good enough jvm, and to select a
	  proper one to use. Are /etc/alternatives not good enough?
	</para>
      </listitem>
      
      <listitem>
	<para>
	  Should the jvm internal classes be possible to
	  override entirely and how?
	</para>
      </listitem>
    </itemizedlist>
  </chapter>
  
  <chapter id="advices">
    <title>Advices to Java packagers</title>
    
    <para>
      Warning: These are just advices, they are not part of the policy.
    </para>
    
    <itemizedlist>
      <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 and 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>
    
  </chapter>
  
</book>