Component Installation

Some languages and plugins are not part of the GraalVM core distribution and must bedownloaded and installed separately. These include:

• GraalVM Native Image – a technology to compile an application ahead-of-time into a binary that runs natively on the system. Warning: The Native Image plugin is available as an Early Adopter technology.
• Python, R, and Ruby languages interpreters. Warning: The support for Python, R and Ruby languages is experimental.
• LLVM toolchain – a set of tools and APIs for compiling native programs to bitcode that can be executed with the GraalVM LLVM runtime.

To assist you with the installation, these features are pre-packaged ascomponents. The GraalVM installation contains the GraalVM Updaterutility, gu, that can be used to manage components. GraalVM Updater alsoverifies whether the version of the component is appropriate for your GraalVMinstallation. Component packages are released for each GraalVM release withrespective updates. Component packages downloaded for previous release(s) cannotbe used with newer ones.

Add the GraalVM /bin folder to your PATHenvironment variable in order to deploy the installer tool.There is a command-line help available.Run gu or gu -h to get commands overview.Run gu <command> -h to get help specific for the particular command, for example gu install -h.

A component may depend on requiring other components for its operation. GraalVM Updaterverifies such requirements and will attempt to download the required dependencies, orabort the installation if component’s requirements are not met.

Warning: Components intended for GraalVM Enterprise Edition can not be installed into GraalVM Community Edition.

Component Installation Modes

Three modes of components installation are supported:

Manual Installation

Depending on the GraalVM distribution, you download a component package from GitHub or Oracle Technology Network and GraalVM Updater will install it. The following pre-built packages are at your disposal:

• native-image.jar
• python-installable.jar
• ruby-installable.jar
• r-installable.jar
• llvm_toolchain.jar

With the already downloaded component JAR file, the component can be installed as

gu -L install component.jar

where -L option, equivalent to —local-file or —file, tells to installfrom the downloaded component archive. However, a component may depend on othercomponents (e.g. Ruby language depends on the LLVM toolchain). For example, gu-L install component.jar will fail if the required components are not yetinstalled. If you download all the dependencies into the same directory, you mayuse:

gu -L install -D

Check gu —help or gu -C (see below) how to instruct GraalVM Updater to find and process required components as well.

Warning: For GraalVM Enterprise Edition users, a manual installation is required toprevent the use of a “community” component version.

Installation from Catalog

There is a component catalog on GitHub maintained by Oracle, fromwhich you can install a component just by its name. GraalVM Updater firstdownloads the list of components, then uses the information in the list todownload the actual component package and installs it.

To get a list of components available in the catalog, their IDs, and descriptive names, use

gu available

Then the ComponentId, for example ruby, can be used as:

gu install ruby

If you want to see more verbose messages during installation, you may use the-v or —verbose switch to see the download progress bar and verbose messages.

If a component being installed requires other components to be present, GraalVMUpdater will search the Catalog to find the appropriate component and install itas well. If required components could not be found, installation will fail.

When using custom catalog URLs, it is possible, as a convenience, to setenvironment variable GRAALVM_CATALOG pointing to the custom catalog’s URL.GraalVM updater will use URL found defined by GRAALVM_CATALOG in preference tothe builtin ones. You may setup the environment variable in startup or profilescripts.

Warning: The installation of the R language component is possible only from catalog.

Installation from Local Components Collection

Components can be downloaded manually in advance to a local file folder, or to afolder shared on the local network. GraalVM Updater can then use that folderinstead of the catalog:

gu -C /path/to/download/directory

specifying the directory to use as components collection. It is possible to typecomponents names (like ruby) instead of filenames. GraalVM Updater alsoattempts to find required dependencies in the local component collection.

Similar to the installation from catalog, the path to the directory thatcontains local components collection can be defined in the GRAALVM_CATALOGenvironment variable.

Installed on your machine components can be printed with:

gu list

Installation Configuration

The installation command of GraalVM Updater accepts multiple options and parameters and allows this syntax:

gu install [-0cCfFiLnorsuvyxY] param [param ...]

The following options are currently supported:

• -0, —dry-run: dry run, do not change anything
• -c, —catalog: treat parameters as component IDs from the GraalVM components catalog. This is the default
• -C, —custom-catalog <url>: use a specific catalog URL to locate components
• -L, —local-file: treat parameters as local filenames of packaged components
• -f, —force: force overwrite, bypass version checks
• -i, —fail-existing: fail on an existing component
• -n, —no-progress: do not display the downloading progress
• -o, —overwrite: overwrite different files
• -r, —replace: replace existing components
• -s, —no-verify-jars: skip integrity verification of component archives
• -u, —url: interpret parameters as URLs of packaged components
• -v, —verbose: be verbose. Prints versions and dependency information
• -x, —ignore: ignore failures
• -y, —only-validate: do not install, just check compatibility and conflicting files
• -Y, —validate-before: download, verify, check file conflicts before any disk change is made

Finally, customers using Oracle GraalVM Enterprise Edition might need to pass anadditional verification step to login to Oracle components repository. GraalVMUpdater tool provides options for that:

• —public-key / -k <path> to set the path to a custom GPG public key path
• —username/-U to enter a username

Rebuilding Images

GraalVM components used to create guest language implementations may change overtime, requiring a Native Image to be rebuilt. Polyglot native image and polyglotnative C library may be out of sync, particularly:

• new languages may not be accessible;
• removed languages may cause the native binary to fail on missing resources or libraries.

To rebuild and refresh the native binaries, use the following command:

gu rebuild-images [--verbose] polyglot|libpolyglot|js|llvm|python|ruby [custom native-image args]

Uninstallation

Components may be uninstalled from the GraalVM environment when no longer needed.To uninstall a specific component you need to know its ComponentId, which can be ruby, or r and so on.The command to uninstall the component is:

gu remove ComponentId

If more components end with, for example, ruby, the installer will print anerror message that you need to use component’s full names (org.graalvm.ruby).The uninstallation removes the files created during the installation. If a filebelongs to multiple components, it will be removed when the last component usingit is removed.

Proxies

If GraalVM Updater needs to reach the component catalog, or download acomponent package, it may need to pass through the HTTP proxy, if your networkuses one. On macOS, the proxy settings are automatically obtained from the OS.On Linux, you must ensure that the http_proxy and https_proxy environmentvariables are set appropriately before you launch gu. Please refer to yourdistribution and/or desktop environment documentation for the details.

Sometimes, an intermediate (e.g. corporate) proxy may act as“man-in-the-middle”, intercepting https-secured communication and issuing itsown host certificates, which cannot be verified by GraalVM Updater. If you seeerror messages with descriptions containing ValidatorException orSunCertPathBuilderException, it is obviously the culprit.

GraalVM Updater intentionally does not supportan option to disable certificate or hostname verification, for security reasons.You may try to add your proxy’s certificate to the GraalVM default security truststore (see JDK documentation for the details). You can also download the componentsmanually to a folder, and then use gu -L install /path/to/file orgu -C /path/to/download/dir install component to install from a local filesystem.

Replacing Components and Files

A component may be only installed once. GraalVM Updater refuses to install acomponent if a component with the same ComponentId is already installed. But theinstalled component may be replaced. GraalVM Updater first uninstalls thecomponent and then installs a new package. To replace a component, use the-r option. The -L option, equivalent to —file or —local-file, tells to treat parameters as local filename of a packaged component.

gu install -L -r component.jar
gu install -r ruby

The process is the same as if gu remove is run first and gu install next.

GraalVM Updater also refuses to overwrite existing files if the to-be-installedand existing versions differ. There are cases when you may need to refresh filecontents, if they were modified or damaged. Use the -o option:

gu install -L -o component.jar
gu install -o ruby

GraalVM Updater will just instruct to replace the contained files of acomponent. By default, it will not alter anything. You can also use -f(—force) option, which disables most of the checks and allows you to installnon-matching versions.

Troubleshooting

If a language component is not installed running the code that tries to initialize the language context can result in an exception like this:

java.lang.ExceptionInInitializerError
Caused by: com.oracle.truffle.polyglot.PolyglotIllegalArgumentException: A language with id '$language' is not installed. Installed languages are: [js, llvm].

If you see a problem like that, install the language component as explained on this page above.