GraalVM Updater

Oracle GraalVM Enterprise Edition includes GraalVM Updater – a command line utility, gu, to install and manage additional components.

These are:

These components are not part of the GraalVM Enterprise core distribution and must be downloaded and installed separately. To assist a user with installation, the components are pre-packaged as JAR files. GraalVM Updater also verifies whether the version of a component is appropriate for the current installation. Component packages are released for each GraalVM Enterprise distribution with respective updates. Component packages downloaded for previous release(s) cannot be used with newer ones.

The source code of GraalVM Updater is located in the <GRAALVM_HOME>/lib/installer folder. To deploy the tool, confirm that GraalVM Enterprise is set in your PATH environment variable.

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

Component Installation

Three modes of a component installation are supported:

Manual Installation

A manual installation is required for Oracle GraalVM Enterprise Edition users.

  1. Download a component package from the Oracle Technology Network page. The following pre-built components are available for download:
    • Oracle GraalVM Enterprise Edition Native Image Early Adopter
    • GraalVM LLVM Toolchain Plugin
    • Oracle GraalVM Enterprise Edition Ruby Language Plugin
    • Oracle GraalVM Enterprise Edition Python Language Plugin
    • Oracle GraalVM Enterprise Edition WebAssembly Language Plugin
  2. Having downloaded the component package in consideration of the operating system and the underlying Java SE version, install it with: 
    gu -L install component.jar

    For example, to install the Native Image component for Java 11 GraalVM Enterprise distribution on macOS, run:

    gu -L install native-image-installable-svm-java11-darwin-amd64-19.3.4.jar

The -L option, equivalent to --local-file or --file, tells to install a component from a downloaded JAR. However, a component may depend on other components (e.g., Ruby depends on the LLVM Toolchain plugin). For example, gu -L install component.jar will fail if the required components are not yet installed. If all dependencies are downloaded into the same directory, you can run:

gu -L install -D

Check gu --help or gu -C how to instruct GraalVM Updater to find and process required components as well.

Installation from Catalog

The R language plugin can be installed to GraalVM Enterprise from the GitHub catalog, maintained by Oracle. This allows to install a component just by its ComponentId value:

gu install ComponentId

To install R, run:

gu install r

GraalVM Updater first downloads the list of components, then uses the information in the list to download the actual component package and installs it. To see more verbose output during the installation, like the download progress bar, print versions and dependency information, use the -v (--verbose) switch.

If a component being installed depends on another component, GraalVM Updater will search the catalog to find an appropriate dependency and install it as well. If required components could not be found, installation will fail.

Installation from Local Components Collection

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

gu install -C /path/to/downloads/directory ComponentId

Specify the directory to use as components collection. It is possible to type components names (like ruby) instead of filenames. GraalVM Updater will also attempt to find required dependencies in the local component collection.

When installing components from a given directory, you can allow installing all components which have correct version number for GraalVM Enterprise using wildcards:

./gu install -C ~/Download/Components/ native*

It will install the native-image component, or anything that starts with native.

Check Installed Components

Installed on a machine components can be printed with:

gu list

A generic support R, Ruby, Python and WebAssembly languages will work out of the box in most cases. It is recommended to fine-tune system-dependent configurations, thus follow the recommendations in the component post-installation messages.

If a necessary component installed, check its version:

native-image --version
llvm-toolchain --version
ruby -v
Rscript --version
graalpython --version
wasm --version

Already installed on components can be printed with:

gu list

Component Uninstallation

Components may be uninstalled from the GraalVM Enterprise installation when no longer needed. To uninstall a specific component, use its ComponentId. Run gu list to find out the exact ComponentId. The command to uninstall the component is:

gu remove ruby

If more components end with, for example, ruby, the installer will print an error message that a component full name is required (org.graalvm.ruby). The uninstallation removes the files created during the installation. If a file belongs to multiple components, it will be removed when the last component using it is removed.

Rebuild images

A set of GraalVM components that provide language implementations may change. Polyglot native image and polyglot native C library may be out of sync, particularly:

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]

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:

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

GraalVM Updater Commands Overview

There is a command-line help available by running gu or gu -h. Run gu <command> -h to get help specific for the particular command, for example, gu install -h.

Usage Description
gu info [-cClLnprstuvV] <param> Print the information about specific component (from file, URL or catalog).
gu available [-aClvV] <expr> List components available in the catalog.
gu install [-0cCDfFiLnorsuvyxY] <param> Install a component package.
gu list [-clv] <expression> List installed components, or components from catalog.
gu rebuild-images Rebuild native images.
gu remove [-0Dfxv] <id> Uninstall a component.
gu update [-cCnLsux] [<ver>] [<param>] Upgrade to the recent GraalVM version.
gu <command> -h Print help message about a specific command.
Option Description
--auto-yes, -A Say YES or ACCEPT to a question.
--catalog, -c Treat parameters as component IDs from catalog of GraalVM components. This is the default.
--local-file, -L Treat parameters as local filenames of packaged components.
--debug, -d Enable debugging and print stacktraces.
--help, -h Print the help message.
--no-progress, -n Do not display download progress.
--non-interactive, -N Enable non-interactive mode. Fail when input is required.
--url, -u Interpret parameters as URLs of packaged components.
--verbose, -v Enable verbose output. Print versions and dependency information.

Configure Proxies

If GraalVM Updater needs to reach the component catalog, or download a component package, it may need to pass through the HTTP/HTTPS proxy, if the network uses one. On macOS, the proxy settings are automatically obtained from the OS. On Linux, ensure that the http_proxy and https_proxy environment variables are set appropriately before launching the gu tool. Refer to the distribution and/or desktop environment documentation for the details.

GraalVM Updater intentionally does not support an option to disable certificate or hostname verification, for security reasons. A user may try to add proxy’s certificate to the GraalVM default security trust store. A user can also download the components manually to a folder, and then use gu -L install /path/to/file or gu -C /path/to/download/dir install component to install from a local filesystem.

Working without Internet Access

If your machine cannot access and download Catalog and GraalVM components from the Internet, either because it is behind a proxy, or for security reasons, Graal Updater can install components from a local directory, or a directory on a network share accessible on the target machine.

You need to prepare a directory, download all Components that you want to install and their dependencies (in case they require other GraalVM components to work) into that directory.

Then you can use gu -L install /path/to/file (where -L option instructs to use local files, equivalent to –local-file or –file). Adding -D option will instruct Graal Updater to look for potential dependencies in the directory next to the installable file. Additionally, gu -C /path/to/download/dir install component can be used, the specified directory contents acting as a Catalog of components.

Note that with gu -L you need to specify the component’s file name, while when using gu -C <dir>, the component name must be used:

# Specify file location
gu -LD install /tmp/installables/fastr.jar

# Specify component name
gu -C /tmp/instalables install r

Replace Components and Files

A component may be only installed once. GraalVM Updater refuses to install a component if a component with the same ID is already installed. But the installed component may be replaced. GraalVM Updater first uninstalls the component and then installs a new package. To replace component, use -r option, and the -L (--local-file or --file) option 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.

The GraalVM Updater also refuses to overwrite existing files if the to-be-installed and existing versions differ. There are cases when refreshing file contents may be needed, if they were modified or damaged. Use -o option:

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

GraalVM Updater will just instruct to replace the contained files of a component. By default, it will not alter anything. Alternatively, use -f (--force) option, which disables most of the checks and allows to install non-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.