JVM での GraalPy の使用開始

GraalPy は、GraalVM JDK、Oracle JDK、または OpenJDK で使用できます。以下に示すように、Maven または Gradle ビルドツールを使用して、GraalPy を Java アプリケーションに簡単に追加できます。その他のビルドシステム (Ant、Make、CMake など) も、少し手作業を加えることで使用できます。

Maven #

GraalPy は、Maven アーティファクトを使用して、Python パッケージを Java アプリケーションに埋め込む Maven プロジェクトを生成できます。

GraalPy プロジェクトは、スタータープロジェクトを生成するための Maven アーキタイプを公開しています

mvn archetype:generate \
  -DarchetypeGroupId=org.graalvm.python \
  -DarchetypeArtifactId=graalpy-archetype-polyglot-app \
  -DarchetypeVersion=24.1.0

自動的に追加された GraalVM Native Image 「ツール」プラグインを使用して、ネイティブ実行可能ファイルをビルドします
```
 mvn -Pnative package
```
完了したら、実行可能ファイルを実行します
```
 ./target/polyglot_app
```
アプリケーションはコンソールに「hello java」を出力します。

このプロジェクトでは、Python 仮想環境を管理し、Python パッケージの依存関係を Maven ワークフローと統合するための追加機能を備えた GraalVM Polyglot API を使用しています。Java コードと *pom.xml* ファイルには詳細なドキュメントが用意されており、生成されたコードでは使用可能な機能について説明しています。

GraalPy Maven プラグインの詳細については、ビルドツールの埋め込みも参照してください。

ネイティブ Python パッケージを使用したクロスプラットフォーム JAR の作成 #

生成されたプロジェクトでは、Python の依存関係を簡単に追加できる GraalPy Maven プラグインを使用しています。ただし、Python パッケージには、ビルドシステムに固有のネイティブコンポーネントが含まれている場合があります。他のシステムに結果のアプリケーションを配布するには、次の手順に従います

各デプロイメントプラットフォームでプロジェクトをビルドします。JAR ファイルの名前をプラットフォーム固有の名前に変更し、同じマシンのテンポラリディレクトリに移動します。
各 JAR ファイルを解凍します (JAR ファイルの正しい名前を代入します)。特別なファイル *vfs/fileslist.txt* は、各 JAR ファイルから連結する必要があります。最後に、すべてのファイルの組み合わせと連結された *fileslist.txt* から新しい *combined.jar* を作成します。
```
 unzip linux.jar -d combined
 mv combined/vfs/fileslist.txt fileslist-linux.txt
 unzip windows.jar -d combined
 mv combined/vfs/fileslist.txt fileslist-windows.txt
 cat fileslist-linux.txt fileslist-windows.txt > combined/vfs/fileslist.txt
 cd combined
 zip -r ../combined.jar *
```

Gradle #

注: GraalPy Gradle プラグインは、2024 年 10 月 15 日に予定されている GraalPy バージョン 24.1.1 以降で利用可能になります。

以下のコマンドを使用して Gradle で Java アプリケーションを作成し、プロンプトに従います (Groovy ビルドスクリプト言語を選択し、テストフレームワークを選択するなど)

 gradle init --type java-application \
             --project-name interop  \
             --package interop \
             --no-split-project

プロジェクトは、次の構造で現在の作業ディレクトリに生成されます

 └── app
     ├── build.gradle
     └── src
         └── main
             ├── java
             │   └── interop
             │       └── App.java
             └── resources

プロジェクト構成ファイル *app/build.gradle* を開き、次のように変更します。
- dependencies セクションに GraalPy サポートと GraalVM Polyglot API を含めます
```
  implementation("org.graalvm.polyglot:polyglot:24.1.1")
  implementation("org.graalvm.polyglot:python:24.1.1")
```

最後に、*App.java* という名前のファイルのコードを、小さな Python 埋め込み用に次のように置き換えます

 package interop;

 import org.graalvm.polyglot.*;

 class App {
     public static void main(String[] args) {
         try (var context = Context.create()) {
             System.out.println(context.eval("python", "'Hello Python!'").asString());
         }
     }
 }

Gradle でアプリケーションを実行します
```
 ./gradlew run
```
アプリケーションはコンソールに「Hello Python!」を出力します。

注: GraalPy ランタイムのパフォーマンスは、埋め込む JDK に依存します。詳細については、ランタイム最適化のサポートを参照してください。

必要に応じて、サードパーティの Python パッケージを使用することもできます

5.1. *app/build.gradle* で

plugins セクションに graalpy-gradle-plugin を追加します
```
id "org.graalvm.python" version "24.1.1"
```
GraalPy Gradle プラグインを構成します
```
graalPy { 
 packages = ["termcolor==2.2"]
}
```

5.2. *settings.gradle* で、次の `pluginManagement` 構成を追加します。

pluginManagement {
   repositories {
      gradlePluginPortal()        
   }
}

5.3. *App.java* という名前のファイルを次のように更新します

   package interop;
   
   import org.graalvm.polyglot.*;
   import org.graalvm.python.embedding.utils.GraalPyResources;
   
   class App {
   ...
   public static void main(String[] args) {
       try (Context context = GraalPyResources.createContext()) {
           String src = """
           from termcolor import colored
           colored_text = colored("hello java", "red", attrs=["reverse", "blink"])
           print(colored_text)
           """;
           context.eval("python", src);
       }
   }

GraalPy Gradle プラグインの詳細については、ビルドツールの埋め込みも参照してください。

Maven 依存関係を直接サポートしていない Ant、CMake、Makefile、またはその他のビルドシステム #

一部の (多くの場合、古い) プロジェクトでは、Maven 依存関係を直接サポートしていない Ant、Makefile、CMake、またはその他のビルドシステムを使用している場合があります。Apache Ivy™ などのプロジェクトでは、このようなビルドシステムで Maven 依存関係を解決できますが、開発者がそれらを使用しない理由がある場合があります。GraalPy には、Maven から必要な JAR ファイルを取得するためのツールが付属しています。

プロジェクトのサードパーティの依存関係が格納されているディレクトリがあり、ビルドシステムがクラスパス上の JAR ファイルをそこに配置するように設定されていると仮定すると、プロジェクトディレクトリツリーは次のようになります
```
 ├───lib
 │   └─── ... *.jar dependencies are here
 └───src
     └─── ... *.java files and resources are here
```
システムに GraalPy をインストールし、`PATH` に `graalpy` があることを確認します。コマンドラインインターフェイスを開き、プロジェクトディレクトリを入力します。次に、システムに応じて、次のいずれかのコマンドを実行します

POSIX シェル
```
 export GRAALPY_HOME=$(graalpy -c 'print(__graalpython__.home)')
 "${GRAALPY_HOME}/libexec/graalpy-polyglot-get" -a python -o lib -v "24.1.0"
```
PowerShell
```
 $GRAALPY_HOME = graalpy -c "print(__graalpython__.home)"
 & "$GRAALPY_HOME/libexec/graalpy-polyglot-get" -a python -o lib -v "24.1.0"
```
これらのコマンドは、すべての GraalPy 依存関係を *lib* ディレクトリにダウンロードします。

ビルドシステムが *lib* から JAR ファイルを取得するように設定されている場合、以下の GraalPy 埋め込みコードは、プロジェクトの適切な場所に配置してメインクラスとして実行すれば機能するはずです。

 import org.graalvm.polyglot.*;

 public class Hello {
     public static void main(String[] args) {
         try (var context = Context.newBuilder().option("engine.WarnInterpreterOnly", "false").build()) {
             System.out.println(context.eval("python", "'Hello Python!'").asString());
         }
     }
 }

CPython の代替としての GraalPy #

CPython の代替として GraalPy を使い始めるには、こちらにアクセスしてください。