Initial revisiondebian/debian_version_0_2@4

1 files changed, 224 insertions, 0 deletions

diff --git a/policy.xml b/policy.xml
new file mode 100644
index 0000000..221acca
--- /dev/null
+++ b/policy.xml
@@ -0,0 +1,224 @@
+<?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>
+
+
+
+
+
+
+
+