Add a section about Best Practices to the Java section and make some
minor changes around it to make it fit in better. PR: docs/67001 Submitted by: Herve Quiroz <herve.quiroz at esil.univ-mrs.fr> Reviewed by: ceri (mentor)
This commit is contained in:
Mark Linimon
parent
c8cb66cdbf
commit
2b56364e87
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=20989
1 changed files with 114 additions and 2 deletions
|
|
@ -3936,6 +3936,9 @@ LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
|
|||
<sect1 id="using-java">
|
||||
<title>Using Java</title>
|
||||
|
||||
<sect2 id="java-variables">
|
||||
<title>Variable definitions</title>
|
||||
|
||||
<para>If your port needs a Java™ Development Kit (JDK) to
|
||||
either build, run or even extract the distfile, then it should
|
||||
define <makevar>USE_JAVA</makevar>.</para>
|
||||
|
|
@ -3946,7 +3949,7 @@ LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
|
|||
version is <filename role="package">java/jdk14</filename>.</para>
|
||||
|
||||
<table frame="none">
|
||||
<title>Variables to be defined by ports that use Java</title>
|
||||
<title>Variables that may be set by ports that use Java</title>
|
||||
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
|
|
@ -4015,7 +4018,7 @@ LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
|
|||
setting <makevar>USE_JAVA</makevar>:</para>
|
||||
|
||||
<table frame="none">
|
||||
<title>Variables defined for ports that use Java</title>
|
||||
<title>Variables provided to ports that use Java</title>
|
||||
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
|
|
@ -4151,6 +4154,115 @@ LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
|
|||
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: <filename>${PREFIX}/share/java</filename>.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><makevar>JAVAJARDIR</makevar></entry>
|
||||
<entry>The directory where JAR files should be installed.
|
||||
Default:
|
||||
<filename>${JAVASHAREDIR}/classes</filename>.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
</sect2>
|
||||
|
||||
<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 installs
|
||||
everything under a single directory (including its JAR
|
||||
dependencies). The use of
|
||||
<filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly
|
||||
encouraged in this regard. 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
|
||||
<link linkend="dads-documentation">same location</link> as for
|
||||
any other port. 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 yet well
|
||||
documented, 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
|
||||
<makevar>PORTDOCS</makevar>.</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 <link
|
||||
linkend="porting-plist">here</link>) 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/">&os; 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 &a.java;.</para>
|
||||
|
||||
<para>Although there is a <literal>java</literal> category for
|
||||
PRs, it refers to the JDK porting effort from the &os; Java
|
||||
project. Therefore, you should submit your Java port in the
|
||||
<literal>ports</literal> category as for any other port, unless
|
||||
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">
|
||||
|
|
|
|||
Loading…
Reference in a new issue