ビルドツールの埋め込み

GraalPyのMavenおよびGradleプラグインは、JavaベースのアプリケーションにPythonコードを埋め込むために必要なPython関連のリソースを管理する機能を提供します。

ユーザーが提供するPythonアプリケーションファイル。たとえば、プロジェクトの一部であるPythonソースなど。
プラグインの設定に従って、ビルド中にプラグインによってインストールされるサードパーティのPythonパッケージ。
ネイティブイメージで生成された実行ファイルを自己完結型にするために必要なPython標準ライブラリ。

これらのファイルを物理的に管理およびデプロイするだけでなく、JavaコードでGraalPyコンテキストを適切に設定することにより、実行時にPythonで利用できるようにする必要があります。GraalPyResources APIは、Pythonへのアクセス、関連リソースを仮想ファイルシステムまたは専用の外部ディレクトリに埋め込んでアクセスするように事前構成されたコンテキストを作成するためのファクトリメソッドを提供します。

デプロイメント #

リソースをデプロイする方法には、Javaリソースとして仮想ファイルシステムを使用してPythonでアクセスする方法と、外部ディレクトリとしてアクセスする方法の2つがあります。

仮想ファイルシステム #

Python関連のリソースは、JARまたはネイティブイメージで生成された実行ファイルに、標準のJavaリソースとして埋め込まれます。GraalPy仮想ファイルシステムは、リソースファイルを標準のJavaリソースとしてアクセスし、GraalPyで実行されているPythonコードで利用できるようにします。これはPythonコードに対して透過的であり、標準のPython IOを使用してこれらのファイルにアクセスできます。

MavenまたはGradleプロジェクトのJavaリソースファイルは、通常、専用のリソースディレクトリにあります。org.graalvm.python.vfsという名前のすべてのリソースサブディレクトリがマージされ、Python側の設定可能な仮想ファイルシステムのマウントポイント（デフォルトでは/graalpy_vfs）にマッピングされます。たとえば、実際のファイルシステムパス${project_resources_directory}/org.graalvm.python.vfs/src/foo/bar.pyを持つPythonファイルは、Pythonで/graalpy_vfs/src/foo/bar.pyとしてアクセスできます。

仮想ファイルシステムを使用するように事前設定されたGraalPyコンテキストを作成するには、次のGraalPyResourcesファクトリメソッドを使用します。

GraalPyResources.createContext()
GraalPyResources.contextBuilder()
GraalPyResources.contextBuilder(VirtualFileSystem)

外部ディレクトリ #

仮想ファイルシステムを使用したJavaリソースの代替として、MavenまたはGradleプラグインを構成して、外部ディレクトリの内容を管理することもできます。これは、結果のアプリケーションにJavaリソースとして埋め込まれません。ユーザーは、そのようなディレクトリのデプロイを担当します。Pythonコードは、実際のファイルシステムから直接ファイルにアクセスします。

外部ディレクトリを使用するように事前構成されたGraalPyコンテキストを作成するには、次のGraalPyResourcesファクトリメソッドを使用します。

GraalPyResources.createContextBuilder(Path)

規約 #

GraalPyResourcesのファクトリメソッドは、次の規約に依存しています。ここで、${root}は外部ディレクトリ、またはPython側の仮想システムのマウントポイントであり、実際のファイルシステムの${project_resources_directory}/org.graalvm.python.vfsです。

${root}/src：Pythonアプリケーションファイルに使用されます。このディレクトリは、Pythonモジュールファイルのデフォルトの検索パス（PYTHONPATH環境変数と同等）として構成されます。
${root}/venv：インストールされたサードパーティのPythonパッケージを保持するPython仮想環境に使用されます。コンテキストは、この仮想環境から実行されているかのように構成されます。特に、この仮想環境にインストールされたパッケージは、インポートに自動的に使用可能になります。
${root}/home：Python標準ライブラリ（PYTHONHOME環境変数と同等）に使用されます。

MavenまたはGradleプラグインは、venvおよびhomeサブディレクトリの内容を完全に管理します。これらのディレクトリでの手動による変更は、ビルド中にプラグインによって上書きされます。

${root}/venv：プラグインは仮想環境を作成し、pom.xmlまたはbuild.gradleのプラグイン構成に従って必要なパッケージをインストールします。
${root}/home：プラグインは、必要な（構成可能な）Python標準ライブラリの部分をこのディレクトリにコピーします。デフォルトでは、標準ライブラリ全体が使用されます。

srcサブディレクトリは、カスタムのPythonスクリプトまたはモジュールを使用して手動で設定する必要があります。

GraalPy Mavenプラグインの構成 #

pom.xmlファイルのgraalpy-maven-pluginのconfigurationブロックにプラグイン構成を追加します。

<plugin>
    <groupId>org.graalvm.python</groupId>
    <artifactId>graalpy-maven-plugin</artifactId>
    ...
    <configuration>
        ...
    </configuration>
    ...
</plugin>

packages要素は、プラグインによってダウンロードおよびインストールされるサードパーティのPythonパッケージのリストを宣言します。

Pythonパッケージとそのバージョンは、pipで使用する場合と同様に指定されます。

<configuration>
    <packages>
        <package>termcolor==2.2</package>
        ...
    </packages>
    ...
</configuration>

pythonHomeサブセクションは、標準ライブラリのどの部分をデプロイする必要があるかを宣言します。

各includeおよびexclude要素は、どのファイルパスを含めるか、または除外するかを指定するJavaのような正規表現として解釈されます。
```
<configuration>
    <pythonHome>
        <includes>
            <include>.*</include>
            ...
        </includes>
        <excludes>
            <exclude></exclude>
            ...
        </excludes>
    </pythonHome>
    ...
</configuration>
```
pythonResourcesDirectory要素が指定されている場合、指定されたディレクトリは外部ディレクトリとして使用され、Javaリソースは埋め込まれません。コンテキストを作成するために、適切なGraalPyResources APIを使用することを忘れないでください。
```
<configuration>
    <pythonResourcesDirectory>${basedir}/python-resources</pythonResourcesDirectory>
    ...
</configuration>
```

GraalPy Gradleプラグインの構成 #

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

build.gradleファイルのGraalPyブロックにプラグイン構成を追加します。packages要素は、プラグインによってダウンロードおよびインストールされるサードパーティのPythonパッケージのリストを宣言します。

Pythonパッケージとそのバージョンは、pipで使用する場合と同様に指定されます。
```
graalPy {
  packages = ["termcolor==2.2"]
  ...
}
```
pythonHomeサブセクションは、標準ライブラリのどの部分をデプロイする必要があるかを宣言します。

includesおよびexcludesリストの各要素は、どのファイルパスを含めるか、または除外するかを指定するJavaのような正規表現として解釈されます。
```
graalPy {
  pythonHome {
    includes = [".*"]
    excludes = []
  }
  ...
}
```
pythonResourcesDirectory要素が指定されている場合、指定されたディレクトリは外部ディレクトリとして使用され、Javaリソースは埋め込まれません。コンテキストを作成するために、適切なGraalPyResources APIを使用することを忘れないでください。
```
graalPy {
  pythonResourcesDirectory = file("$rootDir/python-resources")
  ...
}
```