Date: Fri, 21 May 2004 18:45:06 +0200 (CEST) From: Herve Quiroz <herve.quiroz@esil.univ-mrs.fr> To: FreeBSD-gnats-submit@FreeBSD.org Cc: linimon@FreeBSD.org Subject: docs/67001: [PATCH] Java section of the Porter's Handbook (continued) Message-ID: <200405211645.i4LGj6Pr015633@arabica.esil.univ-mrs.fr> Resent-Message-ID: <200405211650.i4LGoD6r074495@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 67001 >Category: docs >Synopsis: [PATCH] Java section of the Porter's Handbook (continued) >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Fri May 21 09:50:12 PDT 2004 >Closed-Date: >Last-Modified: >Originator: Herve Quiroz >Release: FreeBSD 5.2.1-RELEASE-p5 i386 >Organization: >Environment: System: FreeBSD arabica.esil.univ-mrs.fr 5.2.1-RELEASE-p5 FreeBSD 5.2.1-RELEASE-p5 #3: Thu May 6 20:17:47 CEST 2004 >Description: Here is the second part of the Java section of the Porter's handbook: - Added a table for constants. - Added a "Best practices" subsection that depicts the encouraged policy for Java ports regarding many aspects (location of JAR files, use of PLIST_FILES, category for PRs)... NOTE: There is (again) nothing regarding JAVA_PREFERRED_PORT but now I think we should make a short statement about it. This will probably be part of the next iteration. NOTE2: A lot of information from http://www.freebsd.org/java/docs/howtoports.html is deprecated. IIRC someone already posted something regarding this (with a patch to update it) on the freebsd-java mailing list for review. NOTE3: I had problems referencing sections of the same document. It works for 'html' but not for 'html-split'. Mark Linimon is CC'ed (as we already worked together on the first part) >How-To-Repeat: >Fix: Index: book.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v retrieving revision 1.405 diff -u -r1.405 book.sgml --- book.sgml 21 May 2004 07:10:59 -0000 1.405 +++ book.sgml 21 May 2004 16:27:42 -0000 @@ -4151,6 +4151,108 @@ to get information for debugging your port. It will display the value of many of the forecited variables.</para> + <para>Additionally, the following constants are defined so all Java ports + may be installed in a consistent way:</para> + + <table frame="none"> + <title>Constants defined for ports that use Java</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Constant</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry><makevar>JAVASHAREDIR</makevar></entry> + <entry>The base directory for everything related to Java. Default value + is <filename>${PREFIX}/share/java</filename>.</entry> + </row> + <row> + <entry><makevar>JAVAJARDIR</makevar></entry> + <entry>The directory where JAR files should be installed. Default value + is <filename>${JAVASHAREDIR}/classes</filename>.</entry> + </tbody> + </tgroup> + </table> + + <sect2 id="java-best-practices"> + <title>Best practices</title> + + <para>When porting a Java library, your port should install the JAR + file(s) in <filename>${JAVAJARDIR}</filename>, and everything else + under <filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for the + documentation, see below). In order to reduce the packing file size, + you may reference the JAR file(s) directly in the + <filename>Makefile</filename>. Just use the following statement (where + <filename>myport.jar</filename> is the name of the JAR file installed + as part of the port):</para> + + <programlisting>PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar</programlisting> + + <para>When porting a Java application, the port usually install + everything under a single directory (including its JAR dependencies). + The use of <filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly + encouraged in this extend. It is up the porter to decide whether the + port should install the additional JAR dependencies under this + directory or directly use the already installed ones (from + <filename>${JAVAJARDIR}</filename>).</para> + + <para>Regardless of the type of your port (library or application), the + additional documentation should be installed in the usual location as + for any port (see <ulink url="#DADS-DOCUMENTATION">this + section</ulink>). The JavaDoc tool is known to produce a different set + of files depending on the version of the JDK that is used. For ports + that do not enforce the use of a particular JDK, it is therefore a + complex task to specify the packing list + (<filename>pkg-plist</filename>). This is one reason why porters are + strongly encouraged to use the <makevar>PORTDOCS</makevar> macro. This + feature is unfortunately not (yet) documented in this document so you + should refer to <filename>bsd.port.mk</filename> itself for further + information. Moreover, even if you can predict the set of files that + will be generated by <command>javadoc</command>, the size of the + resulting <filename>pkg-plist</filename> advocates for the use of the + forecited <makevar>PORTDOCS</makevar> macro.</para> + + <para>The default value for <makevar>DATADIR</makevar> is + <filename>${PREFIX}/share/${PORTNAME}</filename>. It is a good idea to + override <makevar>DATADIR</makevar> to + <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java ports. + Indeed, <makevar>DATADIR</makevar> is automatically addded to + <makevar>PLIST_SUB</makevar> (documented <ulink + url="#PORTING-PLIST">here</ulink>) so you may use + <literal>%%DATADIR%%</literal> directly in + <filename>pkg-plist</filename>.</para> + + <para>As for the choice of building Java ports from source or directly + installing them from a binary distribution, there is no defined policy + at the time of writing. However, people from the <ulink + url="http://www.freebsd.org/java/">FreeBSD Java Project</ulink> + encourage porters to have their ports built from source whenever it is + a trivial task.</para> + + <para>All the features that have been presented in this section are + implemented in <filename>bsd.java.mk</filename>. If you ever think that + your port needs more sophisticated Java support, please first have a + look at the <ulink + url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.java.mk">bsd.java.mk + CVS log</ulink> as it usually takes some time to document the latest + features. Then, if you think the support you are lacking would be + beneficial to many other Java ports, feel free to discuss it on the + FreeBSD Java mailing list.</para> + + <para>Although there is a <literal>java</literal> category for PRs, it + refers to the JDK porting effort from the FreeBSD Java project. + Therefore, you should submit your Java port in the + <literal>ports</literal> category as for any other port, unless of + course it turns out that the issue you are trying to resolve is related + to either a JDK implementation or + <filename>bsd.java.mk</filename>.</para> + + </sect2> + </sect1> <sect1 id="using-python"> >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200405211645.i4LGj6Pr015633>