git: 5e7b0befe1 - main - [phb]: Document Uses=java

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=5e7b0befe151cd97730da15e93a33bc8a30b1465

commit 5e7b0befe151cd97730da15e93a33bc8a30b1465
Author:     Fernando Apesteguía <[email protected]>
AuthorDate: 2025-01-05 18:56:56 +0000
Commit:     Fernando Apesteguía <[email protected]>
CommitDate: 2025-01-05 18:59:46 +0000

    [phb]: Document Uses=java
---
 .../en/books/porters-handbook/uses/_index.adoc     | 108 +++++++++++++++++++++
 1 file changed, 108 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
index 0bec4ee1a1..97b3e0c2fd 100644
--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -1044,6 +1044,114 @@ If the `env` argument is given, the `configure` target is not set.
 If the `-a` flag is a problem for the port, add the `notall` argument.
 If `xmkmf` does not generate a `install.man` target, add the `noman` argument.
 
+[[uses-java]]
+== `java`
+
+Possible arguments: (none), `ant`, `build`, `extract`, `run`
+
+Defaults to `USES=java:build,run` if no arguments are provided and `NO_BUILD`
+is undefined. If `NO_BUILD` is defined, `USES=java:run` is used.
+If the `ant` argument is given, the port uses Apache Ant.
+If the `build` argument is given, a JDK port is added to the build dependencies.
+If the `extract` argument is given, a JDK port is added to the extract dependencies.
+If the `run` argument is given, a JDK port is added to the run dependencies.
+
+The framework provides the following variables to be set by the port:
+
+`JAVA_VERSION`::
+List of space-separated suitable java versions for the port. An optional `\+`
+allows you to specify a range of versions. (allowed values `8[+]`, `11[\+]`,
+`17[+]`, `18[\+]`, `19[+]`, `20[\+]`, `21[+]`, `22[\+]`, `22[+]`)
+
+`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: `openjdk`, `oracle`)
+
+The framework exposes the following variables to be read by the port:
+
+`JAVA_PORT`::
+The name of the JDK port. (e.g. 'java/openjdk8')
+
+`JAVA_PORT_VERSION`::
+The version of the JDK port. (e.g. '8')
+
+`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. 'openjdk')
+
+`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. 'OpenJDK BSD Porting Team')
+
+`JAVA_HOME`::
+Path to the installation directory of the JDK. (e.g. [.filename]#/usr/local/openjdk8#)
+
+`JAVAC`::
+Path to the Java compiler to use. (e.g. [.filename]#/usr/local/openjdk8/bin/javac# or
+[.filename]#/usr/local/bin/javac#)
+
+`JAR`::
+Path to the JAR tool to use. (e.g. [.filename]#/usr/local/openjdk8/bin/jar# or
+[.filename]#/usr/local/bin/fastjar#)
+
+`APPLETVIEWER`::
+Path to the appletviewer utility. (e.g.
+[.filename]#/usr/local/linux-jdk1.8.0/bin/appletviewer#)
+
+`JAVA`::
+Path to the `java` executable. Use this for executing Java programs. (e.g. [.filename]#/usr/local/openjdk8/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.
+
+`JAVA_CLASSES`::
+Path to the archive that contains the JDK class files. On most JDKs, this is
+[.filename]#${JAVA_HOME}/jre/lib/rt.jar#.
+
+`JAVASHAREDIR`::
+The base directory for all shared Java resources.
+
+`JAVAJARDIR`::
+The directory where a port should install JAR files.
+
+`JAVALIBDIR`::
+The directory where JAR files installed by other ports are located.
+
 [[uses-kde]]
 == `kde`