Apache Arrow C 在 Windows 上的完整构建指南从环境准备到 CI 复现【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow本文是 Apache Arrow 官方开发者文档 docs/source/developers/cpp/windows.rst 的中文技术详解。与 Linux/macOS 一样Apache Arrow 的 C 库通过 CMake 在 Windows 上实现了开箱即用的构建支持。本文将系统性地讲解在 Windows 上编译 Apache Arrow C 的全部可行路径如何初始化 Visual Studio 开发环境、如何用 conda-forge 与 vcpkg 两种方案管理第三方依赖、如何用 MSVC 解决方案 / Ninja / NMake / MSYS2 等多种构建工具生成产物以及 Debug 构建、静态链接、WoA64 实验性构建和复现 Windows CI 等进阶话题。读完本文你将掌握在 Windows 上从零搭建 Arrow C 构建环境并完成编译与测试的完整实战能力。系统环境准备初始化 Visual Studio 开发环境Microsoft 免费提供 Visual Studio Community 版本其中包含编译 Arrow 所需的 MSVC 编译器与 Windows SDK。需要特别注意的是在 Shell 中进行开发时每次打开新的 Shell 都必须重新初始化开发环境编译器路径、环境变量等不会自动保留。对于 Visual Studio 2017在cmd.exe中执行以下批处理脚本C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools\VsDevCmd.bat -archamd64对于 Visual Studio 2019脚本路径为C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\VsDevCmd.bat -archamd64VsDevCmd.bat早期版本中为vcvarsall.bat会设置编译器、链接器、头文件与库文件的搜索路径。-archamd64指定以 64 位目标架构初始化环境Arrow C 在 Windows 上要求 64 位构建。如果你习惯使用控制台模拟器例如 cmder可以配置其在启动新开发控制台时自动执行上述初始化脚本省去每次手动运行的步骤。从源码结构看Arrow 的构建入口位于 cpp/CMakeLists.txt其依赖解析与构建选项定义分别在 cpp/cmake_modules/ThirdpartyToolchain.cmake 与 cpp/cmake_modules/DefineOptions.cmake 中后续所有构建方式最终都汇入这套 CMake 体系。使用 conda-forge 管理构建依赖conda-forge 是一个社区维护的跨平台 conda 软件包仓库Apache Arrow 社区的成员直接参与其维护。使用 conda-forge 作为 Windows 上 C 构建依赖的来源是最快的起步方式。1. 安装 Miniconda 并配置频道从 Miniconda 主页下载并安装 64 位发行版。然后启动一个命令提示符cmd.exe先运行上文所述的初始化命令vcvarsall.bat或VsDevCmd.bat再执行conda config --add channels conda-forge将conda-forge添加为默认频道后续创建环境时会优先从该频道解析依赖。2. 引导构建环境在 Arrow 代码库根目录下执行以下命令创建独立环境conda create -y -n arrow-dev --fileci\conda_env_cpp.txtci\conda_env_cpp.txt即 ci/conda_env_cpp.txt是 Arrow 维护的依赖清单文件内容包括类别依赖包压缩brotli、bzip2、lz4-c、zlib、zstd、snappy序列化/协议thrift-cpp0.11.0、libprotobuf、libgrpc、orc2.1.0、re2、simdjson、rapidjson云存储 SDKaws-sdk-cpp、azure-*core/identity/storage、google-cloud-cpp1.34.0、c-ares构建工具cmake、make、meson、ninja、pkg-config、python测试与基础库gtest1.10.0、gmock1.10.0、benchmark、gflags、glog、libboost-devel、libutf8proc、xsimd14.2然后激活该环境activate arrow-dev3. 依赖解析的自动识别机制环境激活后Arrow 的构建系统会自动检测%CONDA_PREFIX%环境变量并使用它来解析构建依赖等价于手动传入以下 CMake 参数-DARROW_DEPENDENCY_SOURCESYSTEM ^ -DARROW_PACKAGE_PREFIX%CONDA_PREFIX%\Library该机制在 cpp/cmake_modules/ThirdpartyToolchain.cmake 中实现当检测到CONDA_PREFIX时会将ARROW_PACKAGE_PREFIX设置为$ENV{CONDA_PREFIX}/Library并基于此前缀统一设置PKG_CONFIG_PATH、BOOST_ROOT/Boost_ROOT、OPENSSL_ROOT_DIR以及各依赖包的*_ROOT变量从而让 Find 脚本在 conda 安装目录下定位头文件与库文件。如果你希望直接使用 Visual Studio IDE 配合该 conda 环境开发只需在同一个命令提示符中运行devenv启动 IDE 即可继承全部环境变量。4. Release/Debug 库的链接限制注意以 conda 包形式安装的依赖均以 Release 模式构建无法与 Debug 构建链接。如果打算使用-DCMAKE_BUILD_TYPEdebug则必须从源码自行编译这些依赖包。可选的替代方案是-DCMAKE_BUILD_TYPErelwithdebinfo它产出的构建既可以链接 Release 库又保留可调试信息。常见问题排查使用 conda 包时最常见的问题是混用defaults频道与conda-forge频道的包。可以通过conda list检查当前环境中已安装的包及其来源。使用 vcpkg 管理构建依赖vcpkg 是 Microsoft 开源的 C/C 包管理器托管社区贡献的包移植port及其依赖。Arrow 在仓库中提供了一个清单文件 cpp/vcpkg.json精确声明了构建 C 库所需的 vcpkg 包集合。当前仓库中的清单声明了26.0.0-SNAPSHOT版本并锁定了builtin-baseline9b965a116838c6cd36cdbca60d1b81b030c8ab8d依赖包括abseil、aws-sdk-cpp含 s3/sts/transfer 等 feature、boost-*系列、brotli、bzip2、c-ares、curl、flatbuffers、grpc、gtest、lz4、openssl、orc、protobuf、rapidjson、re2、simdjson、snappy、sqlite3、thrift、utf8proc、xsimd、zlib、zstd等。1. 安装并集成 vcpkg首先安装 vcpkg 并完成与 Visual Studio 的集成。然后在cmd.exe中切换到 Arrow 根目录执行vcpkg install ^ --triplet x64-windows ^ --x-manifest-root cpp ^ --feature-flagsversions ^ --clean-after-build各参数含义--triplet x64-windows指定目标三元组。Windows 上 vcpkg 默认构建动态链接库如需静态库改用x64-windows-static。--x-manifest-root cpp指向包含 cpp/vcpkg.json 清单的目录vcpkg 会按清单安装全部依赖。--feature-flagsversions启用版本化解析配合清单中的builtin-baseline。--clean-after-build构建完成后清理中间产物。由于 vcpkg 会下载源码包并在本地编译安装依赖比 conda 更耗时。2. 在 CMake 中启用 vcpkg 依赖构建时传入-DARROW_DEPENDENCY_SOURCEVCPKG3. 可选的 vcpkg 覆盖变量CMake 变量默认行为覆盖用途-DCMAKE_TOOLCHAIN_FILECMake 脚本自动查找 vcpkg 的vcpkg.cmake工具链文件显式指定工具链文件位置-DVCPKG_TARGET_TRIPLETCMake 脚本尝试推断 vcpkg triplet显式指定 triplet-DARROW_DEPENDENCY_USE_SHARED默认ON动态库设为OFF使用静态库-DVCPKG_MANIFEST_MODE默认ON按 vcpkg.json 清单安装设为OFF忽略清单仅使用 vcpkg 安装目录下已安装的包vcpkg 的自动发现逻辑可在 cpp/cmake_modules/Usevcpkg.cmake 中看到它依次尝试从CMAKE_TOOLCHAIN_FILE反推、-DVCPKG_ROOT、环境变量VCPKG_ROOT、vcpkg integrate install写入的vcpkg.path.txt等途径定位 vcpkg 根目录若无法推断 triplet 则会直接报错要求显式指定。此外VCPKG依赖源在内部会被实现为SYSTEM依赖源处理见该文件末尾的ARROW_VCPKG缓存变量即 vcpkg 安装的包被当作系统包参与后续 Find 流程。使用 Visual StudioMSVC解决方案文件构建在cmd.exe中切换到 Arrow 根目录进行 out-of-source 构建源码与构建产物分离cd cpp mkdir build cd build cmake .. -G Visual Studio 16 2019 -A x64 ^ -DARROW_BUILD_TESTSON cmake --build . --config Release要点说明-G Visual Studio 16 2019 -A x64生成 MSVC 解决方案并指定 x64 架构。-DARROW_BUILD_TESTSON同时构建单元测试。cmake --build . --config Release在生成的解决方案上执行 Release 配置编译。对于更新版本的 Visual Studio将生成器指定为Visual Studio 17 2022可用cmake --help查看当前环境支持的全部生成器。使用 Ninja 与 sccache 构建Ninja 构建系统提供更好的并行度而可选的 sccache 编译器缓存会记录过往编译结果、避免重复编译类似 Unix 上的 ccache。确认/安装 Ninja较新版本的 Visual Studio 自带 Ninja。先运行环境初始化命令vcvarsall.bat或VsDevCmd.bat然后验证ninja --version若你的 Visual Studio 版本未包含 Ninja且使用 conda可激活环境后安装activate arrow-dev conda install -c conda-forge ninja不使用 conda 的用户可以从其他来源自行安装 Ninja。生成 Ninja 构建文件cd cpp mkdir build cd build cmake -G Ninja ^ -DARROW_BUILD_TESTSON ^ -DGTest_SOURCEBUNDLED .. cmake --build . --config Release注意这里的-DGTest_SOURCEBUNDLED使用 Ninja 单配置生成器时Arrow 会随源码一起编译 GoogleTest避免依赖预先安装的测试框架。启用 sccache 本地缓存以本地存储模式使用 sccache 时需在调用cmake前设置SCCACHE_DIR环境变量... set SCCACHE_DIR%LOCALAPPDATA%\Mozilla\sccache cmake -G Ninja ^ ...使用 NMake 构建NMake 是随 Visual Studio 提供的传统命令行构建工具cd cpp mkdir build cd build cmake -G NMake Makefiles .. nmake使用NMake Makefiles生成器生成 Makefile再直接调用nmake完成编译。在 MSYS2 上构建可以在 MSYS2 终端、cmd.exe或 PowerShell 终端中构建。在 MSYS2 终端中cd cpp mkdir build cd build cmake -G MSYS Makefiles .. make在cmd.exe或 PowerShell 终端中可以使用以下批处理文件注意其通过MINGW_PACKAGE_PREFIX、MINGW_PREFIX、MSYSTEM环境变量将 MSYS2 的 MinGW64 工具链引入PATH并清理重建cpp\build目录setlocal REM For 64bit set MINGW_PACKAGE_PREFIXmingw-w64-x86_64 set MINGW_PREFIXc:\msys64\mingw64 set MSYSTEMMINGW64 set PATH%MINGW_PREFIX%\bin;c:\msys64\usr\bin;%PATH% rmdir /S /Q cpp\build mkdir cpp\build pushd cpp\build cmake -G MSYS Makefiles .. || exit /B make || exit /B popd在 Windows/ARM64 上使用 Ninja 与 Clang 构建实验性Ninja 与 clang 可用于 windows/arm64WoA64平台上的库构建cd cpp mkdir build cd build set CCclang-cl set CXXclang-cl cmake -G Ninja .. cmake --build . --config Release关键约束与注意事项LLVM 工具链可从 LLVM 发布页面下载适用于 Windows on ARM64 的版本。MSVC 目前尚不能用于编译 win/arm64 构建原因是 xsimd、boost 等依赖存在兼容性问题。该构建仅处于实验阶段由于缺乏基础设施并非所有功能都经过 CI 的充分测试。Debug 构建要构建 Debug 版本的 Arrow需要预先安装 Debug 版本的 Boost。官方推荐为 Debug 构建配置以下 CMake 变量CMake 变量作用-DARROW_BOOST_USE_SHAREDOFF静态链接 boost debug 库简化第三方库的运行时加载-DBOOST_ROOT设置 boost 库根目录可选-DBOOST_LIBRARYDIR设置包含 boost 库文件的目录可选典型命令行如下cd cpp mkdir build cd build cmake .. -G Visual Studio 15 2017 -A x64 ^ -DARROW_BOOST_USE_SHAREDOFF ^ -DCMAKE_BUILD_TYPEDebug ^ -DBOOST_ROOTC:/local/boost_1_63_0 ^ -DBOOST_LIBRARYDIRC:/local/boost_1_63_0/lib64-msvc-14.0 cmake --build . --config Debug-DARROW_BOOST_USE_SHARED的默认值继承自ARROW_DEPENDENCY_USE_SHARED见 cpp/cmake_modules/DefineOptions.cmake因此 Debug 构建中显式关闭共享链接是推荐做法。另外根据你所用的 CMake 变量或预设preset构建时可能需要在PATH中提供patch工具。例如如果你已安装 Git for Windows可以把C:\Program Files\Git\usr\bin加入PATH。Windows 依赖解析问题静态库命名后缀Windows 使用.lib文件同时支持静态与动态链接因此静态库有时会以不同的名称如%PACKAGE%_static.lib来区分自身。如果你静态链接某些依赖可以传入以下选项解决库名匹配问题-DBROTLI_MSVC_STATIC_LIB_SUFFIX%BROTLI_SUFFIX%-DSNAPPY_MSVC_STATIC_LIB_SUFFIX%SNAPPY_SUFFIX%-LZ4_MSVC_STATIC_LIB_SUFFIX%LZ4_SUFFIX%-ZSTD_MSVC_STATIC_LIB_SUFFIX%ZSTD_SUFFIX%这些选项分别针对 brotli、snappy、lz4、zstd 四类压缩依赖的 MSVC 静态库后缀使 CMake 能够正确找到并链接静态变体。在 Windows 上静态链接 ArrowWindows 上启用ARROW_BUILD_STATIC在 cpp/cmake_modules/DefineOptions.cmake 中默认值为ON构建的 Arrow 静态库其头文件通过预处理宏ARROW_STATIC来抑制符号的 dllimport/dllexport 标记。在 Windows 上静态链接 Arrow 的项目同样需要定义该宏Unix 构建不使用此宏。该机制实现在 cpp/src/arrow/util/visibility.hWindows 分支中若定义了ARROW_STATIC则ARROW_EXPORT等宏展开为空不添加__declspec(dllexport/dllimport)否则根据是否正在导出ARROW_EXPORTING选择__declspec(dllexport)或__declspec(dllimport)。此外如果启用了-DARROW_FLIGHTON还需要定义ARROW_FLIGHT_STATIC-DARROW_FLIGHT_SQLON时同理定义ARROW_FLIGHT_SQL_STATIC。CMake 示例如下project(MyExample) find_package(Arrow REQUIRED) add_executable(my_example my_example.cc) target_link_libraries(my_example PRIVATE arrow_static arrow_flight_static arrow_flight_sql_static) target_compile_definitions(my_example PUBLIC ARROW_STATIC ARROW_FLIGHT_STATIC ARROW_FLIGHT_SQL_STATIC)时区数据库下载使用 MSVC 或较新的 MinGW GCC13构建时Arrow 分别使用 Windows 时区数据库或系统自带的 tzdata无需额外设置。而当使用 Clang/libc 构建例如 MSYS2 Clang64时需要先下载 IANA 时区数据库与 Windows 时区映射才能运行部分 compute 单元测试。仓库中的 ci/scripts/download_tz_database.sh 展示了完整流程从 IANA 下载tzdata-latest.tar.gz并解压再从 CLDR 下载windowsZones.xmlWindows 时区映射表。要在运行单元测试时指定非默认的时区数据库路径可设置ARROW_TIMEZONE_DATABASE环境变量。复现 Windows CI 构建对于熟悉 Linux 开发、但需要复现某个失败的 Windows CI 构建的开发者以下是官方记录的粗略步骤make unittest可能仍会失败但许多单元测试可以通过各自的独立 make 目标构建运行准备 Windows 虚拟机下载并安装 Microsoft 提供的带 Visual Studio 的 Windows 试用虚拟机镜像。安装基础工具在虚拟机中安装 Git、CMake、Miniconda 或 Anaconda以下步骤假设使用 Anaconda以及 Build Tools for Visual Studio。安装向导中务必勾选 C 工具链安装完成后重启。安装预编译的 Boost Debug 二进制下载并安装 pre-built Boost debug binaries。然后在 Anaconda/Miniconda 命令提示符而非 PowerShell中执行并先运行vcvarsall.bat x64其位置可能因安装路径而异例如 2019 Build Tools 下为C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat接着cd $EXTRACT_BOOST_DIRECTORY .\bootstrap.bat rem This is for static libraries needed for static_crt_build .\b2 linkstatic --with-filesystem --with-regex --with-system install rem this should put libraries and headers in c:\Boost激活 Anaconda/Minicondarem this might differ for miniconda C:\Users\User\Anaconda3\Scripts\activate克隆 Arrow 源码并切换到其根目录可能需要先安装 git。设置环境变量以下变量模拟 CI 的Static_Crt_Build任务SET JOBStatic_Crt_Build SET GENERATORNinja SET USE_CLCACHEfalse SET ARROW_BUILD_GANDIVAOFF SET ARROW_LLVM_VERSION8.0.* SET PYTHON3.9 SET ARCH64 SET PATHC:\Users\User\Anaconda3;C:\Users\User\Anaconda3\Scripts;C:\Users\User\Anaconda3\Library\bin;%PATH% SET BOOST_LIBRARYDIRC:\Boost\lib SET BOOST_ROOTC:\Boost安装依赖并构建conda install -c conda-forge --file .\ci\conda_env_cpp.txt git submodule update --init rem you can also just invoke cmake directly with the desired options cmake --build . --config Release --target arrow-compute-hash-testconda install按 ci/conda_env_cpp.txt 清单安装全部依赖git submodule update --init拉取 git 子模块最后一步直接构建指定的测试目标如arrow-compute-hash-test也可以按需直接调用cmake传入其他选项。小结在 Windows 上构建 Apache Arrow C 的路径是多元的依赖管理可选用 conda-forge快捷、预编译 Release 包或 vcpkg清单驱动、可静态化构建工具可选 MSVC 解决方案、Ninja配合 sccache 实现增量缓存、NMake 或 MSYS2 环境调试与链接层面则需关注 Debug 构建的 Boost 静态链接、静态库命名后缀以及ARROW_STATIC宏。无论选择哪条路径底层都统一由 cpp/cmake_modules 下的 CMake 工具链驱动。结合本文的官方命令与仓库源码佐证你可以根据自身场景CI 复现、本地调试、ARM64 实验快速搭建出可用的构建环境。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考