6.9 Using Java

6.9.1 Variable definitions

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 is java/jdk14.

Table 6-5. Variables that may be set by ports that use Java

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.1[+] 1.2[+] 1.3[+] 1.4[+]).
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 ibm blackdown).
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.
USE_JIKES Whether the port should or should not use the jikes bytecode compiler to build. When no value is set for this variable, the port will use jikes to build if available. You may also explicitly forbid or enforce the use of jikes (by setting 'no' or 'yes'). In the later case, devel/jikes will be added to build dependencies of the port. In any case that jikes is actually used in place of javac, then the HAVE_JIKES variable is defined by bsd.java.mk.

Below is the list of all settings a port will receive after setting USE_JAVA:

Table 6-6. Variables provided to ports that use Java

Variable Value
JAVA_PORT The name of the JDK port (e.g. 'java/jdk14').
JAVA_PORT_VERSION The full version of the JDK port (e.g. '1.4.2'). 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. 'linux').
JAVA_PORT_VENDOR The vendor of the JDK port (e.g. 'sun').
JAVA_PORT_OS_DESCRIPTION Description of the operating system used by the JDK port (e.g. 'Linux').
JAVA_PORT_VENDOR_DESCRIPTION Description of the vendor of the JDK port (e.g. 'FreeBSD Foundation').
JAVA_HOME Path to the installation directory of the JDK (e.g. '/usr/local/jdk1.3.1').
JAVAC Path to the Java compiler to use (e.g. '/usr/local/jdk1.1.8/bin/javac' or '/usr/local/bin/jikes').
JAR Path to the jar tool to use (e.g. '/usr/local/jdk1.2.2/bin/jar' or '/usr/local/bin/fastjar').
APPLETVIEWER Path to the appletviewer utility (e.g. '/usr/local/linux-jdk1.2.2/bin/appletviewer').
JAVA Path to the java executable. Use this for executing Java programs (e.g. '/usr/local/jdk1.3.1/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. This variable is available only if the JDK is Java 1.2 or higher.
JAVA_N2A Path to the native2ascii tool.
JAVA_POLICYTOOL Path to the policytool program. This variable is available only if the JDK is Java 1.2 or higher.
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. This variable is only available if the JDK is Java 1.2 or higher.
JAVA_CLASSES Path to the archive that contains the JDK class files. On JDK 1.2 or later, this is ${JAVA_HOME}/jre/lib/rt.jar. Earlier JDKs used ${JAVA_HOME}/lib/classes.zip.
HAVE_JIKES Defined whenever jikes is used by the port (see USE_JIKES above).

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:

Table 6-7. Constants defined for ports that use Java

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 13.5) and SUB_LIST.

6.9.2 Building with Ant

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_TARGETS. This is similar to the USE_GMAKE mechanism, which is documented in Section 5.11.

If jikes is used in place of javac (see USE_JIKES in Section 6.9.1), then Ant will automatically use it to build the port.

6.9.3 Best practices

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

PLIST_FILES+= %%JAVAJARDIR%%/myport.jar

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 13.5) 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 CVS 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.

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.

Hosting by: Hurra Communications Ltd.
Generated: 2007-01-26 17:58:41