企业官网建设流程全解析

Apache Pulsar C++ 客户端源码构建全指南：多平台编译、测试与配置详解

【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址: https://gitcode.com/gh_mirrors/pulsar28/pulsar

Apache Pulsar 官方 C++ 客户端库（pulsar-client-cpp）面向 Linux、macOS 与 Windows 三大平台，为 C++11 应用提供生产/消费、Reader、批量消息、Schema、TLS 加密与多种压缩算法的完整能力。本文以仓库中的 pulsar-client-cpp/README.md 为主线，结合 CMakeLists.txt、vcpkg.json、公开头文件与示例源码，完整还原从依赖安装、三平台编译到单元测试与 API 上手的每一步，并补充构建选项与底层实现的源码级说明，帮助你一次打通 Pulsar C++ 客户端的本地编译与集成。

一、模块概览：编译之后你能得到什么

pulsar-client-cpp位于仓库根目录下的 pulsar-client-cpp 目录，其源码组织如下：

• include/pulsar：对外发布的公共 C++ 头文件，包括Client.h、Producer.h、Consumer.h、Reader.h、ClientConfiguration.h、ProducerConfiguration.h、ConsumerConfiguration.h、Message.h、MessageBuilder.h、MessageId.h、CompressionType.h、Authentication.h、Schema.h、TopicMetadata.h等；其中 c 子目录提供纯 C API。
• lib：客户端库核心实现，涵盖连接管理、异步发送、批量消息容器（BatchMessageContainer.cc）、确认跟踪（AckGroupingTracker*.cc）、压缩编解码（CompressionCodec*.cc）、鉴权（auth/）、统计与日志等模块。
• examples：可运行示例，包含SampleProducer.cc、SampleConsumer.cc、SampleConsumerListener.cc、SampleAsyncProducer.cc、SampleFileLogger.cc，以及 C API 示例（SampleProducerCApi.c、SampleConsumerCApi.c、SampleConsumerListenerCApi.c、SampleReaderCApi.c）。
• perf：性能压测工具perfProducer与perfConsumer。
• python：Python 绑定源码（由同一套 C++ 库构建出 wheel 包）。
• tests：基于 GTest 的 C++ 单元测试。

编译完成后，按平台会生成如下产物：

同时还会生成压测工具：Linux/macOS 下位于perf/perfProducer与perf/perfConsumer，Windows 下位于build/.../Release对应目录；示例程序在build/examples/Release（Windows）。符号导出方面，defines.h 通过PULSAR_PUBLIC宏在 Windows 上使用__declspec(dllexport/dllimport)、在其他平台使用__attribute__((visibility("default")))控制导出，保证客户端 API 的跨平台符号可见性。

二、构建前的依赖准备（Requirements）

官方构建要求如下（摘自 README）：

• 支持C++11的编译器，例如GCC >= 4.8；
• CMake >= 3.4（顶层 CMakeLists.txt 中cmake_minimum_required(VERSION 3.4)与此一致）；
• Boost；
• Protocol Buffer >= 3；README 同时说明 CI 验证过 2.6 版本，3.x 也可正常工作；
• libcurl；
• OpenSSL。

其中 OpenSSL 是硬性依赖（find_package(OpenSSL REQUIRED)），即使不启用 TLS，客户端也需要 OpenSSL 支撑连接与握手相关实现。

压缩算法与可选依赖

默认编译支持的压缩类型在 include/pulsar/CompressionType.h 中定义为枚举：

enum CompressionType { CompressionNone = 0, // 无压缩 CompressionLZ4 = 1, // LZ4（默认支持） CompressionZLib = 2, // 需要 zlib CompressionZSTD = 3, // 需要 zstd CompressionSNAPPY = 4 // 需要 snappy };

默认只内置CompressionNone与CompressionLZ4两种。若要在客户端启用其余压缩类型，需要预先安装对应原生库：

• CompressionZLib→ zlib；
• CompressionZSTD→ zstd；
• CompressionSNAPPY→ snappy。

从 CMakeLists.txt 可以看到，CMake 会通过find_library(LIB_ZSTD zstd)、find_library(LIB_SNAPPY snappy)探测这两个库，命中后定义HAS_ZSTD=1/HAS_SNAPPY=1并把库加入COMMON_LIBS；对应的编解码实现位于 lib/CompressionCodecZstd.cc、lib/CompressionCodecSnappy.cc 等文件。

可选功能开关

• 测试：需要安装 GTest；如果不想构建测试，在 CMake 配置时加-DBUILD_TESTS=OFF；
• Python 绑定：因为boost-python不一定好装，可以加-DBUILD_PYTHON_WRAPPER=OFF跳过 Python wrapper 的构建；
• Log4CXX 日志：只有需要调用ClientConfiguration::setLogConfFilePath时才需要安装 Log4CXX，并用-DUSE_LOG4CXX=ON启用。

三、CMake 构建选项全解析

CMakeLists.txt 定义了以下可配置项（括号内为默认值）：

另有几个实现细节值得注意：

• 编译器告警策略：非 MSVC/Intel 编译器下开启-Wall -Wformat-security -Wvla -Werror，即把告警当错误；GCC 8.1+ 额外关闭-Wno-stringop-truncation；x86_64 与 Apple 平台开启-msse4.2 -mpclmul（用于高性能校验/加密指令）。
• std::regex兼容性：GCC < 4.9 的std::regex实现有缺陷，此时自动链接 Boost.Regex 并定义PULSAR_USE_BOOST_REGEX。
• 版本号生成：CMake 会调用 src/gen-pulsar-version-macro.py，结合 templates/Version.h.in 生成 include/pulsar/Version.h，因此版本头文件不要手工编辑。
• 若本机安装了ccache，CMake 会自动将其设置为 C++ 编译器的 launcher，加速增量编译。
• 环境变量PULSAR_LIBRARY_NAME可覆盖输出库名（默认pulsar）；PULSAR_ADDITIONAL_LIBRARIES可追加额外链接库。

四、在 Docker 容器中编译（推荐路径）

仓库提供了开箱即用的容器化构建脚本，镜像已预装全部依赖，适合快速验证或 CI：

./docker-build.sh

该脚本（docker-build.sh）默认拉取apachepulsar/pulsar-build:ubuntu-16.04-pb3镜像，将仓库根目录挂载到容器/pulsar，然后在pulsar-client-cpp目录内依次执行cmake .、make check-format与make -j8。传入参数skip-clean可跳过 CMake 缓存清理，进行增量构建。

运行单元测试：

./docker-tests.sh

docker-tests.sh 支持--tests="<测试正则>"过滤，例如--tests="BasicEndToEndTest.*"；测试失败时会从容器中导出gtest-parallel-logs等日志到仓库根目录的test-logs/供排查。

五、Ubuntu（以 16.04 为例）编译步骤

1. 安装依赖

apt-get install -y g++ cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \ libprotobuf-dev libboost-all-dev libgtest-dev google-mock \ protobuf-compiler python-setuptools

2. 编译并安装 Google Test / Google Mock

cd /usr/src/gtest sudo cmake . sudo make sudo cp *.a /usr/lib

cd /usr/src/gmock sudo cmake . sudo make sudo cp *.a /usr/lib

3. 编译客户端库

cd pulsar/pulsar-client-cpp cmake . make

4. 检查产物

lib/libpulsar.so lib/libpulsar.a

perf/perfProducer perf/perfConsumer

注意：若未安装 GTest，请务必在cmake .时追加-DBUILD_TESTS=OFF，否则 CMake 会因找不到gtest/gtest.h而失败（见 CMakeLists.txt 中find_path(GTEST_INCLUDE_PATH gtest/gtest.h)的逻辑）。

六、macOS 编译步骤

1. 安装依赖

# For openSSL brew install openssl export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/ # For Protobuf brew install protobuf boost boost-python log4cxx jsoncpp # 如果使用 python3，需要安装 boost-python3

macOS 下 CMake 会额外把/usr/local/opt/openssl与/opt/homebrew/opt/openssl（Apple Silicon Homebrew 路径）加入 OpenSSL 搜索路径。

2. 编译并安装 Google Test

cd $HOME git clone https://github.com/google/googletest.git cd googletest cmake . make install

3. 编译客户端库

export PULSAR_PATH=<Path where you cloned pulsar repo> cd ${PULSAR_PATH}/pulsar-client-cpp/ cmake . make

4. 检查产物

${PULSAR_PATH}/pulsar-client-cpp/lib/libpulsar.dylib ${PULSAR_PATH}/pulsar-client-cpp/lib/libpulsar.a

${PULSAR_PATH}/pulsar-client-cpp/perf/perfProducer ${PULSAR_PATH}/pulsar-client-cpp/perf/perfConsumer

七、Windows 编译步骤

方式一：使用 vcpkg（官方推荐）

Windows 上强烈建议使用 vcpkg 管理 C++ 依赖，它易于安装且对 Visual Studio（2015/2017/2019）与 CMake 支持良好。以 64 位库为例，只需执行：

vcpkg install --feature-flags=manifests --triplet x64-windows

依赖清单由仓库根目录的 vcpkg.json 声明，包含boost-*系列（asio、date-time、program-options、random、serialization 等）、curl、openssl、protobuf、snappy、zlib、zstd、log4cxx，以及仅 Windows 需要的dlfcn-win32。安装完成后依赖会落在vcpkg_installed/子目录。

接着只需两条命令即可完成构建：

cmake \ -B ./build \ -A x64 \ -DBUILD_PYTHON_WRAPPER=OFF -DBUILD_TESTS=OFF \ -DVCPKG_TRIPLET=x64-windows \ -DCMAKE_BUILD_TYPE=Release \ -S . cmake --build ./build --config Release

所有产物都会生成到build子目录。

注意事项

1. 构建 32 位库时，把-A x64换成-A Win32，并把-DVCPKG_TRIPLET=x64-windows换成-DVCPKG_TRIPLET=x86-windows。
2. 使用 MSVC Debug 模式时，需要把CMAKE_BUILD_TYPE与--config都从Release替换为Debug（CMake 会相应从vcpkg_installed/<triplet>/debug中解析 zstd/snappy 的 Debug 库zstdd/snappyd）。

方式二：手动安装依赖

手动安装依赖时，除常规依赖外还需要额外安装 dlfcn-win32（提供 POSIXdlopen语义的 Windows 实现）。

• 如果所有依赖都已在系统 PATH 中，直接执行：

${PULSAR_PATH}/pulsar-client-cpp/cmake .

• 如果依赖不在 PATH 中，需要显式传入PROTOC_PATH与CMAKE_PREFIX_PATH：

${PULSAR_PATH}/pulsar-client-cpp/cmake -DPROTOC_PATH=C:/protobuf/bin/protoc -DCMAKE_PREFIX_PATH="C:/boost;C:/openssl;C:/zlib;C:/curl;C:/protobuf;C:/googletest;C:/dlfcn-win32" .

该命令会生成pulsar-cpp.sln，用 Visual Studio 打开后构建所需配置即可。

3. 检查产物

${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release/pulsar.lib ${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release/pulsar.dll

4. 运行示例

先将以下路径加入 Windows 环境变量PATH：

${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release ${PULSAR_PATH}/pulsar-client-cpp/vcpkg_installed

示例程序位于：

${PULSAR_PATH}/pulsar-client-cpp/build/examples/Release

八、测试与验证

构建完成后，可以按 README 的流程启动一个 standalone broker 并运行全部单元测试：

# Source code ${PULSAR_PATH}/pulsar-client-cpp/tests/ # Execution # 1. Start standalone broker ${PULSAR_PATH}/pulsar-test-service-start.sh # 2. Run the tests ${PULSAR_PATH}/pulsar-client-cpp/tests/main # 3. Stop standalone broker ${PULSAR_PATH}/pulsar-test-service-stop.sh

仓库根目录下的两个脚本 pulsar-test-service-start.sh 与 pulsar-test-service-stop.sh 负责拉起/回收测试用的 Pulsar 服务（含 TLS 与非 TLS 两套 standalone 实例，见 docker-tests.sh）。

在容器环境或 CI 中，测试入口是 run-unit-tests.sh：它先启动测试服务，然后借助gtest-parallel以 2×CPU 核数（上限 10）并行运行tests/main，失败用例自动重试（RETRY_FAILED环境变量，默认 1）；C++ 测试通过后还会构建 Python wheel 并运行 python/pulsar_test.py 等 Python 用例。

测试套件覆盖了客户端核心路径，例如 tests/BasicEndToEndTest.cc（端到端生产消费）、tests/ProducerTest.cc、tests/ConsumerTest.cc、tests/ReaderTest.cc、tests/BackoffTest.cc（重连退避）、tests/MessageChunkingTest.cc（消息分块）等。

九、API 快速上手与配置类源码视角

最小生产示例

仓库中的 examples/SampleProducer.cc 给出了最简同步发送示例：

#include <pulsar/Client.h> using namespace pulsar; int main() { Client client("pulsar://localhost:6650"); Producer producer; Result result = client.createProducer("persistent://public/default/my-topic", producer); if (result != ResultOk) { LOG_ERROR("Error creating producer: " << result); return -1; } // Send synchronously Message msg = MessageBuilder().setContent("content").build(); Result res = producer.send(msg); LOG_INFO("Message sent: " << res); client.close(); }

pulsar://localhost:6650对应 standalone broker 的默认服务地址；生产者通过MessageBuilder构造消息，producer.send(msg)同步发送。异步发送、基于 Listener 的消费、Reader 与 C API 用法可分别参考 examples 目录下的SampleAsyncProducer.cc、SampleConsumerListener.cc、SampleReaderCApi.c等。

ClientConfiguration 关键配置项

include/pulsar/ClientConfiguration.h 集中了客户端级行为配置，常用方法如下：

其中 TLS 相关的setUseTls/setTlsTrustCertsFilePath/setTlsAllowInsecureConnection/setValidateHostName组合使用即可完成客户端到 broker 的加密与证书校验。

ProducerConfiguration 关键配置项

include/pulsar/ProducerConfiguration.h 定义了生产者的路由、哈希与批处理策略：

• 分区路由模式（PartitionsRoutingMode）：UseSinglePartition（固定单分区）、RoundRobinDistribution（轮询分发）、CustomPartition（自定义路由）；
• 哈希算法（HashingScheme）：Murmur3_32Hash、BoostHash、JavaStringHash（与 Java 客户端保持一致的哈希结果，保证跨语言 key 路由一致）；
• 批处理类型（BatchingType）：DefaultBatching（顺序把多个单条消息合成一个批次）与KeyBasedBatching（按 key 聚合后分别成批，保证同一 key 的消息落在同一批次/分区）。

日志配置

若以-DUSE_LOG4CXX=ON编译，可通过ClientConfiguration::setLogConfFilePath加载日志配置。仓库自带的 log4cxx.conf 展示了最小配置，例如：

log4j.rootLogger=INFO, A1 log4j.appender.A1=org.apache.log4j.ConsoleAppender log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%d{yy-MM-dd HH:mm:ss.SSS} %X{pname}:%X{pid} %-5p %l- %m%n log4j.appender.A1.serverFileAppender.fileName=/tmp/pulsar_client_cpp.log

根日志级别为 INFO，输出到控制台与滚动文件/tmp/pulsar_client_cpp.log，格式包含时间戳、进程名（pname）、PID 与日志位置。

十、Contributor 开发规范

如果你计划为 C++ 客户端贡献代码，README 给出了以下约定：

• 推荐安装 LLVM 工具链获取clang-format 5.0与clang-tidy；仓库的格式检查使用 clang-format 5.0，与最新版本行为略有差异。CMake 提供了make format（自动格式化）与make check-format（仅检查，供 CI 使用）两个目标，覆盖lib、perf、examples、tests、include、python/src、wireshark等目录。
• 修改需保持与GCC 4.8和Boost 1.53的向后兼容（这也是上文提到 GCC < 4.9 自动回退 Boost.Regex 的原因）。
• 安装 clang-format@5 的方式因平台而异：macOS 上通过brew tap demogorgon314/clang-format后brew install clang-format@5；Ubuntu 18.04 上可sudo apt install clang-format-5.0，或从 LLVM 官方 releases 下载预编译二进制。

总结

Pulsar C++ 客户端的构建链路围绕 CMake 展开：依赖层面覆盖编译器、CMake、Boost、Protobuf、libcurl、OpenSSL 及可选的 zlib/zstd/snappy/GTest/Log4CXX；平台层面 Docker、Ubuntu、macOS、Windows（vcpkg 或手动）四种路径均可在官方文档指导下复现。理解 CMakeLists.txt 中的构建开关（BUILD_TESTS、BUILD_PYTHON_WRAPPER、BUILD_PERF_TOOLS、USE_LOG4CXX、LINK_STATIC等）与 include/pulsar 下各配置类的默认值，是完成生产环境集成与二次开发的关键。更多用法可直接阅读 examples 与 tests 中的真实代码。

【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址: https://gitcode.com/gh_mirrors/pulsar28/pulsar