Apache Pulsar C 客户端源码构建全指南多平台编译、测试与配置详解【免费下载链接】pulsarApache Pulsar - distributed pub-sub messaging system项目地址: https://gitcode.com/gh_mirrors/pulsar28/pulsarApache Pulsar 官方 C 客户端库pulsar-client-cpp面向 Linux、macOS 与 Windows 三大平台为 C11 应用提供生产/消费、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。pythonPython 绑定源码由同一套 C 库构建出 wheel 包。tests基于 GTest 的 C 单元测试。编译完成后按平台会生成如下产物平台库文件说明Linuxlib/libpulsar.so、lib/libpulsar.a动态库与静态库macOSlib/libpulsar.dylib、lib/libpulsar.a动态库与静态库Windowsbuild/lib/Release/pulsar.lib、build/lib/Release/pulsar.dll导入库与 DLL同时还会生成压测工具Linux/macOS 下位于perf/perfProducer与perf/perfConsumerWindows 下位于build/.../Release对应目录示例程序在build/examples/ReleaseWindows。符号导出方面defines.h 通过PULSAR_PUBLIC宏在 Windows 上使用__declspec(dllexport/dllimport)、在其他平台使用__attribute__((visibility(default)))控制导出保证客户端 API 的跨平台符号可见性。二、构建前的依赖准备Requirements官方构建要求如下摘自 README支持C11的编译器例如GCC 4.8CMake 3.4顶层 CMakeLists.txt 中cmake_minimum_required(VERSION 3.4)与此一致BoostProtocol Buffer 3README 同时说明 CI 验证过 2.6 版本3.x 也可正常工作libcurlOpenSSL。其中 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→ zlibCompressionZSTD→ zstdCompressionSNAPPY→ snappy。从 CMakeLists.txt 可以看到CMake 会通过find_library(LIB_ZSTD zstd)、find_library(LIB_SNAPPY snappy)探测这两个库命中后定义HAS_ZSTD1/HAS_SNAPPY1并把库加入COMMON_LIBS对应的编解码实现位于 lib/CompressionCodecZstd.cc、lib/CompressionCodecSnappy.cc 等文件。可选功能开关测试需要安装 GTest如果不想构建测试在 CMake 配置时加-DBUILD_TESTSOFFPython 绑定因为boost-python不一定好装可以加-DBUILD_PYTHON_WRAPPEROFF跳过 Python wrapper 的构建Log4CXX 日志只有需要调用ClientConfiguration::setLogConfFilePath时才需要安装 Log4CXX并用-DUSE_LOG4CXXON启用。三、CMake 构建选项全解析CMakeLists.txt 定义了以下可配置项括号内为默认值选项默认值作用BUILD_DYNAMIC_LIBON构建动态库并编译 examples 子目录BUILD_STATIC_LIBON构建静态库BUILD_TESTSON构建 GTest 单元测试BUILD_PYTHON_WRAPPERON构建 Python 绑定BUILD_WIRESHARKOFF构建 Wireshark 协议解析插件见 wiresharkBUILD_PERF_TOOLSOFF构建perfProducer/perfConsumer压测工具LINK_STATICOFF全静态链接查找libz.a、libprotobuf.a、libcurl.a等USE_LOG4CXXOFF启用 Log4CXX 日志后端CMAKE_BUILD_TYPERelWithDebInfo未显式指定时的默认构建类型VCPKG_TRIPLET空指定 vcpkg triplet自动设置CMAKE_PREFIX_PATH与PROTOC_PATH另有几个实现细节值得注意编译器告警策略非 MSVC/Intel 编译器下开启-Wall -Wformat-security -Wvla -Werror即把告警当错误GCC 8.1 额外关闭-Wno-stringop-truncationx86_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因此版本头文件不要手工编辑。若本机安装了ccacheCMake 会自动将其设置为 C 编译器的 launcher加速增量编译。环境变量PULSAR_LIBRARY_NAME可覆盖输出库名默认pulsarPULSAR_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.shdocker-tests.sh 支持--tests测试正则过滤例如--testsBasicEndToEndTest.*测试失败时会从容器中导出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-setuptools2. 编译并安装 Google Test / Google Mockcd /usr/src/gtest sudo cmake . sudo make sudo cp *.a /usr/libcd /usr/src/gmock sudo cmake . sudo make sudo cp *.a /usr/lib3. 编译客户端库cd pulsar/pulsar-client-cpp cmake . make4. 检查产物lib/libpulsar.so lib/libpulsar.aperf/perfProducer perf/perfConsumer注意若未安装 GTest请务必在cmake .时追加-DBUILD_TESTSOFF否则 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-python3macOS 下 CMake 会额外把/usr/local/opt/openssl与/opt/homebrew/opt/opensslApple Silicon Homebrew 路径加入 OpenSSL 搜索路径。2. 编译并安装 Google Testcd $HOME git clone https://github.com/google/googletest.git cd googletest cmake . make install3. 编译客户端库export PULSAR_PATHPath where you cloned pulsar repo cd ${PULSAR_PATH}/pulsar-client-cpp/ cmake . make4. 检查产物${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 Studio2015/2017/2019与 CMake 支持良好。以 64 位库为例只需执行vcpkg install --feature-flagsmanifests --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_WRAPPEROFF -DBUILD_TESTSOFF \ -DVCPKG_TRIPLETx64-windows \ -DCMAKE_BUILD_TYPERelease \ -S . cmake --build ./build --config Release所有产物都会生成到build子目录。注意事项构建 32 位库时把-A x64换成-A Win32并把-DVCPKG_TRIPLETx64-windows换成-DVCPKG_TRIPLETx86-windows。使用 MSVC Debug 模式时需要把CMAKE_BUILD_TYPE与--config都从Release替换为DebugCMake 会相应从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_PATHC:/protobuf/bin/protoc -DCMAKE_PREFIX_PATHC:/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.dll4. 运行示例先将以下路径加入 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环境变量默认 1C 测试通过后还会构建 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 集中了客户端级行为配置常用方法如下方法默认值作用setMemoryLimit(bytes)0不限制限制该客户端实例分配的内存上限防止内存失控setAuth(AuthenticationPtr)无设置与 broker 交互的鉴权方式setOperationTimeoutSeconds(int)30ssubscribe / createProducer / close / unsubscribe 等操作超时setIOThreads(int)1客户端 IO 线程数setMessageListenerThreads(int)1消息 Listener 投递线程数同一 Listener 始终绑定同一线程setConcurrentLookupRequest(int)50000单条 broker 连接上允许的并发 lookup 请求数setLogConfFilePath(path)无指定日志配置文件路径需-DUSE_LOG4CXXONsetLogger(LoggerFactory*)stdout注入自定义日志后端setUseTls(bool)false启用 TLS 加密连接setTlsTrustCertsFilePath(path)无设置信任的 CA 证书文件路径setTlsAllowInsecureConnection(bool)false是否接受不受信任的 broker 证书setValidateHostName(bool)false是否按 RFC 2818 校验服务器主机名CN/SANsetListenerName(name)无指定 broker 返回的advertisedListener名称setStatsIntervalInSeconds(unsigned)600统计信息打印周期0 表示关闭统计setPartititionsUpdateInterval(unsigned)60s分区 topic 的分区数更新轮询间隔setConnectionTimeout(ms)10000msbroker 连接建立的超时时间其中 TLS 相关的setUseTls/setTlsTrustCertsFilePath/setTlsAllowInsecureConnection/setValidateHostName组合使用即可完成客户端到 broker 的加密与证书校验。ProducerConfiguration 关键配置项include/pulsar/ProducerConfiguration.h 定义了生产者的路由、哈希与批处理策略分区路由模式PartitionsRoutingModeUseSinglePartition固定单分区、RoundRobinDistribution轮询分发、CustomPartition自定义路由哈希算法HashingSchemeMurmur3_32Hash、BoostHash、JavaStringHash与 Java 客户端保持一致的哈希结果保证跨语言 key 路由一致批处理类型BatchingTypeDefaultBatching顺序把多个单条消息合成一个批次与KeyBasedBatching按 key 聚合后分别成批保证同一 key 的消息落在同一批次/分区。日志配置若以-DUSE_LOG4CXXON编译可通过ClientConfiguration::setLogConfFilePath加载日志配置。仓库自带的 log4cxx.conf 展示了最小配置例如log4j.rootLoggerINFO, A1 log4j.appender.A1org.apache.log4j.ConsoleAppender log4j.appender.A1.layoutorg.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-format5 的方式因平台而异macOS 上通过brew tap demogorgon314/clang-format后brew install clang-format5Ubuntu 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、Windowsvcpkg 或手动四种路径均可在官方文档指导下复现。理解 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考