FreeBSD Porter's Handbook
Prev | Chapter 6 Special Considerations | Next

# 6.11 Using Java

## 6.11.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/jdk16`.

Table 6-14. Variables Which 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.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`:

Table 6-15. Variables Provided to Ports That Use Java

Variable | Value
--- | ---
`JAVA_PORT` | The name of the JDK port (e.g. `'java/diablo-jdk16'`).
`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. `'freebsd'`).
`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. `'FreeBSD Foundation'`).
`JAVA_HOME` | Path to the installation directory of the JDK (e.g. `'/usr/local/diablo-jdk1.6.0'`).
`JAVAC` | Path to the Java compiler to use (e.g. `'/usr/local/diablo-jdk1.6.0/bin/javac'`).
`JAR` | Path to the `jar` tool to use (e.g. `'/usr/local/diablo-jdk1.6.0/bin/jar'` or `'/usr/local/bin/fastjar'`).
`APPLETVIEWER` | Path to the `appletviewer` utility (e.g. `'/usr/local/diablo-jdk1.6.0/bin/appletviewer'`).
`JAVA` | Path to the `java` executable. Use this for executing Java programs (e.g. `'/usr/local/diablo-jdk1.6.0/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:

Table 6-16. 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 7.1) and `SUB_LIST`.

## 6.11.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_TARGET`. This is similar to the `USE_GMAKE` mechanism, which is documented in Section 6.3.

## 6.11.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 7.1) 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 KDE | Up | Web Applications, Apache and PHP

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