If your port needs a Java™ Development Kit
(JDK™) to either build, run or even extract the
distfile, then it should define
USE_JAVA
.
There are several JDKs in the ports collection, from
various vendors, and in several versions. If your port must
use one of these versions, you can define which one. The
most current version, and FreeBSD default is
java/openjdk6
.
Variable | Means |
---|---|
USE_JAVA | Should be defined for the remaining variables to have any effect. |
JAVA_VERSION | List of space-separated suitable Java versions
for the port. An optional "+"
allows you to specify a range of versions (allowed
values:
1.5[+] 1.6[+] 1.7[+] ). |
JAVA_OS | List of space-separated suitable JDK port
operating systems for the port (allowed values:
native linux ). |
JAVA_VENDOR | List of space-separated suitable JDK port
vendors for the port (allowed values:
freebsd bsdjava sun
openjdk ). |
JAVA_BUILD | When set, it means that the selected JDK port should be added to the build dependencies of the port. |
JAVA_RUN | When set, it means that the selected JDK port should be added to the run dependencies of the port. |
JAVA_EXTRACT | When set, it means that the selected JDK port should be added to the extract dependencies of the port. |
Below is the list of all settings a port will receive
after setting USE_JAVA
:
Variable | Value |
---|---|
JAVA_PORT | The name of the JDK port (e.g.,
'java/openjdk6' ). |
JAVA_PORT_VERSION | The full version of the JDK port (e.g.,
'1.6.0' ). If you only need the
first two digits of this version number, use
${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/} . |
JAVA_PORT_OS | The operating system used by the JDK port
(e.g., 'native' ). |
JAVA_PORT_VENDOR | The vendor of the JDK port (e.g.,
'openjdk' ). |
JAVA_PORT_OS_DESCRIPTION | Description of the operating system used by the
JDK port (e.g.,
'Native' ). |
JAVA_PORT_VENDOR_DESCRIPTION | Description of the vendor of the JDK port
(e.g., 'OpenJDK BSD Porting
Team' ). |
JAVA_HOME | Path to the installation directory of the JDK
(e.g.,
'/usr/local/openjdk6' ). |
JAVAC | Path to the Java compiler to use (e.g.,
'/usr/local/openjdk6/bin/javac' ). |
JAR | Path to the jar tool to use
(e.g.,
'/usr/local/openjdk6/bin/jar'
or
'/usr/local/bin/fastjar' ). |
APPLETVIEWER | Path to the appletviewer
utility (e.g.,
'/usr/local/openjdk6/bin/appletviewer' ). |
JAVA | Path to the java executable.
Use this for executing Java programs (e.g.,
'/usr/local/openjdk6/bin/java' ). |
JAVADOC | Path to the javadoc utility
program. |
JAVAH | Path to the javah
program. |
JAVAP | Path to the javap
program. |
JAVA_KEYTOOL | Path to the keytool utility
program. |
JAVA_N2A | Path to the native2ascii
tool. |
JAVA_POLICYTOOL | Path to the policytool
program. |
JAVA_SERIALVER | Path to the serialver
utility program. |
RMIC | Path to the RMI stub/skeleton generator,
rmic . |
RMIREGISTRY | Path to the RMI registry program,
rmiregistry . |
RMID | Path to the RMI daemon program
rmid . |
JAVA_CLASSES | Path to the archive that contains the JDK class
files,
${JAVA_HOME}/jre/lib/rt.jar . |
You may use the java-debug
make
target to get information for debugging your port. It will
display the value of many of the forecited variables.
Additionally, the following constants are defined so all Java ports may be installed in a consistent way:
Constant | Value |
---|---|
JAVASHAREDIR | The base directory for everything related to
Java. Default:
${PREFIX}/share/java . |
JAVAJARDIR | The directory where JAR files should be
installed. Default:
${JAVASHAREDIR}/classes . |
JAVALIBDIR | The directory where JAR files installed by
other ports are located. Default:
${LOCALBASE}/share/java/classes . |
The related entries are defined in both
PLIST_SUB
(documented in
Section 7.1, “Changing pkg-plist
Based on Make
Variables”) and
SUB_LIST
.
When the port is to be built using Apache Ant, it has to
define USE_ANT
. Ant is thus considered
to be the sub-make command. When no
do-build
target is defined by the port, a
default one will be set that simply runs Ant according to
MAKE_ENV
, MAKE_ARGS
and ALL_TARGET
. This is similar to the
USES= gmake
mechanism, which is
documented in Section 6.4, “Building Mechanisms”.
When porting a Java library, your port should install
the JAR file(s) in ${JAVAJARDIR}
, and
everything else under
${JAVASHAREDIR}/${PORTNAME}
(except for
the documentation, see below). In order to reduce the
packing file size, you may reference the JAR file(s)
directly in the Makefile
. Just use the
following statement (where myport.jar
is the name of the JAR file installed as part of the
port):
When porting a Java application, the port usually
installs everything under a single directory (including its
JAR dependencies). The use of
${JAVASHAREDIR}/${PORTNAME}
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
${JAVAJARDIR}
).
Regardless of the type of your port (library or
application), the additional documentation should be
installed in the
same location
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 (pkg-plist
). This is
one reason why porters are strongly encouraged to use the
PORTDOCS
macro. Moreover, even if you
can predict the set of files that will be generated by
javadoc
, the size of the resulting
pkg-plist
advocates for the use of
PORTDOCS
.
The default value for DATADIR
is
${PREFIX}/share/${PORTNAME}
. It is a
good idea to override DATADIR
to
${JAVASHAREDIR}/${PORTNAME}
for Java
ports. Indeed, DATADIR
is automatically
added to PLIST_SUB
(documented in
Section 7.1, “Changing pkg-plist
Based on Make
Variables”) so you may use
%%DATADIR%%
directly in
pkg-plist
.
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 FreeBSD Java Project encourage porters to have their ports built from source whenever it is a trivial task.
All the features that have been presented in this
section are implemented in bsd.java.mk
.
If you ever think that your port needs more sophisticated
Java support, please first have a look at the bsd.java.mk
SVN log 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 Language mailing list.
Although there is a java
category for
PRs, it refers to the JDK porting effort from the FreeBSD Java
project. Therefore, you should submit your Java port in the
ports
category as for any other port,
unless the issue you are trying to resolve is related to
either a JDK implementation or
bsd.java.mk
.
Similarly, there is a defined policy regarding the
CATEGORIES
of a Java port, which is
detailed in Section 5.3, “Categorization”.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.