find-matching-jvm 1 user commands nosh
find-matching-jvm set the JAVA_HOME environment variable to denote a JVM that matches some criteria
`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.

First the files `/usr/local/etc/javavms`, `/etc/javavms`, and `/usr/pkg/etc/javavms` are checked for in order. If the 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 those files do 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/pkg/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