跳到內容

設定開發者環境

來源：vignettes/developers/setup.Rmd
setup.Rmd

相較於您可能貢獻過的其他 R 套件，Arrow R 套件是獨特的，因為它是建立在大型且功能豐富的 Arrow C++ 實作之上。由於 R 套件與 Arrow C++ 緊密整合，因此通常需要該程式庫的專用副本（即，在開發期間通常無法連結到系統版本的 libarrow）。

選項 1：使用 nightly libarrow 二進位檔

在 Linux、macOS 和 Windows 上，您可以使用與其他包含編譯程式碼的套件相同的工作流程（例如，從終端機執行 R CMD INSTALL .、從 R 提示字元執行 devtools::load_all()，或從 RStudio 執行 Install & Restart）。如果 arrow/r/libarrow 目錄未填入內容，則設定腳本將嘗試下載最新的 nightly libarrow 二進位檔，將其解壓縮到 arrow/r/libarrow 目錄 (macOS、Linux) 或 arrow/r/windows 目錄 (Windows)，並照常繼續建置 R 套件。

大多數時候，您不需要更新 libarrow 版本，因為 R 套件很少隨著 C++ 程式庫的更新而變更；但是，如果您在重建 R 套件時開始遇到錯誤，您可能需要移除 libarrow 目錄 (macOS、Linux) 或 windows 目錄 (Windows)，並執行「乾淨」重建。您可以從終端機使用 R CMD INSTALL . --preclean、從 RStudio 使用「Build」標籤中的「Clean and Install」選項，或者如果您使用 R 套件根目錄中的 Makefile，則可以使用 make clean 來執行此操作。

選項 2：使用本機 Arrow C++ 開發建置版本

如果您需要同時修改 libarrow 和 R 套件程式碼，或者如果您無法在其他地方取得最新 libarrow 的二進位版本，則需要從原始碼建置它。本節討論如何設定 C++ libarrow 建置版本，使其與 R 套件搭配使用。如需更通用的資源，請參閱 Arrow C++ 開發人員指南。

此過程包含五個主要步驟。

步驟 1 - 安裝相依性

在建置 libarrow 時，預設情況下，如果找到合適的版本，將使用系統相依性。如果系統相依性不存在，libarrow 將在其自身的建置過程中建置它們。您需要在建置過程之外安裝的唯一相依性是 cmake（用於設定建置）以及如果您使用 S3 支援進行建置，則需要安裝 openssl。

為了加快建置速度，您可以選擇預先安裝更多 C++ 程式庫相依性（例如 lz4、zstd 等）在系統上，這樣它們就不需要在 libarrow 建置中從原始碼建置。

Ubuntu
sudo apt install -y cmake libcurl4-openssl-dev libssl-dev
macOS
brew install cmake openssl

步驟 2 - 設定 libarrow 建置

我們建議您將 libarrow 設定為建置到使用者層級目錄，而不是系統目錄，以進行開發工作。這樣做的目的是為了讓您正在使用的開發版本不會覆寫您可能已安裝的 libarrow 發行版本，並且讓您能夠使用多個版本的 libarrow（透過針對不同版本使用不同的 ARROW_HOME 目錄）。

在下面的範例中，libarrow 安裝到名為 dist 的目錄中，該目錄與 arrow 簽出目錄具有相同的父目錄。您的 Arrow R 套件安裝可以指向任何名稱的任何目錄，但我們建議不要將其放置在 arrow git 簽出目錄內，因為不必要的變更可能會使其無法正常運作。

export ARROW_HOME=$(pwd)/dist
mkdir $ARROW_HOME

Linux 上的特殊說明： 在啟動 R 並使用 arrow 之前，您需要將 LD_LIBRARY_PATH 設定為您設定 $ARROW_HOME 下的 lib 目錄。一種方法是將其新增到您的設定檔中（我們在此處使用 ~/.bash_profile，但您可能需要將其放在不同的檔案中，具體取決於您的設定，例如，如果您使用 bash 以外的 shell）。在 macOS 上，您不需要執行此操作，因為 macOS 共用程式庫路徑在建置時已硬編碼到其位置。

export LD_LIBRARY_PATH=$ARROW_HOME/lib:$LD_LIBRARY_PATH
echo "export LD_LIBRARY_PATH=$ARROW_HOME/lib:$LD_LIBRARY_PATH" >> ~/.bash_profile

首先在終端機中導航到 arrow 儲存庫。您需要建立一個目錄，C++ 建置將把其內容放入其中。我們建議您在 Arrow git 儲存庫的 cpp 目錄內建立一個 build 目錄（它會被 git 忽略，因此您不會意外地將其簽入）。接下來，變更目錄以進入 cpp/build 內部

pushd arrow
mkdir -p cpp/build
pushd cpp/build

您將首先呼叫 cmake 來設定建置，然後呼叫 make install。對於 R 套件，您需要使用 -D 旗標在 libarrow 中啟用多個功能

Linux / Mac OS
cmake \
  -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
  -DCMAKE_INSTALL_LIBDIR=lib \
  -DARROW_COMPUTE=ON \
  -DARROW_CSV=ON \
  -DARROW_DATASET=ON \
  -DARROW_EXTRA_ERROR_CONTEXT=ON \
  -DARROW_FILESYSTEM=ON \
  -DARROW_INSTALL_NAME_RPATH=OFF \
  -DARROW_JEMALLOC=ON \
  -DARROW_JSON=ON \
  -DARROW_PARQUET=ON \
  -DARROW_WITH_SNAPPY=ON \
  -DARROW_WITH_ZLIB=ON \
  ..

.. 指的是 C++ 原始碼目錄：您位於 cpp/build 中，而原始碼位於 cpp 中。

啟用更多 Arrow 功能

若要啟用選用功能，包括：S3 支援、替代記憶體配置器和額外的壓縮程式庫，請將以下部分或全部旗標新增到您的 cmake 呼叫中（尾隨的 \ 使它們更容易貼到新行的 bash shell 中）

  -DARROW_GCS=ON \
  -DARROW_MIMALLOC=ON \
  -DARROW_S3=ON \
  -DARROW_WITH_BROTLI=ON \
  -DARROW_WITH_BZ2=ON \
  -DARROW_WITH_LZ4=ON \
  -DARROW_WITH_SNAPPY=ON \
  -DARROW_WITH_ZSTD=ON \

其他可能有用的旗標

  • -DBoost_SOURCE=BUNDLED 和 -DThrift_SOURCE=BUNDLED，例如，或任何其他相依性 *_SOURCE，如果您有系統版本的 C++ 相依性無法與 Arrow 正常運作。這會告知建置從原始碼編譯其自身的相依性版本。

  • -DCMAKE_BUILD_TYPE=debug 或 -DCMAKE_BUILD_TYPE=relwithdebinfo 對於偵錯可能很有用。您可能通常不希望這樣做，因為偵錯建置版本的執行速度比預設 release 建置版本慢得多。

  • -DARROW_BUILD_STATIC=ON 和 -DARROW_BUILD_SHARED=OFF，如果您想要使用靜態程式庫而不是動態程式庫。使用靜態程式庫，R 套件沒有連結到錯誤程式庫的風險，但這表示如果您變更 C++ 程式碼，則必須重新編譯 C++ 程式庫和 R 套件。編譯器通常只會在動態程式庫不存在時連結到靜態程式庫，這就是為什麼我們需要設定 -DARROW_BUILD_SHARED=OFF。如果您在先前編譯和安裝後進行切換，您可能需要從 $ARROW_HOME/dist/bin 中移除 .dll 或 .so 檔案。

注意 cmake 對於空白字元特別敏感，如果您看到錯誤，請檢查您是否沒有任何錯誤的空白字元。

步驟 3 - 建置 libarrow

您也可以在此命令的末尾新增 -j#，以透過平行執行來加速編譯（其中 # 是您可用的核心數）。

cmake --build . --target install -j8

步驟 4 - 建置 Arrow R 套件

建置 libarrow 後，您可以從 git 簽出安裝 R 套件及其相依性，以及額外的開發相依性

popd # To go back to the root directory of the project, from cpp/build
pushd r
R -e "install.packages('remotes'); remotes::install_deps(dependencies = TRUE)"
R CMD INSTALL --no-multiarch .

--no-multiarch 旗標使其僅在「主要」架構上編譯。這將針對您的路徑中 R 對應的架構進行編譯。如果您在一個架構上編譯，然後切換到另一個架構，請務必傳遞 --preclean 旗標，以便為新架構重新編譯 R 套件程式碼。否則，您可能會看到類似 LoadLibrary failure: %1 is not a valid Win32 application 的錯誤。

編譯旗標

如果您需要在建置 C++ 擴充功能時設定任何編譯旗標，您可以使用 ARROW_R_CXXFLAGS 環境變數。例如，如果您使用 perf 來分析 R 擴充功能，您可能需要設定

export ARROW_R_CXXFLAGS=-fno-omit-frame-pointer
重新編譯 C++ 程式碼

使用此處描述的設定，當您迭代並處理 R 套件時，您不應該需要重建 Arrow 程式庫，甚至不需要重建 R 套件中的 C++ 原始碼。唯一需要重建它們的時間是，如果您已變更 R 套件中的 C++（即使那樣，R CMD INSTALL . 也應該只需要重新編譯已變更的檔案），或者如果 libarrow C++ 已變更並且 libarrow 與 R 套件之間存在不符。如果您發現每次安裝套件或執行測試時都需要重建其中一個或兩個，則您的設定可能存在問題。

對於完整建置：包含所有與 R 相關的選用相依性開啟的 cmake 命令。使用其他語言進行開發也可能需要不同的旗標。例如，若要開發 Python，您還需要新增 -DARROW_PYTHON=ON（雖然用於 Python 的所有其他旗標都已包含在此處）。

cmake \
  -DCMAKE_INSTALL_PREFIX=$ARROW_HOME \
  -DCMAKE_INSTALL_LIBDIR=lib \
  -DARROW_COMPUTE=ON \
  -DARROW_CSV=ON \
  -DARROW_DATASET=ON \
  -DARROW_EXTRA_ERROR_CONTEXT=ON \
  -DARROW_FILESYSTEM=ON \
  -DARROW_GCS=ON \
  -DARROW_INSTALL_NAME_RPATH=OFF \
  -DARROW_JEMALLOC=ON \
  -DARROW_JSON=ON \
  -DARROW_MIMALLOC=ON \
  -DARROW_PARQUET=ON \
  -DARROW_S3=ON \
  -DARROW_WITH_BROTLI=ON \
  -DARROW_WITH_BZ2=ON \
  -DARROW_WITH_LZ4=ON \
  -DARROW_WITH_SNAPPY=ON \
  -DARROW_WITH_ZLIB=ON \
  -DARROW_WITH_ZSTD=ON \
  ..

安裝具有特定 git 參考的 R 套件版本

如果您需要來自特定儲存庫或 git 參考的 arrow 安裝，在大多數平台（Windows 除外）上，您可以執行

remotes::install_github("apache/arrow/r", build = FALSE)

build = FALSE 引數很重要，以便安裝可以存取 apache/arrow 中 cpp/ 目錄中的 C++ 原始碼。

與其他安裝方法一樣，設定環境變數 LIBARROW_MINIMAL=false 和 ARROW_R_DEV=true 將提供功能更完整的 Arrow 版本，並提供更詳細的輸出。

例如，若要從 apache/arrow 的（虛構）分支 bugfix 安裝，您可以執行

Sys.setenv(LIBARROW_MINIMAL="false")
remotes::install_github("apache/arrow/r@bugfix", build = FALSE)

開發人員可能希望使用此方法安裝與另一個 Arrow 開發環境或系統安裝隔離的特定 commit（例如，我們在 arrowbench 中使用此方法來安裝與系統安裝隔離的 libarrow 開發版本）。如果您已在系統範圍內安裝 libarrow，您可能需要設定一些額外的變數，以便將此建置與您的系統程式庫隔離

  • 將環境變數 FORCE_BUNDLED_BUILD 設定為 true 將跳過對 libarrow 的 pkg-config 搜尋，並嘗試從給定的儲存庫 + 參考中的相同來源建置。

  • 您可能還需要將 Makevars CPPFLAGS 和 LDFLAGS 設定為 ""，以防止安裝過程嘗試連結到已安裝的系統版本的 libarrow。暫時執行此操作的一種方法是將您的 remotes::install_github() 呼叫包裝成如下所示

withr::with_makevars(list(CPPFLAGS = "", LDFLAGS = ""), remotes::install_github(...))

環境變數摘要

  • 請參閱使用者導向的安裝文章，以取得大量決定建置運作方式和建置哪些功能的環境變數。
  • ARROW_OFFLINE_BUILD：當設定為 true 時，建置腳本將不會下載預先建置的 C++ 程式庫二進位檔，或在需要時下載 cmake。它將關閉任何需要下載的功能，除非它們在 ARROW_THIRDPARTY_DEPENDENCY_DIR 或 tools/thirdparty_download/ 子資料夾中可用。create_package_with_all_dependencies() 建立該子資料夾。

疑難排解

請注意，在對 libarrow 進行任何變更後，您必須重新安裝它，並執行 make clean 或 git clean -fdx . 以移除 r/src/ 目錄中的任何快取物件程式碼，然後再重新安裝 R 套件。只有在您變更 libarrow 原始碼時才需要這樣做；如果您僅編輯 r/ 內部的 R 或 C++ 程式碼，則無需手動清除物件檔案。

Arrow 程式庫 - R 套件不符

如果 libarrow 和 R 套件已發散，您將看到類似以下的錯誤

Error: package or namespace load failed for ‘arrow' in dyn.load(file, DLLpath = DLLpath, ...):
 unable to load shared object '/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so':
  dlopen(/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so, 6): Symbol not found: __ZN5arrow2io16RandomAccessFile9ReadAsyncERKNS0_9IOContextExx
  Referenced from: /Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so
  Expected in: flat namespace
 in /Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so
Error: loading failed
Execution halted
ERROR: loading failed

若要解決此問題，請嘗試重建 Arrow 程式庫。

libarrow 的多個版本

如果您從使用者層級目錄安裝，並且您已在系統目錄中安裝了先前的 libarrow，則在安裝 R 套件時可能會遇到類似以下的錯誤

Error: package or namespace load failed for ‘arrow' in dyn.load(file, DLLpath = DLLpath, ...):
 unable to load shared object '/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so':
  dlopen(/Library/Frameworks/R.framework/Versions/4.0/Resources/library/00LOCK-r/00new/arrow/libs/arrow.so, 6): Library not loaded: /usr/local/lib/libarrow.400.dylib
  Referenced from: /usr/local/lib/libparquet.400.dylib
  Reason: image not found

如果發生這種情況，您需要確保在建置 arrow 時不要讓 R 連結到您的系統程式庫。您可以使用多種不同的方法來執行此操作

  • 將 MAKEFLAGS 環境變數設定為 "LDFLAGS="（請參閱下面的範例）這是完成此操作的建議方法
  • 使用 {withr} 的 with_makevars(list(LDFLAGS = ""), ...)
  • 將 LDFLAGS= 新增到您的 ~/.R/Makevars 檔案（最不建議的方法，儘管它是線上建議的常見偵錯方法）
MAKEFLAGS="LDFLAGS=" R CMD INSTALL .

rpath 問題

如果套件安裝/載入失敗，並出現類似以下的錯誤

  ** testing if installed package can be loaded from temporary location
  Error: package or namespace load failed for 'arrow' in dyn.load(file, DLLpath = DLLpath, ...):
  unable to load shared object '/Users/you/R/00LOCK-r/00new/arrow/libs/arrow.so':
  dlopen(/Users/you/R/00LOCK-r/00new/arrow/libs/arrow.so, 6): Library not loaded: @rpath/libarrow.14.dylib

請確保已傳遞 -DARROW_INSTALL_NAME_RPATH=OFF（這在 macOS 上很重要，以防止連結時出現問題，並且在其他平台上不起作用）。或者，嘗試將環境變數 R_LD_LIBRARY_PATH 設定為 Arrow C++ 在 make install 中放置的位置，例如 export R_LD_LIBRARY_PATH=/usr/local/lib，然後重試安裝 R 套件。

從原始碼安裝時，如果 R 和 C++ 程式庫版本不符，則安裝可能會失敗。如果您先前已安裝程式庫並想要升級 R 套件，則需要先更新 Arrow C++ 程式庫。

對於任何其他建置/設定挑戰，請參閱 C++ 開發人員指南。

其他安裝問題

在安裝 arrow R 套件時，會觸發許多腳本。對於不與底層程式碼互動的套件使用者，這些都應該可以正常運作，而無需設定，並提取最完整的組件（例如，我們託管的官方二進位檔）。但是，了解這些腳本可以幫助套件開發人員在這些腳本中出現問題或安裝過程中出現問題時進行疑難排解。請參閱 關於 R 套件安裝的文章 以取得更多資訊。