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言語ランタイムおよびユーティリティをインストールできます。
ツール/ユーティリティ:
- ネイティブ・イメージ – アプリケーションをネイティブ実行可能ファイルに事前にコンパイルするテクノロジ
- LLVMツールチェーン - ネイティブ・プログラムをGraalVMで実行可能なビットコードにコンパイルするための一連のツールおよびAPI
ランタイム:
- Java on Truffle - GraalVMのTruffleインタプリタに基づくJava仮想マシン実装
- Node.js – Node.js 14.21.3互換
- Python - Python 3.8.5互換
- WebAssembly – WebAssembly (Wasm)
GraalVMアップデータは、コンポーネントのバージョンが現在のGraalVMインストールに適しているかどうかを検証します。更新のたびに各GraalVMディストリビューション用のコンポーネントがリリースされ、以前のリリース用にダウンロードしたコンポーネントを新しいリリースで使用することはできません。あるコンポーネントが、その操作の前提条件として別のコンポーネントを必要とする場合があります。GraalVMアップデータは、そのような要件を検証し、必要な依存性のダウンロードを試みるか、コンポーネントの要件が満たされない場合はインストールを中止します。
ノート: Oracle GraalVM Enterprise Edition用のコンポーネントをGraalVM Community Editionにインストールすることはできません。
コンポーネントのインストールでは3つのモードがサポートされています:
カタログからのインストール
GitHubで入手可能なコンポーネント・カタログ(オラクル社が保守)があり、そこからコンポーネントをその名前でインストールできます。
- カタログで使用可能なコンポーネントのIDとわかりやすい名前のリストを取得します:
gu available
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インストールを指している必要があります。
手動インストール
-
オペレーティング・システム、Javaバージョンおよびアーキテクチャ(該当する場合)を考慮して、OracleのGraalVMダウンロード・ページからコンポーネントをダウンロードします。
-
適切な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 ...]
現在、次のオプションがサポートされています:
-0, --dry-run
: テスト実行。何も変更しません-c, --catalog
: パラメータをGraalVMコンポーネント・カタログからのコンポーネントIDとして扱います。これがデフォルトです。-C, --custom-catalog <url>
: 特定のカタログURLを使用してコンポーネントを検索します-L, --local-file
: パラメータをパッケージ化されたコンポーネントのローカル・ファイル名として扱います-f, --force
: 上書きを強制し、バージョンの確認をバイパスします-i, --fail-existing
: 既存のコンポーネントで失敗します-n, --no-progress
: ダウンロードの進行状況を表示しません-o, --overwrite
: 異なるファイルを上書きします-r, --replace
: 既存のコンポーネントを置き換えます-s, --no-verify-jars
: コンポーネント・アーカイブの整合性検証をスキップします-u, --url
: パラメータをパッケージ化されたコンポーネントのURLとして解釈します-v, --verbose
: 冗長にします。バージョンおよび依存性情報を出力します-x, --ignore
: 失敗を無視します-y, --only-validate
: インストールせず、互換性および競合するファイルのチェックのみ行います-Y, --validate-before
: ディスク変更の前に、ファイル競合をダウンロード、検証およびチェックします
イメージの再ビルド
言語ランタイム・サポート用の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アップデータの使用オプション:
gu info [-cClLnprstuvV] <param>
: (ファイル、URLまたはカタログから)特定のコンポーネントに関する情報を出力しますgu available [-aClvV] <expr>
: カタログで使用可能なコンポーネントをリストしますgu install [-0cCDfFiLnorsuvyxY] <param>
: コンポーネント・パッケージをインストールしますgu list [-clv] <expression>
: インストール済のコンポーネントまたはカタログのコンポーネントをリストしますgu remove [-0Dfxv] <id>
: コンポーネントをアンインストールしますgu update [-cCnLsux] [<ver>] [<param>]
: 最新のGraalVMバージョンにアップグレードしますgu rebuild-images
: ネイティブ・イメージを再ビルドします。詳細な使用方法については、-h
を使用してくださいgu upgrade
: 使用可能な最新バージョンのGraalVMをインストールしますgu upgrade --edition ee
: GraalVM Community EditionからGraalVM Enterprise Editionの使用可能な最新バージョンへアップグレードします
GraalVMアップデータの共通オプション:
-A, --auto-yes
: 質問に対してYESまたはACCEPTを指定します-c, --catalog
: パラメータをGraalVMコンポーネントのカタログからのコンポーネントIDとして扱います。これがデフォルトです。-C, --custom-catalog <url>
: URLにあるユーザー指定のカタログを使用します-e, --debug
: デバッグを有効にし、スタック・トレースを出力します-E, --no-catalog-errors
: 1つ以上のカタログが機能している場合は停止しません-h, --help
: ヘルプを出力します-L, --local-file, --file
: パラメータをパッケージ化されたコンポーネントのローカル・ファイル名として扱います-N, --non-interactive
: 非対話型モードを有効にします。入力が必要な場合は失敗します--show-version
: バージョン情報を出力して続行します-u, --url
: パラメータをパッケージ化されたコンポーネントのURLとして解釈します-v, --verbose
: 詳細な出力を有効にします。バージョンおよび依存性情報を出力します--version
: バージョンを出力します
Oracle GraalVM Enterprise EditionのユーザーがOracleコンポーネント・リポジトリにログインするには、追加の検証ステップに合格することが必要になる場合があります。GraalVMアップデータ・ツールには、そのためのオプションが用意されています:
--public-key / -k <path>
: パスをカスタムGPG公開キー・パスに設定します--username/-U
: ユーザー名を入力します
実行時オプション:
--native
: Javaアクセスが制限されたネイティブ・ランチャを使用して実行します(デフォルト)--jvm
: Javaアクセスを使用してJava仮想マシンで実行します--vm.[option]
: ホストVMにオプションを渡します。使用可能なオプションを表示するには、--help:vm
を使用します--log.file=<String>
: ゲスト言語のロギングを指定のファイルにリダイレクトします--log.[logger].level=<String>
: 言語のログ・レベルをOFF、SEVERE、WARNING、INFO、CONFIG、FINE、FINER、FINESTまたはALLに設定します--help
: このヘルプ・メッセージを出力します--help:vm
: ホストVMのオプションを出力します
プロキシの構成
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].
このような問題が発生した場合は、このページで説明したように言語ランタイム・コンポーネントをインストールします。