GraalVMアップデータ

GraalVMアップデータ (gu)は、オプションのGraalVM言語ランタイムおよびユーティリティをインストールして管理するためのコマンドライン・ユーティリティです。これらの各言語ランタイムおよびユーティリティは、個別にダウンロードしてインストールする必要があります。インストールを支援するために、これらはJARファイルとしてあらかじめパッケージ化され、ドキュメントではコンポーネントと呼ばれます。バージョン21.0.0以降、GraalVMアップデータはより効率的になり、ローカルのGraalVMインストールを新しいバージョンに更新したり、CommunityからEnterprise Editionにアップグレードするために使用できます。詳細は、「GraalVMのアップグレード」を参照してください。

GraalVMアップデータはGraalVMの基本ディストリビューションに含まれ、<graalvm>/bin/guランチャで使用できます。GraalVMアップデータのソース・コードは、<graalvm>/lib/installerフォルダにあります。

コンポーネントのインストール

次のGraalVM言語ランタイムおよびユーティリティをインストールできます。

ツール/ユーティリティ:

ランタイム:

GraalVMアップデータは、コンポーネントのバージョンが現在のGraalVMインストールに適しているかどうかを検証します。更新のたびに各GraalVMディストリビューション用のコンポーネントがリリースされ、以前のリリース用にダウンロードしたコンポーネントを新しいリリースで使用することはできません。あるコンポーネントが、その操作の前提条件として別のコンポーネントを必要とする場合があります。GraalVMアップデータは、そのような要件を検証し、必要な依存性のダウンロードを試みるか、コンポーネントの要件が満たされない場合はインストールを中止します。

ノート: Oracle GraalVM Enterprise Edition用のコンポーネントをGraalVM Community Editionにインストールすることはできません。

コンポーネントのインストールでは3つのモードがサポートされています:

カタログからのインストール

GitHubで入手可能なコンポーネント・カタログ(オラクル社が保守)があり、そこからコンポーネントをその名前でインストールできます。

  1. カタログで使用可能なコンポーネントのIDとわかりやすい名前のリストを取得します: 
    gu available
  2. ComponentId値を使用してコンポーネント・パッケージをインストールします。たとえば、rubyの場合: 
    gu install ruby

GraalVMアップデータは、最初にコンポーネントのリストをダウンロードし、次にリスト内の情報を使用して実際のコンポーネント・パッケージをダウンロードして、インストールします。インストール中にさらに詳細な出力を表示し(ダウンロードの進行状況バーなど)、バージョンおよび依存性情報を出力するには、-v (--verbose)スイッチを使用します。

インストールするコンポーネントが別のコンポーネントに依存している場合、GraalVMアップデータはカタログを検索して適切な依存性を見つけ、それもインストールします。必要なコンポーネントが見つからない場合、インストールは失敗します。

カスタム・カタログURLを使用する場合、便宜上、カスタム・カタログのURLを指す環境変数GRAALVM_CATALOGを設定できます。GraalVMアップデータは、組込みのURLよりもGRAALVM_CATALOGで定義されたURLを優先して使用します。環境変数は、起動スクリプトまたはプロファイル・スクリプトで設定できます。

ノート: なんらかの理由でGRAALVM_HOME環境変数を設定する必要がある場合、それがgu操作に影響する可能性があります。これが設定されている場合は、JAVA_HOMEおよびPATHと同様に、該当するGraalVMインストールを指している必要があります。

手動インストール

  1. オペレーティング・システム、Javaバージョンおよびアーキテクチャ(該当する場合)を考慮して、OracleのGraalVMダウンロード・ページからコンポーネントをダウンロードします。

  2. 適切なJARファイルをダウンロードしたら、次のコマンドを使用してインストールします:

    gu -L install component.jar

    たとえば、macOSでJava 11 GraalVM Enterpriseeディストリビューションのネイティブ・イメージをインストールするには、次を実行します:

    gu -L install native-image-installable-svm-java11-darwin-amd64-<version>.jar

-Lオプション(--local-fileまたは--fileと同等)は、ダウンロードされたJARからコンポーネントをインストールします。ただし、コンポーネントは他のコンポーネントに依存する場合があります(たとえば、RubyはLLVMツールチェーンに依存します)。たとえば、必要なコンポーネントがまだインストールされていない場合、gu -L install component.jarは失敗します。すべての依存性が同じディレクトリにダウンロードされている場合は、次を実行できます:

gu -L install -D

必要なコンポーネントを検索して処理するようにGraalVMアップデータに指定する方法は、gu --helpまたはgu -Cを確認してください。

ローカル・コンポーネント・コレクションからのインストール

コンポーネントは、ローカルのファイル・フォルダまたはローカル・ネットワーク上で共有されたフォルダに事前に手動でダウンロードできます。GraalVMアップデータは、カタログのかわりにそのフォルダを使用できます:

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

コンポーネント・コレクション用に使用するディレクトリを指定します。ファイル名のかわりにコンポーネントの名前(rubyなど)を入力できます。また、GraalVMアップデータは、ローカル・コンポーネント・コレクション内で必要な依存性の検出も試みます。

指定したディレクトリからコンポーネントをインストールする場合、ワイルドカードを使用して、GraalVMの正しいバージョン番号を持つすべてのコンポーネントをインストールできます:

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

これにより、native-imageコンポーネント(nativeで始まるすべてのもの)がインストールされます。

インストールしたコンポーネントの確認

インストールしたコンポーネントは、次を使用して出力できます:

gu list

ほとんどの場合、Node.js、R、Ruby、PythonおよびWebAssembly言語の一般サポートは、初期状態で使用できます。コンポーネントのインストール後のメッセージにある推奨事項に従って、システムに依存する構成を微調整することをお薦めします。

コンポーネントのアンインストール

コンポーネントは、不要になった場合はGraalVMからアンインストールできます。特定のコンポーネントをアンインストールするには、そのComponentIdを使用します。gu listを実行して、正確なComponentIdを見つけます。コンポーネントをアンインストールするコマンドは次のとおりです:

gu remove ruby

複数のコンポーネントが(たとえば) rubyで終わる場合、インストーラはコンポーネントのフルネーム(org.graalvm.ruby)が必要であるというエラー・メッセージを出力します。アンインストールによって、インストール中に作成されたファイルが削除されます。ファイルが複数のコンポーネントに属している場合、ファイルはそれを使用している最後のコンポーネントが削除されると削除されます。

コマンドラインまたはVisual Studio Codeユーザー・インタフェースからLLVMツールチェーン・コンポーネントのアンインストールを起動したとき、それに依存するコンポーネントがインストールされたままになっていると、失敗する場合があることに注意してください。この場合、依存するコンポーネントを先に削除するか、明示的に選択したコンポーネントに加えて依存するコンポーネントも削除する-Dオプションを追加します:

gu -D remove llvm-toolchain

GraalVMのアップグレード

GraalVMアップデータには、ローカル・マシン上の既存のGraalVMインストールを最新バージョンに更新する機能があります。さらに、エディションをCommunityからEnterpriseにアップグレードすることもできます。

たとえば、GraalVM 20.xがインストールされている場合は、次を使用して使用可能な最新バージョンに更新します:

gu upgrade

GraalVMアップデータは、GraalVM EnterpriseまたはGraalVM Community Editionの最新バージョンをダウンロードしようとします(使用可能な場合)。既存のインストールを書き換えませんが、新しいディレクトリに解凍し、場所のパスを出力します。また、現在のGraalVMインストールにオプションのコンポーネントがインストールされているかどうかを検証し、それらも更新します。親インストールに現在のGraalVMインストールへのsymlinkが含まれている場合、そのsymlinkは更新されます。選択したGraalVMインストールを指す環境変数(PATHなど)が設定に含まれている場合、これらの変数は手動で更新する必要があります。

--editionスイッチを追加することで、エディションを切り替えることができます。たとえば、GraalVM Community EditionをEnterpriseにアップグレードするには、次を実行します:

gu upgrade --edition ee

現在のインストールの次に、最新バージョンのGraalVM Enterprise Editionがインストールされます。GraalVMアップデータは、オプションのコンポーネントが存在するかを再度確認し、コンポーネントがインストールに適しているかどうかを検証し、それもアップグレードします。

ノート: GraalVMアップデータでは、GraalVMを新しいバージョンにのみアップグレードできます。古いバージョンへのダウングレードおよびGraalVM EnterpriseからCommunity Editionへのダウングレードは手動です。

インストール構成

GraalVMアップデータのインストール・コマンドでは、複数のオプションとパラメータを使用でき、次の構文を使用できます:

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

現在、次のオプションがサポートされています:

イメージの再ビルド

言語ランタイム・サポート用のGraalVMコンポーネントは変更される可能性があります。たとえば:

ネイティブ・バイナリを再ビルドしてリフレッシュするには、次のコマンドを使用します:

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

GraalVMアップデータ・コマンドの概要

コマンドライン・ヘルプを使用するには、guまたはgu -hを実行します。特定のコマンドに固有のヘルプを取得するには、gu <command> -hを実行します。たとえば、gu install -hです。

GraalVMアップデータの使用オプション:

GraalVMアップデータの共通オプション:

Oracle GraalVM Enterprise EditionのユーザーがOracleコンポーネント・リポジトリにログインするには、追加の検証ステップに合格することが必要になる場合があります。GraalVMアップデータ・ツールには、そのためのオプションが用意されています:

実行時オプション:

プロキシの構成

GraalVMアップデータがコンポーネント・カタログにアクセスするか、コンポーネント・パッケージをダウンロードする必要がある場合は、HTTP/HTTPSプロキシ(それがネットワークで使用されているとき)を通過する必要があります。macOSでは、プロキシ設定はOSから自動的に取得されます。Linuxでは、guツールを起動する前に、http_proxyおよびhttps_proxy環境変数が適切に設定されていることを確認します。詳細は、ディストリビューションまたはデスクトップ環境(あるいはその両方)のドキュメントを参照してください。

GraalVMアップデータは、セキュリティ上の理由から、証明書またはホスト名の検証を無効にするオプションを意図的にサポートしていません。ユーザーは、GraalVMのデフォルトのセキュリティ・トラスト・ストアにプロキシの証明書を追加できます。ユーザーは、コンポーネントをフォルダに手動でダウンロードし、gu -L install /path/to/fileまたはgu -C /path/to/download/dir install componentを使用してローカル・ファイルシステムからインストールすることもできます。

インターネット・アクセスなしでの作業

プロキシの内側にあるため、またはセキュリティ上の理由で、マシンがインターネットからカタログおよびコンポーネントにアクセスしてダウンロードできない場合、GraalVMアップデータは、ローカル・ディレクトリ、またはターゲット・マシンでアクセス可能なネットワーク共有上のディレクトリから、コンポーネントをインストールできます。

ディレクトリを準備し、インストールするすべてのコンポーネントとその依存性(他のGraalVMコンポーネントが機能する必要がある場合)をそのディレクトリにダウンロードする必要があります。

その後で、gu -L install /path/to/fileを使用できます(-Lオプションはローカル・ファイルを使用するように指定し、--local-fileまたは--fileと同等です)。-Dオプションを追加すると、GraalVMアップデータはインストール可能なファイルの隣のディレクトリで潜在的な依存性を検索します。また、gu -C /path/to/download/dir install componentも使用でき、指定したディレクトリの内容がコンポーネントのカタログとして機能します。

gu -Lではコンポーネントのファイル名を指定する必要がありますが、gu -C <dir>を使用する場合はコンポーネント名を使用する必要があることに注意してください:

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

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

コンポーネントおよびファイルの置換

コンポーネントは1回のみインストールできます。同じIDのコンポーネントがすでにインストールされている場合は、GraalVMアップデータによって、コンポーネントのインストールが拒否されます。ただし、インストールされているコンポーネントを置き換えることができます。GraalVMアップデータは、最初にコンポーネントをアンインストールしてから、新しいパッケージをインストールします。

コンポーネントを置き換えるには、-rオプションと-L (--local-fileまたは--file)オプションを使用し、パッケージ化されたコンポーネントのローカル・ファイル名としてパラメータを扱います:

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

このプロセスは、gu removeが最初に実行され、次にgu installが実行される場合と同じです。

インストールするバージョンと既存のバージョンが異なる場合にも、GraalVMアップデータは、既存のファイルを上書きすることを拒否します。変更された場合や破損した場合など、ファイルの内容をリフレッシュすることが必要になる場合があります。この場合は、-oオプションを使用します:

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

次に、GraalVMアップデータは、コンポーネントに含まれているファイルを置き換えるようにユーザーに指示します。デフォルトでは、何も変更されません。または、-f (--force)オプションを使用して、ほとんどのチェックを無効にし、一致しないバージョンをユーザーがインストールできるようにします。

トラブルシューティング

言語コンポーネントがインストールされていない場合、その言語コンテキストを初期化しようとするコードを実行すると、次のような例外が発生することがあります:

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

このような問題が発生した場合は、このページで説明したように言語ランタイム・コンポーネントをインストールします。