開始在 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」。

該專案使用 GraalVM Polyglot API，並提供額外功能來管理 Python 虛擬環境，以及將 Python 套件相依性與 Maven 工作流程整合。Java 程式碼和 pom.xml 檔案都經過大量文件註解，且產生的程式碼會描述可用的功能。

另請參閱嵌入建置工具以取得有關 GraalPy Maven 外掛程式的更多資訊。

使用原生 Python 套件建立跨平台 JAR 檔 #

產生的專案使用 GraalPy Maven 外掛程式，它可以輕鬆新增 Python 相依性。但是，Python 套件可能具有特定於建置系統的原生元件。為了將產生的應用程式發布到其他系統，請依照下列步驟進行

在每個部署平台上建置專案。重新命名 JAR 檔，讓每個檔案都有一個平台特定的名稱，並將它們移動到同一機器上的臨時目錄。

解壓縮每個 JAR 檔（為 JAR 檔替換正確的名稱）。需要從每個 JAR 檔串連一個特殊檔案 vfs/fileslist.txt。最後，從所有檔案的組合建立一個新的 combined.jar，並使用串連的 fileslist.txt。

 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 外掛程式將在 GraalPy 24.1.1 版本中提供，預計於 2024 年 10 月 15 日推出。

使用以下命令建立一個帶有 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 中

將 graalpy-gradle-plugin 新增到 plugins 區段
```
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 外掛程式的更多資訊。

Ant、CMake、Makefile 或其他不直接支援 Maven 相依性的建置系統 #

有些（通常是較舊的）專案可能會使用 Ant、Makefile、CMake 或其他不直接支援 Maven 相依性的建置系統。諸如 Apache Ivy™ 之類的專案讓這些建置系統能夠解析 Maven 相依性，但開發人員可能有理由不使用它們。GraalPy 帶有一個工具可以從 Maven 取得所需的 JAR 檔。

假設專案有一些目錄用於儲存第三方相依性，並且建置系統設定為將任何 JAR 檔放置在類別路徑中，則專案目錄樹可能看起來類似於此
```
 ├───lib
 │   └─── ... *.jar dependencies are here
 └───src
     └─── ... *.java files and resources are here
```
安裝 GraalPy 以供您的系統使用，並確保您的 PATH 中有 graalpy。開啟命令列介面並輸入您的專案目錄。然後，視您的系統而定，執行以下其中一個命令

在 POSIX shell 中
```
 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());
         }
     }
 }

將 GraalPy 作為 CPython 的替代品 #

前往此處以開始將 GraalPy 作為 CPython 的替代品。