嵌入建置工具

GraalPy 的 Maven 和 Gradle 外掛程式提供管理在基於 Java 的應用程式中嵌入 Python 程式碼所需之 Python 相關資源的功能

使用者提供的Python 應用程式檔案，例如，屬於專案一部分的 Python 原始碼。
由外掛程式在建置期間根據外掛程式設定所安裝的第三方 Python 套件。
為了使 Native Image 產生的執行檔成為獨立的，Python 標準程式庫是必要的。

除了實際管理和部署這些檔案之外，還必須透過在您的 Java 程式碼中相應地設定 GraalPy Context，使其在執行階段於 Python 中可用。 GraalPyResources API 提供工廠方法，用於建立預先設定為存取 Python 的 Context，並使用 虛擬檔案系統或從專用的外部目錄嵌入相關資源。

部署 #

有兩種部署資源的方式：作為 Java 資源，使用虛擬檔案系統在 Python 中存取它們，或是作為外部目錄。

虛擬檔案系統 #

Python 相關資源會以標準 Java 資源的形式嵌入在應用程式檔案中，無論是 JAR 或是 Native Image 產生的執行檔。 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 的形式存取。

使用以下 GraalPyResources 工廠方法來建立預先設定為使用虛擬檔案系統的 GraalPy Context

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

外部目錄 #

除了使用虛擬檔案系統的 Java 資源之外，也可以設定 Maven 或 Gradle 外掛程式來管理外部目錄的內容，而該目錄不會作為 Java 資源嵌入到產生的應用程式中。這樣一來，使用者便有責任部署此類目錄。 Python 程式碼將直接從真實檔案系統存取檔案。

使用以下 GraalPyResources 工廠方法來建立預先設定為使用外部目錄的 GraalPy Context

GraalPyResources.createContextBuilder(Path)

慣例 #

GraalPyResources 中的工廠方法依賴下列慣例，其中 ${root} 是外部目錄，或 Python 端的虛擬系統掛載點，而真實檔案系統上是 ${project_resources_directory}/org.graalvm.python.vfs

${root}/src：用於 Python 應用程式檔案。此目錄將設定為 Python 模組檔案的預設搜尋路徑 (相當於 PYTHONPATH 環境變數)。
${root}/venv：用於保存已安裝第三方 Python 套件的 Python 虛擬環境。將設定 Context，使其如同在此虛擬環境中執行。尤其是在此虛擬環境中安裝的套件將自動可用於匯入。
${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 來建立 Context。
```
<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 來建立 Context。
```
graalPy {
  pythonResourcesDirectory = file("$rootDir/python-resources")
  ...
}
```