diff options
| -rw-r--r-- | debian/.cvsignore | 3 | ||||
| -rw-r--r-- | debian/changelog | 6 | ||||
| -rw-r--r-- | debian/control | 28 | ||||
| -rw-r--r-- | debian/java-common.dirs | 2 | ||||
| -rw-r--r-- | policy.sgml | 479 | ||||
| -rw-r--r-- | policy.xml | 479 | ||||
| -rwxr-xr-x | publish.sh | 5 |
7 files changed, 591 insertions, 411 deletions
diff --git a/debian/.cvsignore b/debian/.cvsignore index 3cb342d..b762e8f 100644 --- a/debian/.cvsignore +++ b/debian/.cvsignore @@ -4,3 +4,6 @@ files java-common java-virtual-machine-dummy java-compiler-dummy +java2-compiler-dummy +java1-runtime-dummy +java2-runtime-dummy diff --git a/debian/changelog b/debian/changelog index 8a1f597..6aee35b 100644 --- a/debian/changelog +++ b/debian/changelog @@ -2,13 +2,17 @@ java-common (0.8) unstable; urgency=low * Moved java-compiler-dummy to java-common. * Moved java-virtual-machine-dummy to java-common. + * Created java1-runtime-dummy, java2-runtime-dummy and + java2-compiler-dummy. * Moved dummy config files, closes: #55527, #55747. * Fixed manpage, closes: #55525. * Fixed the copyright file, closes: #55524. * No I will not add a jar hook. It does not require any special classpaths and the jar program should exist in the package that provides the binary, closes: #81647. - * The updated java policy will be updated soon. + * Updated the java policy. This is a major rewrite from all the information + that people seems to have agreed upon, in the debian-java@lists.debian.org + mailinglist. Closes: #107809, #107810. -- Ola Lundqvist <opal@debian.org> Mon, 01 Oct 2001 13:43:56 +0200 diff --git a/debian/control b/debian/control index b177992..cdf095d 100644 --- a/debian/control +++ b/debian/control @@ -2,7 +2,7 @@ Source: java-common Section: misc Priority: optional Maintainer: Ola Lundqvist <opal@debian.org> -Build-Depends: debhelper (>> 3.0.0), jade, jadetex, tetex-bin, debiandoc-sgml, sp, lynx, docbook-xml-simple, dpsyco-devel +Build-Depends-Indep: debhelper (>> 3.0.0), jade, jadetex, tetex-bin, debiandoc-sgml, sp, lynx, docbook-xml-simple, dpsyco-devel Standards-Version: 3.5.2 Package: java-common @@ -27,3 +27,29 @@ Provides: java-compiler Description: Dummy Java compiler This package is only to respect the dependencies rules. Install it only if you have a real Java compiler. + +Package: java2-compiler-dummy +Architecture: all +Depends: java-common +Provides: java2-compiler +Description: Dummy Java compiler + This package is only to respect the dependencies. + Install it only if you have a real Java version 2 compiler. + +Package: java1-runtime-dummy +Architecture: all +Depends: java-virtual-machine +Provides: java1-runtime +Description: Dummy java 1 runtime environment. + This package is only to respect the dependenies. + Install it only if you have a real Java version 1 + compliant environment. + +Package: java2-runtime-dummy +Architecture: all +Depends: java-virtual-machine +Provides: java2-runtime +Description: Dummy java 2 runtime environment. + This package is only to respect the dependenies. + Install it only if you have a real Java version 2 + compliant environment. diff --git a/debian/java-common.dirs b/debian/java-common.dirs index bae4823..13c9f03 100644 --- a/debian/java-common.dirs +++ b/debian/java-common.dirs @@ -1 +1 @@ -usr/share/java/repository +usr/share/java diff --git a/policy.sgml b/policy.sgml index 17edfe0..b3daf5b 100644 --- a/policy.sgml +++ b/policy.sgml @@ -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> - - - - - - - - @@ -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> - - - - - - - - diff --git a/publish.sh b/publish.sh new file mode 100755 index 0000000..ee95139 --- /dev/null +++ b/publish.sh @@ -0,0 +1,5 @@ +#!/bin/sh + +make policy.html +FILES="$(find . -maxdepth 1 -type f -name '*.html' -printf '%f ')" +scp $FILES opal@master.debian.org:public_html/java |