在 Windows 上进行开发

与 Linux 和 macOS 类似，我们已经努力使项目的一个相当大的子集能够通过 CMake 实现“开箱即用”的构建。

系统设置

微软提供了免费的 Visual Studio Community 版本。在 shell 中进行开发时，每次打开 shell 都必须初始化开发环境。

对于 Visual Studio 2017，请执行以下批处理脚本

"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\Tools\VsDevCmd.bat" -arch=amd64

对于 Visual Studio 2019，脚本如下

"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\VsDevCmd.bat" -arch=amd64

可以配置一个控制台模拟器，比如 cmder，以便在启动新的开发控制台时自动运行此脚本。

使用 conda-forge 管理构建依赖

Miniconda 是一个包含 conda 包管理器的最小 Python 发行版。Apache Arrow 社区的一些成员参与了 conda-forge 的维护，这是一个社区维护的、用于 conda 的跨平台软件包仓库。

要在 Windows 上使用 conda-forge 来管理 C++ 构建依赖，首先从 Miniconda 首页 下载并安装一个 64 位发行版。

要配置 conda 默认使用 conda-forge 频道，启动一个命令提示符 (cmd.exe)，运行上面显示的初始化命令（vcvarsall.bat 或 VsDevCmd.bat），然后运行以下命令

conda config --add channels conda-forge

现在，你可以在 Arrow 代码库的根目录中调用以下命令来引导一个构建环境

conda create -y -n arrow-dev --file=ci\conda_env_cpp.txt

然后用以下命令“激活”这个 conda 环境

activate arrow-dev

如果环境已被激活，Arrow 构建系统将自动检测到 %CONDA_PREFIX% 环境变量，并用它来解析构建依赖项。这等同于设置

-DARROW_DEPENDENCY_SOURCE=SYSTEM ^
-DARROW_PACKAGE_PREFIX=%CONDA_PREFIX%\Library

要在这个已激活的 conda 环境中使用 Visual Studio IDE，请在同一个命令提示符中运行 devenv 命令来启动它。

请注意，作为 conda 包安装的依赖项是以 release 模式构建的，不能与 debug 构建链接。如果你打算使用 -DCMAKE_BUILD_TYPE=debug，那么你必须从源代码构建这些包。-DCMAKE_BUILD_TYPE=relwithdebinfo 也是一个可选项，它能生成一个既可以与 release 库链接又可以进行调试的构建。

注意

如果在使用 conda 包管理依赖项时遇到任何问题，一个非常常见的问题是混用了来自 defaults 频道和 conda-forge 频道的包。你可以使用 conda list 来检查环境中已安装的包（及其来源）

使用 vcpkg 管理构建依赖

vcpkg 是一个来自微软的开源包管理器。它托管了社区贡献的 C 和 C++ 包及其依赖项的移植。Arrow 包含一个清单文件 cpp/vcpkg.json，该文件指定了构建 C++ 库所需的 vcpkg 包。

要在 Windows 上使用 vcpkg 管理 C++ 构建依赖，首先请安装并集成 vcpkg。然后在 cmd.exe 中将工作目录更改为 Arrow 的根目录，并运行以下命令

vcpkg install ^
  --triplet x64-windows ^
  --x-manifest-root cpp  ^
  --feature-flags=versions ^
  --clean-after-build

在 Windows 上，vcpkg 默认构建动态链接库。使用三元组 x64-windows-static 来构建静态库。vcpkg 会下载源码包并在本地编译它们，因此使用 vcpkg 安装依赖比使用 conda 更耗时。

然后在你的 cmake 命令中，要使用 vcpkg 安装的依赖项，请设置

-DARROW_DEPENDENCY_SOURCE=VCPKG

你可以选择性地设置其他变量来覆盖 vcpkg 的默认 CMake 配置，包括

• -DCMAKE_TOOLCHAIN_FILE：默认情况下，CMake 脚本会自动查找 vcpkg CMake 工具链文件 vcpkg.cmake 的位置；使用此选项可指定其位置

• -DVCPKG_TARGET_TRIPLET：默认情况下，CMake 脚本会尝试推断 vcpkg 的三元组（triplet）；使用此选项可指定三元组

• -DARROW_DEPENDENCY_USE_SHARED：默认为 ON；对于静态库，请设置为 OFF

• -DVCPKG_MANIFEST_MODE：默认为 ON；设置为 OFF 可忽略 vcpkg.json 清单文件，并只查找 vcpkg 安装目录下已安装的包

使用 Visual Studio (MSVC) 解决方案文件进行构建

在 cmd.exe 中将工作目录更改为 Arrow 的根目录，并通过生成 MSVC 解决方案来进行源码外构建（out-of-source build）

cd cpp
mkdir build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64 ^
      -DARROW_BUILD_TESTS=ON
cmake --build . --config Release

对于较新版本的 Visual Studio，请指定生成器 Visual Studio 17 2022，或查看 cmake --help 以获取可用的生成器。

使用 Ninja 和 sccache 进行构建

Ninja 构建系统提供了更好的构建并行化能力，而可选的 sccache 编译器缓存可以跟踪过去的编译，以避免重复运行它们（类似于 Unix 特有的 ccache）。

较新版本的 Visual Studio 包含 Ninja。要查看你的 Visual Studio 是否包含 Ninja，请运行上面显示的初始化命令（vcvarsall.bat 或 VsDevCmd.bat），然后运行 ninja --version。

如果你的 Visual Studio 版本中不包含 Ninja，并且你正在使用 conda，请激活你的 conda 环境并安装 Ninja

activate arrow-dev
conda install -c conda-forge ninja

如果你不使用 conda，请从其他来源安装 Ninja。

安装完成后，在 cmd.exe 中将工作目录更改为 Arrow 的根目录，并通过生成 Ninja 文件来进行源码外构建

cd cpp
mkdir build
cd build
cmake -G "Ninja" ^
      -DARROW_BUILD_TESTS=ON ^
      -DGTest_SOURCE=BUNDLED ..
cmake --build . --config Release

要在本地存储模式下使用 sccache，你需要在调用 cmake 之前设置 SCCACHE_DIR 环境变量

...
set SCCACHE_DIR=%LOCALAPPDATA%\Mozilla\sccache
cmake -G "Ninja" ^
...

使用 NMake 进行构建

在 cmd.exe 中将工作目录更改为 Arrow 的根目录，并使用 nmake 进行源码外构建

cd cpp
mkdir build
cd build
cmake -G "NMake Makefiles" ..
nmake

在 MSYS2 上构建

你可以在 MSYS2 终端、cmd.exe 或 PowerShell 终端上进行构建。

在 MSYS2 终端上

cd cpp
mkdir build
cd build
cmake -G "MSYS Makefiles" ..
make

在 cmd.exe 或 PowerShell 终端上，你可以使用以下批处理文件

setlocal

REM For 64bit
set MINGW_PACKAGE_PREFIX=mingw-w64-x86_64
set MINGW_PREFIX=c:\msys64\mingw64
set MSYSTEM=MINGW64

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/arm64 平台上构建库。

cd cpp
mkdir build
cd build

set CC=clang-cl
set CXX=clang-cl

cmake -G "Ninja" ..

cmake --build . --config Release

用于 Windows on ARM64 的 LLVM 工具链可以从 LLVM 发布页面 LLVM 发布页面 下载。

由于与 xsimd 和 boost 库等依赖项的兼容性问题，Visual Studio (MSVC) 尚不能用于编译 win/arm64 构建。

注意：这只是 WoA64 的一个实验性构建，因为缺乏基础设施，所有功能尚未通过 CI 进行广泛测试。

调试构建

要构建 Arrow 的调试版本，你应该预先安装一个调试版本的 Boost。建议使用以下变量配置 cmake 以进行调试构建

• -DARROW_BOOST_USE_SHARED=OFF：启用与 boost 调试库的静态链接，并简化第三方库的运行时加载

• -DBOOST_ROOT：设置 boost 库的根目录。（可选）

• -DBOOST_LIBRARYDIR：设置 boost 库文件所在的目录。（可选）

在调试模式下构建 Arrow 的命令行将类似于这样

cd cpp
mkdir build
cd build
cmake .. -G "Visual Studio 15 2017" -A x64 ^
      -DARROW_BOOST_USE_SHARED=OFF ^
      -DCMAKE_BUILD_TYPE=Debug ^
      -DBOOST_ROOT=C:/local/boost_1_63_0  ^
      -DBOOST_LIBRARYDIR=C:/local/boost_1_63_0/lib64-msvc-14.0
cmake --build . --config Debug

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%

要获取最新的构建说明，你可以参考 ci/appveyor-built.bat，这是由 Appveyor 自动化构建使用的脚本。

在 Windows 上静态链接到 Arrow

在 Windows 静态库构建中（通过 CMake 选项 ARROW_BUILD_STATIC 启用），Arrow 头文件使用预处理器宏 ARROW_STATIC 来抑制符号的 dllimport/dllexport 标记。在 Windows 上静态链接 Arrow 的项目也需要此定义。Unix 构建不使用该宏。

此外，如果使用 -DARROW_FLIGHT=ON，则需要定义 ARROW_FLIGHT_STATIC，同样地，对于 -DARROW_FLIGHT_SQL=ON 也是如此。

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)

下载时区数据库

要在 Windows 上运行一些计算单元测试，需要先下载 IANA 时区数据库和 Windows 时区映射。请参阅运行时依赖中的下载说明。要在运行单元测试时为时区数据库设置非默认路径，请设置 ARROW_TIMEZONE_DATABASE 环境变量。

复现 Appveyor 构建

对于更熟悉 Linux 开发但需要复现失败的 Appveyor 构建的人员，这里有一些复现 Static_Crt_Build 的粗略说明（make unittest 可能仍然会失败，但许多单元测试可以通过其各自的 make 目标来构建）。

1. 微软提供了带有 Microsoft Visual Studio 的 Windows 试用虚拟机。下载并安装一个版本。

2. 运行虚拟机并安装 Git、CMake 和 Miniconda 或 Anaconda（本说明假设使用 Anaconda）。同时安装“Visual Studio 生成工具”。确保在安装向导中选择 C++ 工具链，并在安装后重新启动。

3. 下载预编译的 Boost 调试二进制文件并安装它。

   从 Anaconda/Miniconda 命令提示符（*不是* PowerShell 提示符）运行此命令，并确保首先运行 “vcvarsall.bat x64”。vcvarsall.bat 的位置可能会有所不同，它可能位于一个与通常指示的路径不同的路径下，例如，对于 2019 构建工具，它在 “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 in appveyor
.\b2 link=static --with-filesystem --with-regex --with-system install
@rem this should put libraries and headers in c:\Boost

4. 激活 anaconda/miniconda

@rem this might differ for miniconda
C:\Users\User\Anaconda3\Scripts\activate

5. 克隆并切换目录到 arrow 源代码（你可能需要安装 git）。

6. 设置环境变量

@rem Change the build type based on which appveyor job you want.
SET JOB=Static_Crt_Build
SET GENERATOR=Ninja
SET APPVEYOR_BUILD_WORKER_IMAGE=Visual Studio 2017
SET USE_CLCACHE=false
SET ARROW_BUILD_GANDIVA=OFF
SET ARROW_LLVM_VERSION=8.0.*
SET PYTHON=3.9
SET ARCH=64
SET PATH=C:\Users\User\Anaconda3;C:\Users\User\Anaconda3\Scripts;C:\Users\User\Anaconda3\Library\bin;%PATH%
SET BOOST_LIBRARYDIR=C:\Boost\lib
SET BOOST_ROOT=C:\Boost

7. 运行 appveyor 脚本

conda install -c conda-forge --file .\ci\conda_env_cpp.txt
.\ci\appveyor-cpp-setup.bat
@rem this might fail but at this point most unit tests should be buildable by there individual targets
@rem see next line for example.
.\ci\appveyor-cpp-build.bat
@rem you can also just invoke cmake directly with the desired options
cmake --build . --config Release --target arrow-compute-hash-test