diff options
Diffstat (limited to 'policy.xml')
| -rw-r--r-- | policy.xml | 479 |
1 files changed, 275 insertions, 204 deletions
@@ -4,7 +4,11 @@ <!ENTITY must "<emphasis>must</emphasis>"> <!ENTITY may "<emphasis>may</emphasis>"> <!ENTITY should "<emphasis>should</emphasis>"> -<!ENTITY repository "<filename>/usr/share/java/repository</filename>"> +<!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 @@ -14,212 +18,279 @@ <title>PROPOSED Debian policy for Java</title> <artheader> <author> - <surname>Bortzmeyer</surname> - <firstname>Stephane</firstname> + <surname>Lundqvist</surname> + <firstname>Ola</firstname> <authorblurb> - <para><email>bortzmeyer@debian.org</email></para> + <para><email>opal@debian.org</email></para> </authorblurb> </author> - <edition>Version 0.3, 12 July 2000</edition> - <!-- $Id$ --> + <edition>$Revision:$ $Date:$</edition> + <!-- $Id:$ --> </artheader> - -<section id="policy-bg"><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 id="policy-actual"><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 <= 2.1 or binfmt_misc, in -Debian > 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> + + <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>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 - and the one included in libgcj), it cannot go to main. If your package itself is free, it must -goes 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 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 >= 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 id="policy-advices"><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> - + + <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>Advices to Java packagers</title> + + <para>Warning: they 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> + + </section> + </article> - - - - - - - - |