1. 项目概述为什么需要自己编译ZooKeeper C客户端最近在搞一个分布式系统的项目底层协调服务选型时我们团队最终还是决定用ZooKeeper。理由很直接它成熟、稳定社区活跃是很多大数据框架的“标配”。但项目里有个模块是用C写的需要直接和ZooKeeper服务端交互这就绕不开它的C客户端库了。ZooKeeper官方提供了Java和C两种客户端绑定。对于C官方并没有直接提供预编译好的二进制库而是提供了一个基于C客户端封装的C包装器。这意味着如果你想在C项目里用ZooKeeper十有八九得自己动手从源码开始编译这个客户端库。这个过程说简单也简单照着文档敲命令就行说麻烦也麻烦环境依赖、编译选项、版本兼容任何一个环节出点岔子都可能让你折腾半天。特别是对于刚接触的新手或者项目环境比较“干净”的机器很容易踩坑。所以今天我就把从安装ZooKeeper 3.8.4服务端到成功编译出C客户端API库再到写一个简单的测试程序验证的完整过程结合我踩过的几个坑详细记录下来。目标就一个让你拿到这份“攻略”能在自己的Linux环境以CentOS 7/8或Ubuntu 20.04/22.04为例里一次搞定把可用的libzookeeper_mt.so多线程库或libzookeeper_st.so单线程库稳稳地编译出来。2. 环境准备与依赖梳理在开始编译之前一个干净、完备的编译环境是成功的一半。ZooKeeper的C客户端C客户端基于此编译需要一些基础开发工具和库我们得先把它们备齐。2.1 系统与基础开发工具首先确保你的系统已经安装了必要的编译工具链。打开终端执行以下命令对于基于RPM的系统如CentOS、RHEL、Fedorasudo yum groupinstall -y Development Tools sudo yum install -y wget tar gzip openssl-devel cppunit-devel对于基于APT的系统如Ubuntu、Debiansudo apt-get update sudo apt-get install -y build-essential wget tar gzip libssl-dev libcppunit-dev这里解释一下几个关键包Development Tools/build-essential这是编译器的“全家桶”包含了gcc,g,make,autoconf等核心工具。没有它们编译无从谈起。wget,tar,gzip用于下载和解压源码包。openssl-devel/libssl-devZooKeeper客户端与服务端的通信默认不加密但其代码依赖OpenSSL库的一些基础功能如随机数生成。即使你不打算启用SSL加密这个开发库也是编译的必需依赖缺少它会导致编译失败。cppunit-devel/libcppunit-dev这是C单元测试框架。ZooKeeper源码中包含了大量的单元测试用例。虽然编译主库不一定强制需要但如果你想运行make test来验证编译结果或者遇到一些奇怪的链接问题安装它是很好的实践。建议一并安装。2.2 获取ZooKeeper源码我们选择安装和编译的版本是3.8.4。这是一个长期支持LTS版本相对稳定。建议从Apache官方镜像或仓库下载避免来源不明的代码。# 创建一个工作目录并进入 mkdir -p ~/zk_build cd ~/zk_build # 下载ZooKeeper 3.8.4源码包 wget https://archive.apache.org/dist/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4.tar.gz # 验证文件完整性可选但推荐 wget https://archive.apache.org/dist/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4.tar.gz.sha512 sha512sum -c apache-zookeeper-3.8.4.tar.gz.sha512 # 解压源码包 tar -zxvf apache-zookeeper-3.8.4.tar.gz cd apache-zookeeper-3.8.4解压后目录结构大致如下zookeeper-client/客户端相关代码其中zookeeper-client/zookeeper-client-c/是C客户端源码zookeeper-client/zookeeper-client-cpp/是C包装器源码。这是我们今天的主战场。zookeeper-server/服务端代码。zookeeper-jute/序列化组件。bin/,conf/服务端脚本和配置样例。注意网上有些教程会教你直接下载zookeeper-3.8.4.tar.gz那个包通常只包含二进制发行版bin/目录没有zookeeper-client-c的源码。我们编译C库必须使用包含完整客户端的源码包也就是apache-zookeeper-3.8.4.tar.gz。3. ZooKeeper 3.8.4 单机模式安装与运行在编译客户端之前我们先快速地把ZooKeeper服务端以单机模式运行起来。这样后面编译测试客户端时就有个可以连接的真实服务端方便验证。3.1 基础配置ZooKeeper服务端的运行主要依赖一个配置文件zoo.cfg和一个数据目录。# 进入解压后的目录如果还在的话 cd ~/zk_build/apache-zookeeper-3.8.4 # 复制样例配置文件 cp conf/zoo_sample.cfg conf/zoo.cfg # 创建数据目录配置文件里默认是 /tmp/zookeeper但生产环境千万别放这里 # 我们这里为了测试先使用默认配置。你可以编辑 conf/zoo.cfg 修改 dataDir 路径。 mkdir -p /tmp/zookeeper现在看一下conf/zoo.cfg的核心配置项tickTime2000 initLimit10 syncLimit5 dataDir/tmp/zookeeper clientPort2181tickTimeZooKeeper使用的基本时间单位毫秒用于心跳和超时。dataDir存储内存数据库快照和事务日志的目录。重要提示/tmp目录在系统重启后可能被清空仅用于测试。生产环境务必指向一个持久化、有足够空间的目录。clientPort客户端连接的端口默认2181。3.2 启动与验证服务ZooKeeper提供了方便的脚本来管理服务。# 启动ZooKeeper服务前台运行方便看日志 bin/zkServer.sh start-foreground如果看到日志输出中包含INFO [main:ZooKeeperServer836] - Started之类的信息并且没有报错退出说明服务启动成功。可以按CtrlC停止它。更常见的做法是后台启动# 后台启动 bin/zkServer.sh start # 查看状态 bin/zkServer.sh status状态命令会告诉你服务是standalone模式单机还是leader/follower模式集群以及是否在运行。3.3 使用Cli客户端简单测试服务跑起来后可以用自带的命令行客户端连接上去创建一个节点试试确保服务端工作正常。# 启动Cli连接到本机2181端口 bin/zkCli.sh -server 127.0.0.1:2181 # 连接成功后在Cli里执行 [zk: 127.0.0.1:2181(CONNECTED) 0] create /my_test_node hello_zk # 输出Created /my_test_node [zk: 127.0.0.1:2181(CONNECTED) 1] get /my_test_node # 输出hello_zk [zk: 127.0.0.1:2181(CONNECTED) 2] quit这个简单的测试验证了服务端可以正常处理客户端的连接和请求。接下来我们的重头戏就是编译出能发出这些请求的C客户端库。4. C客户端API编译全流程解析这是整个过程中最核心也最容易出问题的部分。ZooKeeper的C库并不是一个独立的项目它是对C客户端的面向对象封装。因此编译顺序是先编译C客户端库再编译C包装器。4.1 编译C客户端库C客户端是基石它提供了所有与ZooKeeper服务端通信的底层API。# 进入C客户端源码目录 cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-c # 执行autoreconf如果已有configure脚本可跳过但执行无害 autoreconf -if # 配置编译选项。这里有几个关键点 # --prefix指定安装目录。我们暂不安装到系统先编译到本地。 # --without-cppunit如果不打算运行单元测试可以加上以跳过对cppunit的检查。 # --enable-debug如果需要调试信息可以加上。 ./configure --prefix/usr/local/zookeeper-c-client-3.8.4 # 编译。-j参数指定并行编译的作业数可以加快速度如make -j4。 make # 可选但强烈建议运行单元测试 make test如果make test全部通过恭喜你C客户端库编译基本成功了。生成的库文件位于src/c/.libs/目录下主要是libzookeeper_st.a静态链接库单线程。libzookeeper_mt.a静态链接库多线程。libzookeeper_st.so.x.x.x动态链接库单线程。libzookeeper_mt.so.x.x.x动态链接库多线程。实操心得./configure阶段最常见的错误是找不到openssl。即使你安装了libssl-dev有时开发头文件的位置可能不在默认搜索路径。如果报错checking for openssl/ssl.h... no你可以通过指定CPPFLAGS和LDFLAGS来帮助configure找到它们./configure CPPFLAGS-I/usr/include/openssl LDFLAGS-L/usr/lib64 -lssl -lcrypto --prefix...路径/usr/include/openssl和/usr/lib64请根据你系统的实际情况调整Ubuntu可能在/usr/include和/usr/lib/x86_64-linux-gnu。4.2 编译C客户端库C库的编译依赖于刚刚编译好的C库。我们需要告诉它C库的位置。# 进入C客户端源码目录 cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-cpp # 生成构建文件。这里使用CMake这是目前推荐的方式。 # ZOOKEEPER_ROOT 指向包含C客户端源码的上一级目录即zookeeper-client-c的父目录。 # 这样CMake就能自动找到C库。 mkdir build cd build cmake .. -DZOOKEEPER_ROOT../../.. # 开始编译 make编译成功后你会在src/cpp/.libs/目录下找到C的动态库文件例如libzookeeper_mt.so.x.x.x多线程C客户端库。libzookeeper_st.so.x.x.x单线程C客户端库。同时在src/cpp/目录下会生成对应的头文件如zookeeper.hzookeeper.jute.h等这些头文件在编写C程序时需要包含。注意事项老版本的ZooKeeper可能使用autotools./configure make来构建C库。从3.5.x版本开始官方逐渐转向CMake。3.8.4版本两者都支持但CMake是更现代、更推荐的方式。如果你遇到CMake失败可以尝试回退到源码目录直接make但可能需要手动处理依赖路径。4.3 安装库文件可选如果你希望在其他项目里方便地链接这个库可以将其安装到系统目录如/usr/local或自定义目录。安装C客户端库cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-c sudo make install这会将库文件和头文件安装到之前configure时指定的--prefix目录例如/usr/local/zookeeper-c-client-3.8.4下的lib和include子目录。安装C客户端库cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-cpp/build sudo make install默认的安装前缀是/usr/local你可以通过CMake参数-DCMAKE_INSTALL_PREFIX/your/path来修改。安装后你可以在/usr/local/lib下找到libzookeeper_mt.so等库文件在/usr/local/include下找到zookeeper相关的头文件。别忘了运行sudo ldconfig更新系统的动态链接库缓存。5. 编写并编译一个简单的C测试程序库编译好了不写个程序跑一下心里总不踏实。我们来创建一个最简单的C程序连接我们刚才启动的ZooKeeper单机服务创建一个临时节点。5.1 测试程序源码创建一个文件test_zk.cpp#include iostream #include string #include zookeeper/zookeeper.h // C头文件它内部会包含C的头文件 #include zookeeper/zookeeper.jute.h #include unistd.h // for sleep // 全局的ZooKeeper句柄 zhandle_t *zh; // Watcher回调函数这里简单处理会话事件 void watcher_func(zhandle_t *zzh, int type, int state, const char *path, void* watcherCtx) { if (type ZOO_SESSION_EVENT) { if (state ZOO_CONNECTED_STATE) { std::cout [Watcher] Connected to ZooKeeper server successfully! std::endl; } else if (state ZOO_EXPIRED_SESSION_STATE) { std::cout [Watcher] Session expired! std::endl; } } } int main() { // 1. 初始化ZooKeeper连接 // 参数连接字符串超时(ms)watcher回调客户端上下文标志位 zh zookeeper_init(127.0.0.1:2181, watcher_func, 30000, nullptr, nullptr, 0); if (zh nullptr) { std::cerr Error when connecting to ZooKeeper server! std::endl; return -1; } std::cout Connecting to ZooKeeper server... std::endl; // 等待连接建立通过watcher回调通知 sleep(2); // 2. 创建一个ZNode (EPHEMERAL | SEQUENCE 标志表示临时顺序节点) std::string path /test_ephemeral_node; char path_buffer[256]; int buffer_len sizeof(path_buffer); int ret zoo_create(zh, path.c_str(), test_data, 9, // 数据长度不包括结尾的\0 ZOO_OPEN_ACL_UNSAFE, // 使用不安全的ACL仅测试 ZOO_EPHEMERAL, // 临时节点 path_buffer, buffer_len); if (ret ZOK) { std::cout Node created successfully: path_buffer std::endl; } else { std::cerr Error creating node, code: ret ( zerror(ret) ) std::endl; } // 3. 等待一段时间观察临时节点可以在此期间用zkCli.sh ls / 查看 std::cout Node exists for 10 seconds... std::endl; sleep(10); // 4. 关闭连接临时节点会自动消失 zookeeper_close(zh); std::cout Connection closed. std::endl; return 0; }5.2 编译与链接测试程序编译这个测试程序需要指定头文件路径和链接我们刚刚编译好的库。假设你的库文件在编译目录下没有进行系统安装可以这样编译# 进入测试程序所在目录 cd ~/zk_build # 设置环境变量指向库和头文件的位置 export ZK_CPP_DIR~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-cpp export ZK_C_DIR~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-c # 编译并链接 g -o test_zk_app test_zk.cpp \ -I${ZK_CPP_DIR}/src/cpp \ -I${ZK_C_DIR}/include \ -I${ZK_C_DIR}/generated \ -L${ZK_CPP_DIR}/src/cpp/.libs \ -L${ZK_C_DIR}/src/c/.libs \ -lzookeeper_mt -lpthread -ldl关键参数解释-I指定头文件搜索路径。需要C头文件、C头文件以及C客户端生成的Jute头文件路径。-L指定库文件搜索路径。分别指向C和C客户端库的编译输出目录。-lzookeeper_mt链接多线程版本的ZooKeeper C客户端库。编译器会在-L指定的路径中查找libzookeeper_mt.so。-lpthread链接POSIX线程库因为多线程版本依赖它。-ldl链接动态加载库某些系统调用需要。5.3 运行测试程序在运行前确保ZooKeeper服务端正在运行bin/zkServer.sh status确认。# 首先将库文件所在路径添加到动态链接器的搜索路径中临时生效 export LD_LIBRARY_PATH${ZK_CPP_DIR}/src/cpp/.libs:${ZK_C_DIR}/src/c/.libs:$LD_LIBRARY_PATH # 运行程序 ./test_zk_app如果一切顺利你将看到类似输出Connecting to ZooKeeper server... [Watcher] Connected to ZooKeeper server successfully! Node created successfully: /test_ephemeral_node Node exists for 10 seconds... Connection closed.同时你可以在另一个终端用zkCli.sh执行ls /应该能看到创建的/test_ephemeral_node可能带有序号后缀。当测试程序运行结束连接关闭后这个节点会自动消失这正是临时节点的特性。6. 编译与使用中的常见问题排查即使按照步骤来也可能遇到各种问题。这里汇总了几个我遇到过的高频问题及其解决方法。6.1 编译阶段问题问题1configure或cmake阶段报错找不到openssl。现象checking for openssl/ssl.h... no或 CMake报错Could NOT find OpenSSL。排查确认已安装开发包yum list installed | grep openssl-devel或dpkg -l | grep libssl-dev。确认头文件和库文件位置find /usr -name ssl.h 2/dev/null和find /usr -name libssl.so 2/dev/null。解决对于autotools在./configure时通过CPPFLAGS和LDFLAGS明确指定路径。./configure CPPFLAGS-I$(pkg-config --cflags openssl) LDFLAGS$(pkg-config --libs openssl) ...如果pkg-config不可用就手动指定如-I/usr/include/openssl -L/usr/lib64。对于CMake可以尝试指定OpenSSL根目录。cmake .. -DOPENSSL_ROOT_DIR/usr/local/openssl # 如果你的openssl装在自定义位置问题2make编译C库时报错undefined reference tozoo_xxx‘。现象链接阶段失败提示找不到C客户端库中的函数。原因CMake或makefile没有正确找到或链接C客户端库。解决确保先成功编译了C客户端库make。确保在编译C库时ZOOKEEPER_ROOT参数正确指向了包含zookeeper-client-c目录的上级目录即apache-zookeeper-3.8.4。可以尝试手动进入zookeeper-client-cpp目录直接运行make使用旧的autotools系统有时这反而更简单。但需要确保C库在系统默认的链接路径中或者设置好LIBRARY_PATH环境变量。6.2 链接与运行阶段问题问题3编译测试程序时报错fatal error: zookeeper.h: No such file or directory。原因编译器找不到头文件。解决仔细检查-I参数指定的路径是否正确。确保路径下确实存在zookeeper.h文件。C程序应包含zookeeper/zookeeper.h所以-I的路径应该是其父目录。例如如果头文件在/home/user/zk/include/zookeeper/zookeeper.h那么-I参数应该是-I/home/user/zk/include。问题4运行测试程序时报错error while loading shared libraries: libzookeeper_mt.so.2: cannot open shared object file。原因动态链接器在运行时找不到共享库。解决临时方法运行前设置LD_LIBRARY_PATH环境变量包含.so文件所在目录。永久方法推荐用于开发环境将.so文件复制到系统库目录如/usr/local/lib。创建软链接sudo ln -s /full/path/to/libzookeeper_mt.so.2 /usr/local/lib/运行sudo ldconfig更新缓存。编译时静态链接如果你不想处理动态库依赖可以在编译测试程序时使用静态库.a文件并使用-static或-Bstatic选项。但这会增大最终可执行文件的体积。问题5程序能编译运行但连接ZooKeeper服务器失败返回非ZOK状态码。排查服务端是否运行bin/zkServer.sh status确认。连接字符串检查zookeeper_init中的连接字符串格式是否正确如“127.0.0.1:2181”或“host1:2181,host2:2181”集群。防火墙检查服务器防火墙是否开放了2181端口。查看服务端日志在logs/目录下查看.log文件看是否有客户端的连接请求或错误信息。使用zerror(ret)在代码中打印错误码对应的文本信息如std::cerr zerror(ret) std::endl;这比数字码直观得多。6.3 版本与兼容性问题问题6编译出的库在另一个系统或更高版本编译器上无法使用。建议对于生产环境最好在目标部署环境或使用与生产环境一致的Docker镜像中进行编译。这样可以最大程度避免因glibc版本、编译器ABI应用二进制接口不兼容导致的问题。如果必须在开发机编译供生产机使用尽量使用较低版本的GCC如CentOS 7默认的gcc 4.8.5以保证更好的向后兼容性。7. 集成到CMake项目的最佳实践在实际的C项目中我们通常使用CMake来管理构建。将自行编译的ZooKeeper C客户端集成到CMake项目中有几种清晰的做法。7.1 使用find_package(如果已安装到系统)如果你已经将ZooKeeper库安装到了系统标准路径如/usr/local那么集成非常简单。# 在你的项目CMakeLists.txt中 cmake_minimum_required(VERSION 3.10) project(MyZkProject) find_package(ZooKeeper REQUIRED) # 如果CMake提供了FindZooKeeper.cmake模块 # 如果find_package找不到可以手动指定 # find_path(ZooKeeper_INCLUDE_DIR NAMES zookeeper/zookeeper.h) # find_library(ZooKeeper_LIBRARY NAMES zookeeper_mt) add_executable(my_zk_app src/main.cpp) target_include_directories(my_zk_app PRIVATE ${ZooKeeper_INCLUDE_DIR}) target_link_libraries(my_zk_app PRIVATE ${ZooKeeper_LIBRARY})7.2 使用FetchContent或add_subdirectory(源码集成)对于追求构建可重复性或不想依赖系统库的项目可以将ZooKeeper客户端源码作为项目的一部分来编译。# 方法一使用add_subdirectory假设你把zookeeper-client-c和zookeeper-client-cpp源码放在项目子目录third_party/zookeeper下 add_subdirectory(third_party/zookeeper) # 方法二使用FetchContent从Git仓库下载以C客户端为例C类似 include(FetchContent) FetchContent_Declare( zookeeper_c GIT_REPOSITORY https://github.com/apache/zookeeper.git GIT_TAG release-3.8.4 SOURCE_SUBDIR zookeeper-client/zookeeper-client-c ) FetchContent_MakeAvailable(zookeeper_c) # 然后链接对应的target add_executable(my_zk_app src/main.cpp) target_link_libraries(my_zk_app PRIVATE zookeeper_mt) # 链接多线程C库 # 对于C库需要先编译它并找到对应的target名7.3 手动指定路径 (最直接可控)最常见的情况是你把编译好的库和头文件放在项目目录的某个地方比如third_party/zookeeper。# 设置库的路径 set(ZOOKEEPER_ROOT ${CMAKE_SOURCE_DIR}/third_party/zookeeper) set(ZOOKEEPER_INCLUDE_DIR ${ZOOKEEPER_ROOT}/include) # 包含zookeeper子目录的头文件 set(ZOOKEEPER_LIB_DIR ${ZOOKEEPER_ROOT}/lib) # 查找头文件 find_path(ZooKeeper_INCLUDE_DIRS NAMES zookeeper/zookeeper.h PATHS ${ZOOKEEPER_INCLUDE_DIR} REQUIRED) # 查找库文件 find_library(ZooKeeper_LIBRARIES NAMES zookeeper_mt PATHS ${ZOOKEEPER_LIB_DIR} REQUIRED) add_executable(my_zk_app src/main.cpp) target_include_directories(my_zk_app PRIVATE ${ZooKeeper_INCLUDE_DIRS}) target_link_libraries(my_zk_app PRIVATE ${ZooKeeper_LIBRARIES} pthread dl)这种方式清晰明了将第三方库的依赖固定在项目内非常适合团队协作和持续集成。最后关于线程安全的选择libzookeeper_mt多线程是更通用的选择除非你非常确定你的应用只会在单线程上下文环境中访问ZooKeeper。在编译你自己的项目时如果链接了多线程库别忘了也链接pthread库-lpthread。整个过程从环境准备到集成落地虽然步骤不少但每一步都有其明确的目的。自己编译一遍不仅能得到所需的库更能加深对ZooKeeper客户端依赖和链接过程的理解以后再遇到类似问题解决起来就得心应手了。
1. 项目概述为什么需要自己编译ZooKeeper C客户端最近在搞一个分布式系统的项目底层协调服务选型时我们团队最终还是决定用ZooKeeper。理由很直接它成熟、稳定社区活跃是很多大数据框架的“标配”。但项目里有个模块是用C写的需要直接和ZooKeeper服务端交互这就绕不开它的C客户端库了。ZooKeeper官方提供了Java和C两种客户端绑定。对于C官方并没有直接提供预编译好的二进制库而是提供了一个基于C客户端封装的C包装器。这意味着如果你想在C项目里用ZooKeeper十有八九得自己动手从源码开始编译这个客户端库。这个过程说简单也简单照着文档敲命令就行说麻烦也麻烦环境依赖、编译选项、版本兼容任何一个环节出点岔子都可能让你折腾半天。特别是对于刚接触的新手或者项目环境比较“干净”的机器很容易踩坑。所以今天我就把从安装ZooKeeper 3.8.4服务端到成功编译出C客户端API库再到写一个简单的测试程序验证的完整过程结合我踩过的几个坑详细记录下来。目标就一个让你拿到这份“攻略”能在自己的Linux环境以CentOS 7/8或Ubuntu 20.04/22.04为例里一次搞定把可用的libzookeeper_mt.so多线程库或libzookeeper_st.so单线程库稳稳地编译出来。2. 环境准备与依赖梳理在开始编译之前一个干净、完备的编译环境是成功的一半。ZooKeeper的C客户端C客户端基于此编译需要一些基础开发工具和库我们得先把它们备齐。2.1 系统与基础开发工具首先确保你的系统已经安装了必要的编译工具链。打开终端执行以下命令对于基于RPM的系统如CentOS、RHEL、Fedorasudo yum groupinstall -y Development Tools sudo yum install -y wget tar gzip openssl-devel cppunit-devel对于基于APT的系统如Ubuntu、Debiansudo apt-get update sudo apt-get install -y build-essential wget tar gzip libssl-dev libcppunit-dev这里解释一下几个关键包Development Tools/build-essential这是编译器的“全家桶”包含了gcc,g,make,autoconf等核心工具。没有它们编译无从谈起。wget,tar,gzip用于下载和解压源码包。openssl-devel/libssl-devZooKeeper客户端与服务端的通信默认不加密但其代码依赖OpenSSL库的一些基础功能如随机数生成。即使你不打算启用SSL加密这个开发库也是编译的必需依赖缺少它会导致编译失败。cppunit-devel/libcppunit-dev这是C单元测试框架。ZooKeeper源码中包含了大量的单元测试用例。虽然编译主库不一定强制需要但如果你想运行make test来验证编译结果或者遇到一些奇怪的链接问题安装它是很好的实践。建议一并安装。2.2 获取ZooKeeper源码我们选择安装和编译的版本是3.8.4。这是一个长期支持LTS版本相对稳定。建议从Apache官方镜像或仓库下载避免来源不明的代码。# 创建一个工作目录并进入 mkdir -p ~/zk_build cd ~/zk_build # 下载ZooKeeper 3.8.4源码包 wget https://archive.apache.org/dist/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4.tar.gz # 验证文件完整性可选但推荐 wget https://archive.apache.org/dist/zookeeper/zookeeper-3.8.4/apache-zookeeper-3.8.4.tar.gz.sha512 sha512sum -c apache-zookeeper-3.8.4.tar.gz.sha512 # 解压源码包 tar -zxvf apache-zookeeper-3.8.4.tar.gz cd apache-zookeeper-3.8.4解压后目录结构大致如下zookeeper-client/客户端相关代码其中zookeeper-client/zookeeper-client-c/是C客户端源码zookeeper-client/zookeeper-client-cpp/是C包装器源码。这是我们今天的主战场。zookeeper-server/服务端代码。zookeeper-jute/序列化组件。bin/,conf/服务端脚本和配置样例。注意网上有些教程会教你直接下载zookeeper-3.8.4.tar.gz那个包通常只包含二进制发行版bin/目录没有zookeeper-client-c的源码。我们编译C库必须使用包含完整客户端的源码包也就是apache-zookeeper-3.8.4.tar.gz。3. ZooKeeper 3.8.4 单机模式安装与运行在编译客户端之前我们先快速地把ZooKeeper服务端以单机模式运行起来。这样后面编译测试客户端时就有个可以连接的真实服务端方便验证。3.1 基础配置ZooKeeper服务端的运行主要依赖一个配置文件zoo.cfg和一个数据目录。# 进入解压后的目录如果还在的话 cd ~/zk_build/apache-zookeeper-3.8.4 # 复制样例配置文件 cp conf/zoo_sample.cfg conf/zoo.cfg # 创建数据目录配置文件里默认是 /tmp/zookeeper但生产环境千万别放这里 # 我们这里为了测试先使用默认配置。你可以编辑 conf/zoo.cfg 修改 dataDir 路径。 mkdir -p /tmp/zookeeper现在看一下conf/zoo.cfg的核心配置项tickTime2000 initLimit10 syncLimit5 dataDir/tmp/zookeeper clientPort2181tickTimeZooKeeper使用的基本时间单位毫秒用于心跳和超时。dataDir存储内存数据库快照和事务日志的目录。重要提示/tmp目录在系统重启后可能被清空仅用于测试。生产环境务必指向一个持久化、有足够空间的目录。clientPort客户端连接的端口默认2181。3.2 启动与验证服务ZooKeeper提供了方便的脚本来管理服务。# 启动ZooKeeper服务前台运行方便看日志 bin/zkServer.sh start-foreground如果看到日志输出中包含INFO [main:ZooKeeperServer836] - Started之类的信息并且没有报错退出说明服务启动成功。可以按CtrlC停止它。更常见的做法是后台启动# 后台启动 bin/zkServer.sh start # 查看状态 bin/zkServer.sh status状态命令会告诉你服务是standalone模式单机还是leader/follower模式集群以及是否在运行。3.3 使用Cli客户端简单测试服务跑起来后可以用自带的命令行客户端连接上去创建一个节点试试确保服务端工作正常。# 启动Cli连接到本机2181端口 bin/zkCli.sh -server 127.0.0.1:2181 # 连接成功后在Cli里执行 [zk: 127.0.0.1:2181(CONNECTED) 0] create /my_test_node hello_zk # 输出Created /my_test_node [zk: 127.0.0.1:2181(CONNECTED) 1] get /my_test_node # 输出hello_zk [zk: 127.0.0.1:2181(CONNECTED) 2] quit这个简单的测试验证了服务端可以正常处理客户端的连接和请求。接下来我们的重头戏就是编译出能发出这些请求的C客户端库。4. C客户端API编译全流程解析这是整个过程中最核心也最容易出问题的部分。ZooKeeper的C库并不是一个独立的项目它是对C客户端的面向对象封装。因此编译顺序是先编译C客户端库再编译C包装器。4.1 编译C客户端库C客户端是基石它提供了所有与ZooKeeper服务端通信的底层API。# 进入C客户端源码目录 cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-c # 执行autoreconf如果已有configure脚本可跳过但执行无害 autoreconf -if # 配置编译选项。这里有几个关键点 # --prefix指定安装目录。我们暂不安装到系统先编译到本地。 # --without-cppunit如果不打算运行单元测试可以加上以跳过对cppunit的检查。 # --enable-debug如果需要调试信息可以加上。 ./configure --prefix/usr/local/zookeeper-c-client-3.8.4 # 编译。-j参数指定并行编译的作业数可以加快速度如make -j4。 make # 可选但强烈建议运行单元测试 make test如果make test全部通过恭喜你C客户端库编译基本成功了。生成的库文件位于src/c/.libs/目录下主要是libzookeeper_st.a静态链接库单线程。libzookeeper_mt.a静态链接库多线程。libzookeeper_st.so.x.x.x动态链接库单线程。libzookeeper_mt.so.x.x.x动态链接库多线程。实操心得./configure阶段最常见的错误是找不到openssl。即使你安装了libssl-dev有时开发头文件的位置可能不在默认搜索路径。如果报错checking for openssl/ssl.h... no你可以通过指定CPPFLAGS和LDFLAGS来帮助configure找到它们./configure CPPFLAGS-I/usr/include/openssl LDFLAGS-L/usr/lib64 -lssl -lcrypto --prefix...路径/usr/include/openssl和/usr/lib64请根据你系统的实际情况调整Ubuntu可能在/usr/include和/usr/lib/x86_64-linux-gnu。4.2 编译C客户端库C库的编译依赖于刚刚编译好的C库。我们需要告诉它C库的位置。# 进入C客户端源码目录 cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-cpp # 生成构建文件。这里使用CMake这是目前推荐的方式。 # ZOOKEEPER_ROOT 指向包含C客户端源码的上一级目录即zookeeper-client-c的父目录。 # 这样CMake就能自动找到C库。 mkdir build cd build cmake .. -DZOOKEEPER_ROOT../../.. # 开始编译 make编译成功后你会在src/cpp/.libs/目录下找到C的动态库文件例如libzookeeper_mt.so.x.x.x多线程C客户端库。libzookeeper_st.so.x.x.x单线程C客户端库。同时在src/cpp/目录下会生成对应的头文件如zookeeper.hzookeeper.jute.h等这些头文件在编写C程序时需要包含。注意事项老版本的ZooKeeper可能使用autotools./configure make来构建C库。从3.5.x版本开始官方逐渐转向CMake。3.8.4版本两者都支持但CMake是更现代、更推荐的方式。如果你遇到CMake失败可以尝试回退到源码目录直接make但可能需要手动处理依赖路径。4.3 安装库文件可选如果你希望在其他项目里方便地链接这个库可以将其安装到系统目录如/usr/local或自定义目录。安装C客户端库cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-c sudo make install这会将库文件和头文件安装到之前configure时指定的--prefix目录例如/usr/local/zookeeper-c-client-3.8.4下的lib和include子目录。安装C客户端库cd ~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-cpp/build sudo make install默认的安装前缀是/usr/local你可以通过CMake参数-DCMAKE_INSTALL_PREFIX/your/path来修改。安装后你可以在/usr/local/lib下找到libzookeeper_mt.so等库文件在/usr/local/include下找到zookeeper相关的头文件。别忘了运行sudo ldconfig更新系统的动态链接库缓存。5. 编写并编译一个简单的C测试程序库编译好了不写个程序跑一下心里总不踏实。我们来创建一个最简单的C程序连接我们刚才启动的ZooKeeper单机服务创建一个临时节点。5.1 测试程序源码创建一个文件test_zk.cpp#include iostream #include string #include zookeeper/zookeeper.h // C头文件它内部会包含C的头文件 #include zookeeper/zookeeper.jute.h #include unistd.h // for sleep // 全局的ZooKeeper句柄 zhandle_t *zh; // Watcher回调函数这里简单处理会话事件 void watcher_func(zhandle_t *zzh, int type, int state, const char *path, void* watcherCtx) { if (type ZOO_SESSION_EVENT) { if (state ZOO_CONNECTED_STATE) { std::cout [Watcher] Connected to ZooKeeper server successfully! std::endl; } else if (state ZOO_EXPIRED_SESSION_STATE) { std::cout [Watcher] Session expired! std::endl; } } } int main() { // 1. 初始化ZooKeeper连接 // 参数连接字符串超时(ms)watcher回调客户端上下文标志位 zh zookeeper_init(127.0.0.1:2181, watcher_func, 30000, nullptr, nullptr, 0); if (zh nullptr) { std::cerr Error when connecting to ZooKeeper server! std::endl; return -1; } std::cout Connecting to ZooKeeper server... std::endl; // 等待连接建立通过watcher回调通知 sleep(2); // 2. 创建一个ZNode (EPHEMERAL | SEQUENCE 标志表示临时顺序节点) std::string path /test_ephemeral_node; char path_buffer[256]; int buffer_len sizeof(path_buffer); int ret zoo_create(zh, path.c_str(), test_data, 9, // 数据长度不包括结尾的\0 ZOO_OPEN_ACL_UNSAFE, // 使用不安全的ACL仅测试 ZOO_EPHEMERAL, // 临时节点 path_buffer, buffer_len); if (ret ZOK) { std::cout Node created successfully: path_buffer std::endl; } else { std::cerr Error creating node, code: ret ( zerror(ret) ) std::endl; } // 3. 等待一段时间观察临时节点可以在此期间用zkCli.sh ls / 查看 std::cout Node exists for 10 seconds... std::endl; sleep(10); // 4. 关闭连接临时节点会自动消失 zookeeper_close(zh); std::cout Connection closed. std::endl; return 0; }5.2 编译与链接测试程序编译这个测试程序需要指定头文件路径和链接我们刚刚编译好的库。假设你的库文件在编译目录下没有进行系统安装可以这样编译# 进入测试程序所在目录 cd ~/zk_build # 设置环境变量指向库和头文件的位置 export ZK_CPP_DIR~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-cpp export ZK_C_DIR~/zk_build/apache-zookeeper-3.8.4/zookeeper-client/zookeeper-client-c # 编译并链接 g -o test_zk_app test_zk.cpp \ -I${ZK_CPP_DIR}/src/cpp \ -I${ZK_C_DIR}/include \ -I${ZK_C_DIR}/generated \ -L${ZK_CPP_DIR}/src/cpp/.libs \ -L${ZK_C_DIR}/src/c/.libs \ -lzookeeper_mt -lpthread -ldl关键参数解释-I指定头文件搜索路径。需要C头文件、C头文件以及C客户端生成的Jute头文件路径。-L指定库文件搜索路径。分别指向C和C客户端库的编译输出目录。-lzookeeper_mt链接多线程版本的ZooKeeper C客户端库。编译器会在-L指定的路径中查找libzookeeper_mt.so。-lpthread链接POSIX线程库因为多线程版本依赖它。-ldl链接动态加载库某些系统调用需要。5.3 运行测试程序在运行前确保ZooKeeper服务端正在运行bin/zkServer.sh status确认。# 首先将库文件所在路径添加到动态链接器的搜索路径中临时生效 export LD_LIBRARY_PATH${ZK_CPP_DIR}/src/cpp/.libs:${ZK_C_DIR}/src/c/.libs:$LD_LIBRARY_PATH # 运行程序 ./test_zk_app如果一切顺利你将看到类似输出Connecting to ZooKeeper server... [Watcher] Connected to ZooKeeper server successfully! Node created successfully: /test_ephemeral_node Node exists for 10 seconds... Connection closed.同时你可以在另一个终端用zkCli.sh执行ls /应该能看到创建的/test_ephemeral_node可能带有序号后缀。当测试程序运行结束连接关闭后这个节点会自动消失这正是临时节点的特性。6. 编译与使用中的常见问题排查即使按照步骤来也可能遇到各种问题。这里汇总了几个我遇到过的高频问题及其解决方法。6.1 编译阶段问题问题1configure或cmake阶段报错找不到openssl。现象checking for openssl/ssl.h... no或 CMake报错Could NOT find OpenSSL。排查确认已安装开发包yum list installed | grep openssl-devel或dpkg -l | grep libssl-dev。确认头文件和库文件位置find /usr -name ssl.h 2/dev/null和find /usr -name libssl.so 2/dev/null。解决对于autotools在./configure时通过CPPFLAGS和LDFLAGS明确指定路径。./configure CPPFLAGS-I$(pkg-config --cflags openssl) LDFLAGS$(pkg-config --libs openssl) ...如果pkg-config不可用就手动指定如-I/usr/include/openssl -L/usr/lib64。对于CMake可以尝试指定OpenSSL根目录。cmake .. -DOPENSSL_ROOT_DIR/usr/local/openssl # 如果你的openssl装在自定义位置问题2make编译C库时报错undefined reference tozoo_xxx‘。现象链接阶段失败提示找不到C客户端库中的函数。原因CMake或makefile没有正确找到或链接C客户端库。解决确保先成功编译了C客户端库make。确保在编译C库时ZOOKEEPER_ROOT参数正确指向了包含zookeeper-client-c目录的上级目录即apache-zookeeper-3.8.4。可以尝试手动进入zookeeper-client-cpp目录直接运行make使用旧的autotools系统有时这反而更简单。但需要确保C库在系统默认的链接路径中或者设置好LIBRARY_PATH环境变量。6.2 链接与运行阶段问题问题3编译测试程序时报错fatal error: zookeeper.h: No such file or directory。原因编译器找不到头文件。解决仔细检查-I参数指定的路径是否正确。确保路径下确实存在zookeeper.h文件。C程序应包含zookeeper/zookeeper.h所以-I的路径应该是其父目录。例如如果头文件在/home/user/zk/include/zookeeper/zookeeper.h那么-I参数应该是-I/home/user/zk/include。问题4运行测试程序时报错error while loading shared libraries: libzookeeper_mt.so.2: cannot open shared object file。原因动态链接器在运行时找不到共享库。解决临时方法运行前设置LD_LIBRARY_PATH环境变量包含.so文件所在目录。永久方法推荐用于开发环境将.so文件复制到系统库目录如/usr/local/lib。创建软链接sudo ln -s /full/path/to/libzookeeper_mt.so.2 /usr/local/lib/运行sudo ldconfig更新缓存。编译时静态链接如果你不想处理动态库依赖可以在编译测试程序时使用静态库.a文件并使用-static或-Bstatic选项。但这会增大最终可执行文件的体积。问题5程序能编译运行但连接ZooKeeper服务器失败返回非ZOK状态码。排查服务端是否运行bin/zkServer.sh status确认。连接字符串检查zookeeper_init中的连接字符串格式是否正确如“127.0.0.1:2181”或“host1:2181,host2:2181”集群。防火墙检查服务器防火墙是否开放了2181端口。查看服务端日志在logs/目录下查看.log文件看是否有客户端的连接请求或错误信息。使用zerror(ret)在代码中打印错误码对应的文本信息如std::cerr zerror(ret) std::endl;这比数字码直观得多。6.3 版本与兼容性问题问题6编译出的库在另一个系统或更高版本编译器上无法使用。建议对于生产环境最好在目标部署环境或使用与生产环境一致的Docker镜像中进行编译。这样可以最大程度避免因glibc版本、编译器ABI应用二进制接口不兼容导致的问题。如果必须在开发机编译供生产机使用尽量使用较低版本的GCC如CentOS 7默认的gcc 4.8.5以保证更好的向后兼容性。7. 集成到CMake项目的最佳实践在实际的C项目中我们通常使用CMake来管理构建。将自行编译的ZooKeeper C客户端集成到CMake项目中有几种清晰的做法。7.1 使用find_package(如果已安装到系统)如果你已经将ZooKeeper库安装到了系统标准路径如/usr/local那么集成非常简单。# 在你的项目CMakeLists.txt中 cmake_minimum_required(VERSION 3.10) project(MyZkProject) find_package(ZooKeeper REQUIRED) # 如果CMake提供了FindZooKeeper.cmake模块 # 如果find_package找不到可以手动指定 # find_path(ZooKeeper_INCLUDE_DIR NAMES zookeeper/zookeeper.h) # find_library(ZooKeeper_LIBRARY NAMES zookeeper_mt) add_executable(my_zk_app src/main.cpp) target_include_directories(my_zk_app PRIVATE ${ZooKeeper_INCLUDE_DIR}) target_link_libraries(my_zk_app PRIVATE ${ZooKeeper_LIBRARY})7.2 使用FetchContent或add_subdirectory(源码集成)对于追求构建可重复性或不想依赖系统库的项目可以将ZooKeeper客户端源码作为项目的一部分来编译。# 方法一使用add_subdirectory假设你把zookeeper-client-c和zookeeper-client-cpp源码放在项目子目录third_party/zookeeper下 add_subdirectory(third_party/zookeeper) # 方法二使用FetchContent从Git仓库下载以C客户端为例C类似 include(FetchContent) FetchContent_Declare( zookeeper_c GIT_REPOSITORY https://github.com/apache/zookeeper.git GIT_TAG release-3.8.4 SOURCE_SUBDIR zookeeper-client/zookeeper-client-c ) FetchContent_MakeAvailable(zookeeper_c) # 然后链接对应的target add_executable(my_zk_app src/main.cpp) target_link_libraries(my_zk_app PRIVATE zookeeper_mt) # 链接多线程C库 # 对于C库需要先编译它并找到对应的target名7.3 手动指定路径 (最直接可控)最常见的情况是你把编译好的库和头文件放在项目目录的某个地方比如third_party/zookeeper。# 设置库的路径 set(ZOOKEEPER_ROOT ${CMAKE_SOURCE_DIR}/third_party/zookeeper) set(ZOOKEEPER_INCLUDE_DIR ${ZOOKEEPER_ROOT}/include) # 包含zookeeper子目录的头文件 set(ZOOKEEPER_LIB_DIR ${ZOOKEEPER_ROOT}/lib) # 查找头文件 find_path(ZooKeeper_INCLUDE_DIRS NAMES zookeeper/zookeeper.h PATHS ${ZOOKEEPER_INCLUDE_DIR} REQUIRED) # 查找库文件 find_library(ZooKeeper_LIBRARIES NAMES zookeeper_mt PATHS ${ZOOKEEPER_LIB_DIR} REQUIRED) add_executable(my_zk_app src/main.cpp) target_include_directories(my_zk_app PRIVATE ${ZooKeeper_INCLUDE_DIRS}) target_link_libraries(my_zk_app PRIVATE ${ZooKeeper_LIBRARIES} pthread dl)这种方式清晰明了将第三方库的依赖固定在项目内非常适合团队协作和持续集成。最后关于线程安全的选择libzookeeper_mt多线程是更通用的选择除非你非常确定你的应用只会在单线程上下文环境中访问ZooKeeper。在编译你自己的项目时如果链接了多线程库别忘了也链接pthread库-lpthread。整个过程从环境准备到集成落地虽然步骤不少但每一步都有其明确的目的。自己编译一遍不仅能得到所需的库更能加深对ZooKeeper客户端依赖和链接过程的理解以后再遇到类似问题解决起来就得心应手了。
)
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
