This NSIS plugin searches Windows for Java installations and reports back "the most suitable" installation found, if any. It is intended to be versatile letting you specify various options that will impact the search and what is deemed "the most suitable".
The plugin performs the search in multiple steps, each of which can be influenced using options.
A set of predefined registry paths will be searched for both HKEY_LOCAL_MACHINE
and HKEY_CURRENT_USER
in both 32- and 64-bit "views":
SOFTWARE\JavaSoft
SOFTWARE\Eclipse Adoptium
SOFTWARE\Azul Systems\Zulu
SOFTWARE\Azul Systems\Zulu 32-bit
SOFTWARE\Semeru
SOFTWARE\BellSoft\Liberica
The plugin contains parsers that looks for the expected subkeys like for example JRE\8.0.392.8\hotspot
or Java Development Kit\1.8.0_392
. Additional registry paths can be searched by using the /REGPATH
option or predefined paths can be excluded by using the /DELREGPATH
option.
The predefined environment variable %JAVA_HOME%
will be searched. Additional variables can be added using the /ENVSTR
option and the predefined variable can be removed using /DELENVSTR
. The parser will look for in the bin
subfolder if the variable exist but doesn't include bin
.
The Windows %PATH%
environmental variable will be searched so that any Java installations that have been added to %PATH%
should be picked up. This search can be disabled using the /SKIPOSPATH
option.
Specified paths can be searched if specified as a parameter. Any parameter not belonging to a specific option is assumed to be a path to be searched. Specified paths can include "aliases" like %ProgramFiles%
- which will be expanded automatically. There are no predefined file paths, so unless one or more is specified as parameters, none will be searched.
Filtering paths can be applied across all installations already found in the previous steps. These will be excluded from the results. Filtering paths can include "aliases" which will be expanded before application. The following predefined filtering paths are default:
%commonprogramfiles%\Oracle\Java\javapath
%commonprogramfiles(x86)%\Oracle\Java\javapath
%commonprogramW6432%\Oracle\Java\javapath
%ALLUSERSPROFILE%\Oracle\Java\javapath
%SystemRoot%\system32
%SystemRoot%\SysWOW64
The javaw.exe
found in the various "javapath" locations aren't real Java installations, they are merely "launchers" that tries to find a real installation using registry information. These are thus not wanted.
Additional filtering paths can be specified using the /ADDFILTER
option, and existing filtering paths can be removed using /DELFILTER
. Filtering paths must match the beginning of the Java installation paths that are to be filtered, which includes the drive letter. Drive letters should not be hard coded, so it's recommended to use aliases as in the predefined filtering paths. When expanded these will contain the correct drive letter for the system.
Found Java installations can be excluded based on their version using the /MINVER
and /MAXVER
options. Any installations that doesn't meet the criteria will be removed from the list over found installations at this point.
If more than one Java installation remains at this point, the list will be sorted according to "suitability". This means that the highest version and build numbers will be preferred, 64-bit will be preferred over 32-bit and the option /OPTVER
will be taken into account.
After exclusion both by path filtering and version rules, and sorting, zero or more Java installations remain. If none are found or remain, an empty string is returned - otherwise the first in the list is deemed "the most suitable" and returned to the NSIS script by returning the full path to javaw.exe
. Additional information can also be returned of any of the options /RETVERSION
, /RETBUILD
, /RETVERSIONSTR
, /RETINSTTYPE
, /RETARCH
and /RETARCHBITS
are specified. If no matching Java installation is found, all the additional options are also returned as empty strings so that the number of returned elements are consistent.
NSIS Java Locator consists of four different DLL files, both 32- and 64-bit versions in both ANSI and "Unicode" (Widestring) versions. The version that corresponds to the NSIS variant in use must be used. Most will probably need the 32-bit "Unicode" version. Once the correct DLL has been selected, simply drop it in NSIS' Plugins
folder and it is ready for use. The plugin only has one function, Locate
, which can be called like this:
NsJavaLocator::Locate [/OPTION] [VALUE] /END
Since the plugin doesn't take a fixed number of parameters and NSIS calls plugins in a very "crude" way (all parameters are simply pushed to the stack before the call), /END
must always be the last parameter - even if none others are specified. If /END
is missing, your NSIS script will probably crash, as the plugin will keep draining the stack until it encounters /END
.
When the plugin returns, the result of the search in the form of a string with the full path to javaw.exe
or an empty string if none was found has been pushed to the stack. Use Pop
to retrieve it. Unless one of the /RET
options has been specified, only one value is pushed to the stack. For each /RET
parameter specified, an additional value is pushed - even if the same /RET
option is specified multiple times. The /RET
values are pushed in the inverse of the specified order with the javaw.exe
path pushed last, so that the values are pop'ed in the same order that they are specified.
NSIS Java Locator can take any number of parameters. These consist of options, option and value pairs and the default: file paths to search. This means that any parameter that isn't an option and isn't a value following an option, is assumed to be a file path that is to be searched. All options start with a forward slash /
. All parameters except the final /END
are optional. Without any additional parameters, the Java search will executed with the default setting and the Java installation with the highest Java version will be returned.
Option | Description |
---|---|
/SKIPOSPATH |
Makes the plugin skip searching the Windows PATH environment variable. |
/LOG |
Enables plugin logging to the installer's "details output" window. The log level determines what level of detail/what messages that are logged. |
/DIALOGDEBUG |
Only use this option for figuring out what's happening when the plugin is running. This will display a modal message box that will halt the plugin's execution for each logged message, and can be very obtrusive. The log level determines what level of detail/what messages that are shown. |
/RETVERSION |
Makes the plugin return the major version of the Java installation (e.g 7 or 21 ) or an empty string if unknown. |
/RETBUILD |
Makes the plugin return the build of the Java installation (e.g 80 or 392 ) or an empty string if unknown. |
/RETVERSIONSTR |
Makes the plugin return a string with the combination of version and build in the form <Version>.<Build> (e.g 8.392 ) or an empty string if unknown. |
/RETINSTTYPE |
Makes the plugin return a string indicating the Java installation type, if known. Possible values are JDK , JRE , Unknown or an empty string if no installation was found. |
/RETARCH |
Makes the plugin return a string indicating the CPU architecture the Java installation is for. Possible values are ia64 , x64 , x86 , Unknown or an empty string if no installation was found. |
/RETARCHBITS |
Makes the plugin return only the number of bits of the CPU architecture the Java installation is for. Possible values are 32 , 64 or an empty string if unknown. |
Option | Type | Description |
---|---|---|
/REGPATH |
String | Adds a registry path to search. Registry paths should use backslashes (\ ) between key names, and should start after where HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER would be. Every registry path will be searched with both prefixes. |
/DELREGPATH |
String | Removes a registry path from the search. This is useful to remove predefined registry paths. The path must be an exact match. |
/ENVSTR |
String | Adds an environmental variable to the search. The string must contain an environmental variable enclosed in % like this: %JAVA_HOME% . %JAVA_HOME% is predefined and doesn't need to be added. If the string doesn't "expand" when passed to the Windows API, it isn't added to the search. This means that any variable specified will only be "used" on systems where they are defined. |
/DELENVSTR |
String | Removes an environmental variable from the search. This is useful to remove the predefined %JAVA_HOME% variable from the search. |
/ADDFILTER |
String | Adds a filtering path. See 1.5 File path filtering for further information. |
/DELFILTER |
String | Removes a filtering path. This is useful to remove predefined filtering paths The filtering path much be an exact match. |
/MINVER |
Version expression | Specifies the minimum Java version to include in the search. |
/MAXVER |
Version expression | Specifies the maximum Java version to include in the search. |
/OPTVER |
Version expression | Specifies the "optimal" Java version. Java installations that match this will be preferred when selecting "the most suitable" installation. |
/LOGLEVEL |
Log level | The log level for the plugin if either /LOG or /DIALOGDEBUG is specified. |
Version expressions can be used to specify a specific version, with or without build, or any versions "less than" or "greater than" a given version. The syntax is:
[ < | <= | = | >= | > ] <Version> [.<Build>]
If no operator is specified, the operator is context based: For minimum, greater than is assumed. For maximum, less than is assumed. For optimal, equals is assumed.
If the operator is equals and the build isn't specified, any build of the specified version will match. If both version and and build are specified, both must match.
If the operator is less than or greater than, with or without equals, it will be evaluated slightly differently if build is specified than if it is not. For example, <9
will match any Java version that is 8 or less, regardless of build - but no Java 9 version will match. <=9.20
on the other hand will also match Java 9 up to and including build 20.
The log level determines what messages will be logged or shown if /LOG
or /DIALOGDEBUG
is specified. The allowed values are:
ERROR
WARN
INFO
DEBUG
The default log level is INFO
.
NSIS Java Locator has been made using Lazarus 2.2.6 with Free Pascal 3.2.2. The 32-bit version of Lazarus with 64-bit cross-compilation was used to be able to compile both 32- and 64-bit DLLs.
It is probably possible to build NSIS Java Locator using Free Pascal alone, but it would require some manual configuration of build paths and options. By opening NsJavaLocator.lpi
with Lazarus, everything should be ready to compile without further configuration. All project paths are relative.