FreeBSD Porter's Handbook
Prev	Chapter 6 Special considerations	Next

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.

Prev	Home	Next
Using Bison	Up	Using Python