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">
|
<sect1 id="using-java">
|
||||||
<title>Using Java</title>
|
<title>Using Java</title>
|
||||||
|
|
||||||
|
<sect2 id="java-variables">
|
||||||
|
<title>Variable definitions</title>
|
||||||
|
|
||||||
<para>If your port needs a Java™ Development Kit (JDK) to
|
<para>If your port needs a Java™ Development Kit (JDK) to
|
||||||
either build, run or even extract the distfile, then it should
|
either build, run or even extract the distfile, then it should
|
||||||
define <makevar>USE_JAVA</makevar>.</para>
|
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>
|
version is <filename role="package">java/jdk14</filename>.</para>
|
||||||
|
|
||||||
<table frame="none">
|
<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">
|
<tgroup cols="2">
|
||||||
<thead>
|
<thead>
|
||||||
|
|
@ -4015,7 +4018,7 @@ LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
|
||||||
setting <makevar>USE_JAVA</makevar>:</para>
|
setting <makevar>USE_JAVA</makevar>:</para>
|
||||||
|
|
||||||
<table frame="none">
|
<table frame="none">
|
||||||
<title>Variables defined for ports that use Java</title>
|
<title>Variables provided to ports that use Java</title>
|
||||||
|
|
||||||
<tgroup cols="2">
|
<tgroup cols="2">
|
||||||
<thead>
|
<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
|
to get information for debugging your port. It will display the
|
||||||
value of many of the forecited variables.</para>
|
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>
|
||||||
|
|
||||||
<sect1 id="using-python">
|
<sect1 id="using-python">
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue