建置 Arrow Java#

系統設定#

Arrow Java 使用 Maven 建置系統。

建置需求

  • JDK 11+

  • Maven 3+

注意

CI 將測試所有支援的 JDK LTS 版本，以及最新的非 LTS 版本。

建置#

以下所有指示皆假設您已克隆 Arrow git 儲存庫

$ git clone https://github.com/apache/arrow.git
$ cd arrow
$ git submodule update --init --recursive

以下是可用的選項，用於編譯 Arrow Java 模組：

  • Maven 建置工具。

  • Docker Compose。

  • Archery。

建置 Java 模組#

若要建置預設模組，請前往專案根目錄並執行

Maven#

$ cd arrow/java
$ export JAVA_HOME=<absolute path to your java home>
$ java --version
$ mvn clean install

Docker compose#

$ cd arrow/java
$ export JAVA_HOME=<absolute path to your java home>
$ java --version
$ docker compose run java

Archery#

$ cd arrow/java
$ export JAVA_HOME=<absolute path to your java home>
$ java --version
$ archery docker run java

建置 JNI 函式庫 (*.dylib / *.so / *.dll)#

首先，我們需要建置 C++ 共享函式庫，JNI 綁定將會使用。我們可以手動建置這些，或者我們可以使用 Archery，透過 Docker 容器來建置它們（這將需要安裝 Docker、Docker Compose 和 Archery）。

注意

如果您在 Apple Silicon 上建置，請務必使用為該架構編譯的 JDK 版本。例如，請參閱 Azul JDK。

如果您在 Windows 作業系統上建置，請參閱 在 Windows 上開發。

Maven#

  • 若要僅建置 JNI C 資料介面函式庫 (macOS / Linux)

    $ cd arrow/java
$ export JAVA_HOME=<absolute path to your java home>
$ java --version
$ mvn generate-resources -Pgenerate-libs-cdata-all-os -N
$ ls -latr ../java-dist/lib
|__ arrow_cdata_jni/

  • 若要僅建置 JNI C 資料介面函式庫 (Windows)

    $ cd arrow/java
$ mvn generate-resources -Pgenerate-libs-cdata-all-os -N
$ dir "../java-dist/bin"
|__ arrow_cdata_jni/

  • 若要建置除了 JNI C 資料介面函式庫以外的所有 JNI 函式庫 (macOS / Linux)

    $ cd arrow/java
$ export JAVA_HOME=<absolute path to your java home>
$ java --version
$ mvn generate-resources -Pgenerate-libs-jni-macos-linux -N
$ ls -latr java-dist/lib
|__ arrow_dataset_jni/
|__ arrow_orc_jni/
|__ gandiva_jni/

  • 若要建置除了 JNI C 資料介面函式庫以外的所有 JNI 函式庫 (Windows)

    $ cd arrow/java
$ mvn generate-resources -Pgenerate-libs-jni-windows -N
$ dir "../java-dist/bin"
|__ arrow_dataset_jni/

CMake#

  • 若要僅建置 JNI C 資料介面函式庫 (macOS / Linux)

    $ cd arrow
$ mkdir -p java-dist java-cdata
$ cmake \
    -S java \
    -B java-cdata \
    -DARROW_JAVA_JNI_ENABLE_C=ON \
    -DARROW_JAVA_JNI_ENABLE_DEFAULT=OFF \
    -DBUILD_TESTING=OFF \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=java-dist
$ cmake --build java-cdata --target install --config Release
$ ls -latr java-dist/lib
|__ arrow_cdata_jni/

  • 若要僅建置 JNI C 資料介面函式庫 (Windows)

    $ cd arrow
$ mkdir java-dist, java-cdata
$ cmake ^
    -S java ^
    -B java-cdata ^
    -DARROW_JAVA_JNI_ENABLE_C=ON ^
    -DARROW_JAVA_JNI_ENABLE_DEFAULT=OFF ^
    -DBUILD_TESTING=OFF ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_INSTALL_PREFIX=java-dist
$ cmake --build java-cdata --target install --config Release
$ dir "java-dist/bin"
|__ arrow_cdata_jni/

  • 若要建置除了 JNI C 資料介面函式庫以外的所有 JNI 函式庫 (macOS / Linux)

    $ cd arrow
$ brew bundle --file=cpp/Brewfile
# Homebrew Bundle complete! 25 Brewfile dependencies now installed.
$ brew uninstall aws-sdk-cpp
#  (We can't use aws-sdk-cpp installed by Homebrew because it has
#  an issue: https://github.com/aws/aws-sdk-cpp/issues/1809 )
$ export JAVA_HOME=<absolute path to your java home>
$ mkdir -p java-dist cpp-jni
$ cmake \
    -S cpp \
    -B cpp-jni \
    -DARROW_BUILD_SHARED=OFF \
    -DARROW_CSV=ON \
    -DARROW_DATASET=ON \
    -DARROW_DEPENDENCY_SOURCE=BUNDLED \
    -DARROW_DEPENDENCY_USE_SHARED=OFF \
    -DARROW_FILESYSTEM=ON \
    -DARROW_GANDIVA=ON \
    -DARROW_GANDIVA_STATIC_LIBSTDCPP=ON \
    -DARROW_JSON=ON \
    -DARROW_ORC=ON \
    -DARROW_PARQUET=ON \
    -DARROW_S3=ON \
    -DARROW_SUBSTRAIT=ON \
    -DARROW_USE_CCACHE=ON \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=java-dist \
    -DCMAKE_UNITY_BUILD=ON
$ cmake --build cpp-jni --target install --config Release
$ cmake \
    -S java \
    -B java-jni \
    -DARROW_JAVA_JNI_ENABLE_C=OFF \
    -DARROW_JAVA_JNI_ENABLE_DEFAULT=ON \
    -DBUILD_TESTING=OFF \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=java-dist \
    -DCMAKE_PREFIX_PATH=$PWD/java-dist \
    -DProtobuf_ROOT=$PWD/../cpp-jni/protobuf_ep-install \
    -DProtobuf_USE_STATIC_LIBS=ON
$ cmake --build java-jni --target install --config Release
$ ls -latr java-dist/lib/
|__ arrow_dataset_jni/
|__ arrow_orc_jni/
|__ gandiva_jni/

  • 若要建置除了 JNI C 資料介面函式庫以外的所有 JNI 函式庫 (Windows)

    $ cd arrow
$ mkdir java-dist, cpp-jni
$ cmake ^
    -S cpp ^
    -B cpp-jni ^
    -DARROW_BUILD_SHARED=OFF ^
    -DARROW_CSV=ON ^
    -DARROW_DATASET=ON ^
    -DARROW_DEPENDENCY_USE_SHARED=OFF ^
    -DARROW_FILESYSTEM=ON ^
    -DARROW_GANDIVA=OFF ^
    -DARROW_JSON=ON ^
    -DARROW_ORC=ON ^
    -DARROW_PARQUET=ON ^
    -DARROW_S3=ON ^
    -DARROW_SUBSTRAIT=ON ^
    -DARROW_USE_CCACHE=ON ^
    -DARROW_WITH_BROTLI=ON ^
    -DARROW_WITH_LZ4=ON ^
    -DARROW_WITH_SNAPPY=ON ^
    -DARROW_WITH_ZLIB=ON ^
    -DARROW_WITH_ZSTD=ON ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_INSTALL_PREFIX=java-dist ^
    -DCMAKE_UNITY_BUILD=ON ^
    -GNinja
$ cd cpp-jni
$ ninja install
$ cd ../
$ cmake ^
    -S java ^
    -B java-jni ^
    -DARROW_JAVA_JNI_ENABLE_C=OFF ^
    -DARROW_JAVA_JNI_ENABLE_DATASET=ON ^
    -DARROW_JAVA_JNI_ENABLE_DEFAULT=ON ^
    -DARROW_JAVA_JNI_ENABLE_GANDIVA=OFF ^
    -DARROW_JAVA_JNI_ENABLE_ORC=ON ^
    -DBUILD_TESTING=OFF ^
    -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_INSTALL_PREFIX=java-dist ^
    -DCMAKE_PREFIX_PATH=$PWD/java-dist
$ cmake --build java-jni --target install --config Release
$ dir "java-dist/bin"
|__ arrow_orc_jni/
|__ arrow_dataset_jni/

Archery#

$ cd arrow
$ archery docker run java-jni-manylinux-2014
$ ls -latr java-dist
|__ arrow_cdata_jni/
|__ arrow_dataset_jni/
|__ arrow_orc_jni/
|__ gandiva_jni/

建置 Java JNI 模組#

  • 若要編譯 JNI 綁定，請使用 arrow-c-data Maven Profile

    $ cd arrow/java
$ mvn -Darrow.c.jni.dist.dir=<absolute path to your arrow folder>/java-dist/lib -Parrow-c-data clean install

  • 若要編譯 ORC / Gandiva / Dataset 的 JNI 綁定，請使用 arrow-jni Maven Profile

    $ cd arrow/java
$ mvn \
    -Darrow.cpp.build.dir=<absolute path to your arrow folder>/java-dist/lib/ \
    -Darrow.c.jni.dist.dir=<absolute path to your arrow folder>/java-dist/lib/ \
    -Parrow-jni clean install

測試#

預設情況下，Maven 會使用相同的 Java 版本來建置程式碼和執行測試。

也可以為測試使用不同的 JDK 版本。這需要事先設定 Maven Toolchains，然後設定特定的測試屬性。

設定 Maven Toolchains#

為了能夠使用 JDK 版本進行測試，需要先在 Maven toolchains.xml 設定檔中註冊，通常位於 ${HOME}/.m2 下，並在其中加入以下程式碼片段

<?xml version="1.0" encoding="UTF8"?>
<toolchains>

  [...]

  <toolchain>
    <type>jdk</type>
    <provides>
      <version>21</version> <!-- Replace with the corresponding JDK version: 11, 17, ... -->
      <vendor>temurin</vendor> <!-- Replace with the vendor/distribution: temurin, oracle, zulu ... -->
    </provides>
    <configuration>
      <jdkHome>path/to/jdk/home</jdkHome> <!-- Replace with the path to the JDK -->
    </configuration>
  </toolchain>

  [...]

</toolchains>

使用特定 JDK 進行測試#

若要使用特定 JDK 版本執行 Arrow 測試，請使用 arrow.test.jdk-version 屬性。

例如，若要使用 JDK 17 執行 Arrow 測試，請使用以下程式碼片段

$ cd arrow/java
$ mvn -Darrow.test.jdk-version=17 clean verify

IDE 設定#

IntelliJ#

若要在 IntelliJ 中開始使用 Arrow：先從命令列使用 mvn clean install 建置專案一次。然後開啟 Arrow 儲存庫的 java/ 子目錄，並更新以下設定

  • 在「檔案」工具視窗中，找到路徑 vector/target/generated-sources，在目錄上按一下滑鼠右鍵，然後選取「標記目錄為」>「產生的來源根目錄」。無需標記其他產生的來源目錄，因為只有 vector 模組會產生來源。

  • 對於 JDK 11，由於 IntelliJ 錯誤，您必須進入「設定」>「建置、執行、部署」>「編譯器」>「Java 編譯器」，並停用「針對交叉編譯使用 ‘–release’ 選項 (Java 9 及更新版本)」。否則您會收到類似「套件 sun.misc 不存在」的錯誤。

  • 如果 error-prone 發出偽造警告，您可能想要完全停用它（在 Maven 工具視窗中停用 error-prone 設定檔和「重新載入所有 Maven 專案」）。

  • 如果使用 IntelliJ 的 Maven 整合功能來建置，您可能需要由於 IntelliJ 錯誤，將 pom.xml 檔案中的 <fork> 變更為 false。

  • 若要啟用偵錯 JNI 基礎模組 (例如 dataset)，請在「設定檔」下的 Maven 標籤中啟用特定設定檔。確保啟用 arrow-c-data、arrow-jni、generate-libs-cdata-all-os、generate-libs-jni-macos-linux 和 jdk11+ 設定檔，以便 IDE 可以建置它們並啟用偵錯。

如果您使用 IntelliJ Maven 整合功能而非直接使用 IntelliJ 進行建置/測試，您可能不需要更新所有這些設定。

常見錯誤#

  • 當使用 JNI 程式碼時：如果 C++ 建置找不到相依性，並出現如下錯誤

    Could NOT find Boost (missing: Boost_INCLUDE_DIR system filesystem)
Could NOT find Lz4 (missing: LZ4_LIB)
Could NOT find zstd (missing: ZSTD_LIB)

    指定應在建置時下載相依性（更多詳細資訊請參閱〈相依性解析〉）

    -Dre2_SOURCE=BUNDLED \
-DBoost_SOURCE=BUNDLED \
-Dutf8proc_SOURCE=BUNDLED \
-DSnappy_SOURCE=BUNDLED \
-DORC_SOURCE=BUNDLED \
-DZLIB_SOURCE=BUNDLED

安裝每夜建置套件#

警告

這些套件並非官方發行版本。使用風險自負。

Arrow 每夜建置會發布在郵寄清單 builds@arrow.apache.org 上。成品會上傳到 GitHub。例如，對於 2022/07/30，可以在 GitHub Nightly 中找到它們。

從 Apache 每夜建置安裝#

  1. 查閱所使用 Arrow 函式庫的每夜建置版本號碼。

    例如，對於 arrow-memory，請造訪 https://nightlies.apache.org/arrow/java/org/apache/arrow/arrow-memory/ 並查看有哪些版本可用（例如 9.0.0.dev501）。

  2. 將 Apache 每夜建置儲存庫新增至 Maven/Gradle 專案。

    <properties>
   <arrow.version>9.0.0.dev501</arrow.version>
</properties>
...
<repositories>
   <repository>
         <id>arrow-apache-nightlies</id>
         <url>https://nightlies.apache.org/arrow/java</url>
   </repository>
</repositories>
...
<dependencies>
   <dependency>
         <groupId>org.apache.arrow</groupId>
         <artifactId>arrow-vector</artifactId>
         <version>${arrow.version}</version>
   </dependency>
</dependencies>
...

手動安裝#

  1. 決定要使用的每夜建置套件儲存庫，例如：ursacomputing/crossbow

  2. 將套件新增至您的 pom.xml，例如：flight-core（它相依於：arrow-format、arrow-vector、arrow-memory-core 和 arrow-memory-netty）。

    <properties>
   <maven.compiler.source>8</maven.compiler.source>
   <maven.compiler.target>8</maven.compiler.target>
   <arrow.version>9.0.0.dev501</arrow.version>
</properties>

<dependencies>
   <dependency>
         <groupId>org.apache.arrow</groupId>
         <artifactId>flight-core</artifactId>
         <version>${arrow.version}</version>
   </dependency>
</dependencies>

  3. 將必要的 pom 和 jar 檔案下載到暫存目錄

    $ mkdir nightly-packaging-2022-07-30-0-github-java-jars
$ cd nightly-packaging-2022-07-30-0-github-java-jars
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-java-root-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-format-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-format-9.0.0.dev501.jar
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-vector-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-vector-9.0.0.dev501.jar
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-memory-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-memory-core-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-memory-netty-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-memory-core-9.0.0.dev501.jar
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-memory-netty-9.0.0.dev501.jar
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/arrow-flight-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/flight-core-9.0.0.dev501.pom
$ wget https://github.com/ursacomputing/crossbow/releases/download/nightly-packaging-2022-07-30-0-github-java-jars/flight-core-9.0.0.dev501.jar
$ tree
.
├── arrow-flight-9.0.0.dev501.pom
├── arrow-format-9.0.0.dev501.jar
├── arrow-format-9.0.0.dev501.pom
├── arrow-java-root-9.0.0.dev501.pom
├── arrow-memory-9.0.0.dev501.pom
├── arrow-memory-core-9.0.0.dev501.jar
├── arrow-memory-core-9.0.0.dev501.pom
├── arrow-memory-netty-9.0.0.dev501.jar
├── arrow-memory-netty-9.0.0.dev501.pom
├── arrow-vector-9.0.0.dev501.jar
├── arrow-vector-9.0.0.dev501.pom
├── flight-core-9.0.0.dev501.jar
└── flight-core-9.0.0.dev501.pom

  4. 使用 mvn install:install-file 將成品安裝到本機 Maven 儲存庫

    $ mvn install:install-file -Dfile="$(pwd)/arrow-java-root-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-java-root -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/arrow-format-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-format -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/arrow-format-9.0.0.dev501.jar" -DgroupId=org.apache.arrow -DartifactId=arrow-format -Dversion=9.0.0.dev501 -Dpackaging=jar
$ mvn install:install-file -Dfile="$(pwd)/arrow-vector-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-vector -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/arrow-vector-9.0.0.dev501.jar" -DgroupId=org.apache.arrow -DartifactId=arrow-vector -Dversion=9.0.0.dev501 -Dpackaging=jar
$ mvn install:install-file -Dfile="$(pwd)/arrow-memory-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-memory -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/arrow-memory-core-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-memory-core -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/arrow-memory-netty-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-memory-netty -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/arrow-memory-core-9.0.0.dev501.jar" -DgroupId=org.apache.arrow -DartifactId=arrow-memory-core -Dversion=9.0.0.dev501 -Dpackaging=jar
$ mvn install:install-file -Dfile="$(pwd)/arrow-memory-netty-9.0.0.dev501.jar" -DgroupId=org.apache.arrow -DartifactId=arrow-memory-netty -Dversion=9.0.0.dev501 -Dpackaging=jar
$ mvn install:install-file -Dfile="$(pwd)/arrow-flight-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=arrow-flight -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/flight-core-9.0.0.dev501.pom" -DgroupId=org.apache.arrow -DartifactId=flight-core -Dversion=9.0.0.dev501 -Dpackaging=pom
$ mvn install:install-file -Dfile="$(pwd)/flight-core-9.0.0.dev501.jar" -DgroupId=org.apache.arrow -DartifactId=flight-core -Dversion=9.0.0.dev501 -Dpackaging=jar

  5. 驗證套件已安裝

    $ tree ~/.m2/repository/org/apache/arrow
.
├── arrow-flight
│   ├── 9.0.0.dev501
│   │   └── arrow-flight-9.0.0.dev501.pom
├── arrow-format
│   ├── 9.0.0.dev501
│   │   ├── arrow-format-9.0.0.dev501.jar
│   │   └── arrow-format-9.0.0.dev501.pom
├── arrow-java-root
│   ├── 9.0.0.dev501
│   │   └── arrow-java-root-9.0.0.dev501.pom
├── arrow-memory
│   ├── 9.0.0.dev501
│   │   └── arrow-memory-9.0.0.dev501.pom
├── arrow-memory-core
│   ├── 9.0.0.dev501
│   │   ├── arrow-memory-core-9.0.0.dev501.jar
│   │   └── arrow-memory-core-9.0.0.dev501.pom
├── arrow-memory-netty
│   ├── 9.0.0.dev501
│   │   ├── arrow-memory-netty-9.0.0.dev501.jar
│   │   └── arrow-memory-netty-9.0.0.dev501.pom
├── arrow-vector
│   ├── 9.0.0.dev501
│   │   ├── _remote.repositories
│   │   ├── arrow-vector-9.0.0.dev501.jar
│   │   └── arrow-vector-9.0.0.dev501.pom
└── flight-core
   ├── 9.0.0.dev501
   │   ├── flight-core-9.0.0.dev501.jar
   │   └── flight-core-9.0.0.dev501.pom

  6. 像往常一樣使用 mvn clean install 編譯您的專案。

安裝預發布套件#

警告

這些套件並非官方發行版本。使用風險自負。

當準備發行候選版本 (RC) 時，會建立 Arrow 預發布建置。這可讓使用者在投票決定發行版本之前，在其應用程式中測試 RC。

從 Apache 預發布安裝#

  1. 查閱所使用 Arrow 函式庫的下一個版本號碼。

  2. 將 Apache 預發布儲存庫新增至 Maven/Gradle 專案。

    <properties>
   <arrow.version>9.0.0</arrow.version>
</properties>
...
<repositories>
   <repository>
         <id>arrow-apache-staging</id>
         <url>https://repository.apache.org/content/repositories/staging</url>
   </repository>
</repositories>
...
<dependencies>
   <dependency>
         <groupId>org.apache.arrow</groupId>
         <artifactId>arrow-vector</artifactId>
         <version>${arrow.version}</version>
   </dependency>
</dependencies>
...