Name

find-matching-jvm — set the JAVA_HOME environmnent variable to denote a JVM that matches some criteria

Synopsis

find-matching-jvm [--version v...] [--operating-system os...] [--manufacturer m...] {next-prog}

Description

find-matching-jvm is a chain-loading utility that sets the JAVA_HOME environment variable to denote the root directory for a JVM that matches zero or more version, operating system, and manufacturer criteria, and then chain loads to next-prog with the execvp(3) function. If the environment variable is already set, it simply chain loads and does not alter it.

next-prog may contain its own command line options, which find-matching-jvm will ignore.

find-matching-jvm scans through the list of available JVMs and matches them against zero or more criteria. The command-line options describe the match criteria. They may occur multiple times, in order to specify more than one possible match. If any of them are not supplied at all, then all JVMs are considered to match that aspect. They are:

--version v

The JVM must be Java version v, which will be in the form 1.6, 1.7, 1.8, and so forth. JVM version numbers in the form 1.x.y and just x are renormalized into 1.x form for comparison.

--operating-system os

os is native to denote a JVM that is "native" to the host operating system or foreign to denote a "foreign" JVM. Currently, the only "foreign" JVMs are JVMs ported from Linux to the BSDs.

--manufacturer m

m is one of openjdk, sun, oracle, ibm, or gnu denoting the various (widely known) JVM manufacturers.

If the /usr/local/etc/jvms file exists, it is expected to be a (potentially commented) list of JVM programs, in descending priority order. The JAVA_HOME variable is set to the root of the JVM subtree, which is presumed to be the directory above the directory containing the first matching named JVM program.

If that file does not exist, then if the /usr/lib/jvm directory exists it is presumed to contain all of the JVM subtree root directories, either directly or as symbolic links. The default-java entry, any entries whose names cannot be parsed into version and manufacturer, and any entry that is not a directory or a symbolic link to a directory, are ignored; all other entries are sorted into descending version order. The JAVA_HOME variable is set to the first matching JVM subtree.

Failing either of those, the /usr/local/bin/java, /usr/bin/java, and /bin/java files are checked in order, and if they exist they are matched against the criteria. For matching purposes they are considered to have no version, "native" operating system, and no manufacturer. They will thus only match if no explicit version or manufacturer criterion is specified.

Failure to find a matching JVM, which can occur if there are no JVMs that match the given criteria or if there are no JVMs available to match in the first place, is a fatal error.

See also

find-default-jvm(1)

This has a slightly different mechanism that does not ignore the /usr/lib/jvm/default-java file and that always succeeds in setting the environment variable to something, even if there is no JVM on the system.

Author

Jonathan de Boyne Pollard