docs/67001: [PATCH] Java section of the Porter's Handbook (continued)
Herve Quiroz
herve.quiroz at esil.univ-mrs.fr
Fri May 21 16:50:27 UTC 2004
>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:
More information about the freebsd-doc
mailing list