<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>