path: root/policy.sgml

<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD Simplified DocBk XML V3.1.3.6//EN"
 "/usr/share/sgml/docbook/custom/simple/3.1.7.1/sdocbook.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>">
]>

<!-- 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>Lundqvist</surname>
      <firstname>Ola</firstname>
      <authorblurb>
	<para><email>opal@debian.org</email></para>
      </authorblurb>
    </author>
    <edition>$Revision:$ $Date:$</edition>
    <!-- $Id:$ -->
  </artheader>
  
  <section id="policy-bg">
    <title>Background</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 (Ola Lundqvist
      <email>opal@debian.org</email>) comments and disagrements. I'll
      put them on this text and forward them to
      <email>debian-java@lists.debian.org</email>, 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>, when the policy have been
      officially accepted.
    </para>
    
  </section>
  
  <section id="policy-introduction">
    <title>Introduction</title>
    
    <para>A package java-common is created, containing this policy and
      some basic tools.</para>
    
    <para>Virtual packages are created: &jc;, &j2c;,
      &jvm;, &j1r; and &j2r;.</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 &jvm;.
    </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.
    </para>
    
    <para>This policy does not address the issue of documentation (for instance
      HTML pages made with javadoc).</para>

  </section>
  
  <section 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>I &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>

  </section>

  <section 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>

  </section>

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

  <section id="policy-libraries">
    <title>Java libraries</title>

    <para>Libraries are not separated between developers (-dev) and users
      versions, since it 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>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>
    
  </section>

  <section 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 (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; go to contrib.
	</para></listitem>
      
    </itemizedlist>
  </section>
  
  <section id="policy-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?
	  Where can we <ulink url="http://www.sun.com/software/communitysource/faq.html">
	    find the text</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>

  </section>
  
  <section id="policy-advices"><title>Advice to Java packagers</title>
    
    <para>Observe: it is just advice, it is 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>
    
  </section>
  
</article>