如何在 C++ 项目中用 CMake 集成 Arrow C++ 库并链接 Arrow::arrow_shared

如何在 C++ 项目中用 CMake 集成 Arrow C++ 库并链接 Arrow::arrow_shared

【免费下载链接】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

如果你的 C++ 工程需要调用 Arrow C++（列式内存格式与数据分析库）的 API，官方推荐的做法是用 CMake 的find_package定位系统上已安装的 Arrow C++ 库，然后链接Arrow::arrow_shared目标。前提是你的系统上已经装好了 Arrow C++ 库——通过包管理器安装，或按仓库文档自己编译安装（见 docs/source/cpp/build_system.rst）。本文给出最短可用的 CMake 配置，并用仓库自带的cpp/examples/minimal_build/端到端例子验证你的集成是否成功。

前置条件

• 系统上已存在 Arrow C++ 安装（包管理器安装或自行编译安装），否则find_package(Arrow REQUIRED)会直接配置失败。
• 使用 CMake 作为构建系统。文档示例中的CMakeLists.txt要求cmake_minimum_required(VERSION 3.25)；如果你不用 CMake，文档给出的替代路径是 pkg-config，见文末说明。

最小 CMakeLists.txt：find_package + Arrow::arrow_shared

下面是最简配置，把my_example.cc编译成链接了 Arrow C++ 共享库的可执行文件（来自 docs/source/cpp/build_system.rst）：

cmake_minimum_required(VERSION 3.25) project(MyExample) find_package(Arrow REQUIRED) add_executable(my_example my_example.cc) target_link_libraries(my_example PRIVATE Arrow::arrow_shared)

find_package(Arrow REQUIRED)让 CMake 在系统中查找 Arrow C++ 安装。配置阶段能顺利通过这一行，就说明 Arrow 被找到了。

find_package(Arrow REQUIRED)返回后会设置以下 CMake 变量（注意${Arrow_FOUND}为 true 表示找到了 Arrow）：

• ${Arrow_FOUND}：Arrow C++ 是否被找到
• ${ARROW_VERSION}：Arrow 版本字符串
• ${ARROW_FULL_SO_VERSION}：Arrow DLL 版本字符串

同时会创建可链接的目标（这些是目标名，不是变量）：

• Arrow::arrow_shared：链接 Arrow 共享库
• Arrow::arrow_static：链接 Arrow 静态库

为了向后兼容，arrow_shared和arrow_static目标也可用，但文档推荐使用带命名空间的形式。多数情况下文档建议优先使用共享库。

两个容易踩的坑：find_package的实现目前不支持COMPONENTS；CMake 目标名和变量名大小写敏感，必须按上面拼写完全一致。

Arrow 安装在非系统路径时：配置 CMAKE_PREFIX_PATH

如果 Arrow 装在自定义路径而不是常见系统路径，需要把安装路径加进CMAKE_PREFIX_PATH。它既可以定义为 CMake 变量，也可以定义为环境变量。

作为环境变量时（ARROW_ROOT指向你的 Arrow 安装路径，命令保留了原有的CMAKE_PREFIX_PATH值）：

export CMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}

作为 CMake 变量时，在配置项目时传入：

cmake ... -DCMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}

其中...处替换为你原有的项目源目录和其他 CMake 参数。

端到端验证：编译并运行仓库自带的 minimal_build 例子

仓库内 cpp/examples/minimal_build/ 提供了一个第三方 C++ 项目集成 Arrow 的完整示例，可用于验证上面这套流程。示例可执行文件运行时读取test.csv，把解析后的内容打印出来，并以 Arrow IPC 格式写入test.arrow（见 cpp/examples/minimal_build/README.md）。

方式一：Docker Compose 一键运行

在cpp/examples/minimal_build/目录下打开终端执行：

docker compose run --rm minimal

该命令会构建并运行容器（副作用：Docker 会拉取/构建镜像并挂载两个卷：/arrow指向 Arrow 源码树，/io指向示例目录），容器内完成 Arrow 编译安装和示例项目的 CMake 构建。

容器内的流程对应两个脚本：

build_arrow.sh 在$ARROW_BUILD_DIR中编译安装 Arrow：

cmake /arrow/cpp \ -DARROW_CSV=ON \ -DARROW_MIMALLOC=OFF \ $ARROW_CMAKE_OPTIONS make -j$NPROC make install

其中ARROW_CSV=ON是因为示例第三方工程用到了 CSV reader；/arrow/cpp是容器内挂载的 Arrow 源码路径。

build_example.sh 在$EXAMPLE_BUILD_DIR中配置并构建示例工程：

cmake /io make

/io即示例目录挂载点。

示例工程的 CMakeLists.txt

cpp/examples/minimal_build/CMakeLists.txt 在最小配置之外还展示了共享/静态链接的切换方式和版本信息输出：

find_package(Arrow REQUIRED) include(CMakeDependentOption) cmake_dependent_option(ARROW_LINK_SHARED "Link to the Arrow shared library if possible" ON ARROW_BUILD_SHARED OFF) if(NOT DEFINED CMAKE_CXX_STANDARD) set(CMAKE_CXX_STANDARD 20) endif() # We require a C++20 compliant compiler set(CMAKE_CXX_STANDARD_REQUIRED ON) if(NOT CMAKE_BUILD_TYPE) set(CMAKE_BUILD_TYPE Release) endif() message(STATUS "Arrow version: ${ARROW_VERSION}") message(STATUS "Arrow SO version: ${ARROW_FULL_SO_VERSION}") add_executable(arrow-example example.cc) if(ARROW_LINK_SHARED) target_link_libraries(arrow-example PRIVATE Arrow::arrow_shared) else() target_link_libraries(arrow-example PRIVATE Arrow::arrow_static) endif()

注意：C++20 是该示例工程自己声明的要求（见 example.cc 的配套配置），ARROW_LINK_SHARED选项控制链接Arrow::arrow_shared还是Arrow::arrow_static。

成功判定

按文档可核对的结果是：

1. 配置阶段打印出Arrow version: ...与Arrow SO version: ...状态行，说明find_package成功解析出版本信息；
2. 构建出示例可执行文件；运行后它读取当前目录的test.csv，打印解析后的表内容，并生成test.arrow（Arrow IPC 格式）文件——README 描述的就是这一预期行为，具体打印内容取决于test.csv数据。

可选分支：静态链接

如果确实要静态链接（例如做依赖自包含的可执行文件），把target_link_libraries换成Arrow::arrow_static即可。minimal_build 示例提供了三种静态构建入口（来自 cpp/examples/minimal_build/README.md）：

• Linux（复用上面的 Docker 镜像）：docker compose run --rm static

• macOS：设置环境变量后运行./run_static.sh，例如：

  export ARROW_DIR=path/to/arrow-clone export EXAMPLE_DIR=$ARROW_DIR/cpp/examples/minimal_build export ARROW_BUILD_DIR=$(pwd)/arrow-build export EXAMPLE_BUILD_DIR=$(pwd)/example ./run_static.sh

  其中ARROW_DIR需替换为你本地 Arrow 源码 checkout 的路径，脚本会据此编译 Arrow 并构建示例。

• Windows：在启用 Visual Studio 命令行工具、且 CMake 和 ninja 在 PATH 中的命令行中执行call run_static.bat。

• 若要用系统提供的 Arrow 依赖静态库，可设ARROW_DEPENDENCY_SOURCE=SYSTEM运行run_static.sh，或docker compose run --rm static-system-dependency。

需要用到其他模块时

除Arrow外，CMake 包还包括：ArrowCUDA、ArrowAcero、ArrowCompute、ArrowDataset、ArrowFlight、ArrowFlightSql、ArrowFlightTesting、ArrowSubstrait、ArrowTesting、Gandiva、Parquet。命名规则一致：find_package(PackageName REQUIRED)，共享目标为PackageName::package_name_shared，静态目标为PackageName::package_name_static。例如 ArrowCompute 的用法是find_package(ArrowCompute REQUIRED)加链接ArrowCompute::arrow_compute_shared或ArrowCompute::arrow_compute_static。

链接注意事项

如果你的工程还要直接使用 Arrow 组件的依赖库（比如 Protobuf、gRPC），必须保证你的工程以与 Arrow 相同的方式（同为静态或同为动态）链接相同版本的这些依赖，否则可能违反 ODR（One Definition Rule），导致程序崩溃或静默数据损坏。文档特别指出 Arrow Flight 及其依赖 Protobuf、gRPC 最容易出问题：

• 静态链接 Arrow Flight 时，Protobuf 和 gRPC 也必须静态链接；动态则同为动态；
• 某些平台（如文档撰写时的 Ubuntu 20.04）自带的 Protobuf/gRPC 版本可能过旧，Arrow Flight 会自带这些依赖——这时不要混用系统版本，否则应用里会链入两个版本的 Protobuf 或 gRPC。

文档给出的规避建议：依赖一个从源码构建、可以自己控制每个依赖来源和链接方式的 Arrow 版本，或使用 Conda、vcpkg 等包管理器提供的 Arrow，由包管理器保证版本一致性。

不用 CMake 时：pkg-config 替代路径

如果你的构建系统不是 CMake，可用 pkg-config 获取编译链接参数：

pkg-config --cflags --libs arrow

静态链接 Arrow C++ 时加--static：

pkg-config --cflags --libs --static arrow

对应的最小 Makefile（来自 docs/source/cpp/build_system.rst）：

my_example: my_example.cc $(CXX) -o $@ $(CXXFLAGS) $< $$(pkg-config --cflags --libs arrow)

各模块对应的 pkg-config 包名包括arrow、arrow-csv、arrow-dataset、arrow-flight、parquet、gandiva等。文档同时提醒：CMake 用户仍应优先使用find_package(Arrow)而不是 pkg-config 模块。

【免费下载链接】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