★ FEATURED ARTICLE 简介Carla 0.9.15编译的zlib 1.2.13库压缩包面向需要在Carla项目中集成压缩/解压功能的开发者。zlib是应用广泛的开源压缩库该包省去从源码手动编译和依赖配置的步骤拿到后即可用于相关工程构建。包内共247个文件以C源码41个、头文件28个、Visual Studio工程文件vcxproj/sln为主配有makefile、configure等跨平台构建配置还包含minizip示例、测试程序及说明文档整体仅1.61MB结构清晰便于定位。已有380人学习/下载。在搭建Carla扩展或工具链时可直接复用这套编译产物需要定制时借助源码、头文件以及构建定义也能快速调整重编有效减少环境适配和排错成本。1. 编译 Carla 0.9.15 时卡在 zlib-1.2.13.zip是依赖链上最容易被低估的一环A同学按官方流程编译 Carla 0.9.15前面一切顺利直到构建日志停在一行zlib-1.2.13.zip的下载上光标闪了十几分钟没有动静最终以网络错误退出。这个zlib-1.2.13.zip不是随便一个压缩包而是 Carla 0.9.15 构建链上写死了版本的第三方依赖Carla 不直接使用系统自带的 zlib它要的是一个指定版本、指定目录结构、能直接喂给 CMake 的库包。文章要解决的就是三件事这个 zip 为什么会卡住构建、怎么自己编译出一个合规的 zlib 1.2.13 包、以及怎么把它塞进 Carla 的构建流程让它认账。适合网络受限的构建机、需要反复部署环境的团队以及想把 Carla 构建过程变得可预测的人。自己动手打包 zlib看起来是多走一步实际上是把整个依赖环节的主动权拿回手里。2. 为什么 Carla 0.9.15 要锁死 zlib 的版本和来源2.1 依赖获取机制构建脚本里的下载清单、缓存与哈希校验Carla 的编译不是一个 CMake 项目从头编到尾而是先由一个构建脚本把一整套第三方依赖拉到本地再统一交给 CMake 去解析。这套依赖的版本、下载地址、压缩包文件名、校验和全部写在构建脚本的依赖清单里。也就是说编译还没真正开始构建脚本就已经在按照清单逐条比对本地缓存了。我一般会把这个阶段理解为“依赖前置检查”它只做三件事查缓存目录里有没有同名文件、比对清单里的哈希值算出来是否一致、决定是直接解压还是重新下载。问题就出在这里只要网络环境访问不了清单里写的那个下载地址哪怕你本地已经有一个完全可用的 zlib 库脚本也不会去用。它只会反复尝试下载直到超时或者报错。这个机制在源码构建项目里很常见Carla 只是把它做得更严格。依赖清单里的条目通常包含 URL、文件名、解压目标路径、SHA 校验值四要素缺一个或者对不上构建脚本就会把那个包判定为无效。所以要绕过网络问题不是把 zip 扔在任意目录就行而是要精确地让脚本认为“这个依赖已经拿到了”。这一步没做对后面所有 CMake 配置都白搭。2.2 谁在链接 zlib静态库是默认选择DLL 是麻烦源zlib 在 Carla 的构建链里不是被直接调用的模块多数情况下是作为间接依赖出现。Carla 的渲染和图像处理组件通常要依赖 libpng 这类格式库而 libpng 在压缩和解压缩 PNG 数据时链接的就是 zlib。也就是说zlib 的问题往往不会单独报出来而是在链接 libpng 时突然抛出一堆inflate、deflate相关的未解析符号。这就引出一个关键选择Carla 的第三方库是静态链接还是动态链接。我建议统一走静态库方案也就是zlib.libWindows或libz.aLinux。静态链接的优点是编译产物里直接把 zlib 的二进制揉进去了部署时不用额外带一个zlib1.dll或者.so文件也就少了一类“运行时找不到动态库”的现场。动态库方案不是不能用但代价翻倍。编译时要额外处理 DLL 的导出符号Carla 跑起来时还要保证zlib1.dll在系统搜索路径里能被子进程找到。我见过不止一次编译全程通过启动模拟器时却因为zlib1.dll不在输出目录里直接崩掉。如果读者只是想让 Carla 编译通过静态库是阻力最小的路径这一点从官方依赖包默认就是静态库也能看出来。2.3 版本锁定到 1.2.13 的合理性zlib 1.2.13 是 2022 年发布的稳定版本修复了 1.2.12 中一个 deflate 越界读的漏洞CVE-2022-37434在 Carla 0.9.15 发布时属于经过充分验证的版本线。Carla 把依赖锁在 1.2.13 而不是更新的 1.3.x通常是出于组合验证的考虑毕竟整个依赖链是作为一个整体测试过的换一个 zlib 小版本都可能让 libpng 的压缩输出产生轻微差异。这里有人会想直接把系统里的 zlib 1.2.13 拷过来用行不行。Linux 上如果系统 zlib 恰好是 1.2.13 且头文件路径能被找到勉强可行但 Carla 的构建脚本要的是独立目录结构系统库散落在/usr/lib和/usr/include里脚本的目录假设就对不上了。Windows 上系统根本没有预装 zlib这条路直接堵死。结论就是自己按 Carla 的目录规范编译一个固定版本是唯一确定性足够高的做法。3. 编译 zlib 1.2.13 并打包源码到 zip 的完整操作3.1 Windows 下用 MSVC CMake 编译静态 zlib先准备 zlib 1.2.13 的源码从源码包解压后在源码根目录执行以下命令。这里用 CMake 而不是老的nmake -f win32/Makefile.msc是为了让安装目录可控也方便后续生成符合 Carla 预期的目录结构。cmake -S . -B build -G Visual Studio 17 2022 -A x64 ^ -DZLIB_BUILD_SHAREDOFF ^ -DZLIB_BUILD_STATICON ^ -DCMAKE_INSTALL_PREFIX%CD%\install cmake --build build --config Release cmake --install build参数说明-G Visual Studio 17 2022指定生成器-A x64强制 64 位架构和 Carla 0.9.15 的目标平台保持一致。ZLIB_BUILD_SHAREDOFF是关键它决定不生成zlib1.dll只产出静态库。ZLIB_BUILD_STATICON显式启用静态库目标。CMAKE_INSTALL_PREFIX指到源码目录下的install文件夹这样整个产物是集中的打包时一步到位。cmake --build build --config Release只编 Release 配置。如果后续要用 Debug 版 Carla 调试需要再补一次--config Debug因为 zlib 在 MSVC 下 Debug 和 Release 的静态库文件名不同Debug 版是zlibd.lib缺失时链接会直接找不到文件。3.2 Linux 下用 Clang 编译编译器版本必须和 Carla 工具链对齐Linux 上编译 zlib常见做法是用 CMake Ninja编译器选择 Clang。这里不是故意绕开 GCC而是 Carla 的 Linux 构建工具链本身就基于 Clang第三方库统一用同一套编译器能避免 ABI 层面的隐性冲突。如果手头有多个 Clang 版本优先选和 Carla 要求的工具链大版本接近的那一个。cmake -S . -B build -G Ninja \ -DCMAKE_C_COMPILERclang \ -DCMAKE_BUILD_TYPERelease \ -DZLIB_BUILD_SHAREDOFF \ -DZLIB_BUILD_STATICON \ -DCMAKE_INSTALL_PREFIX$PWD/install cmake --build build cmake --install build参数说明-DCMAKE_C_COMPILERclang把 C 编译器显式指定为 Clang避免 CMake 默认选到 GCC。-DCMAKE_BUILD_TYPERelease设定优化等级和 NDEBUG。剩下的 zlib 选项和 Windows 一致保持只出静态库。需要注意的是CMAKE_INSTALL_PREFIX$PWD/install这里用绝对路径展开避免相对路径在 install 阶段解析出错。Linux 上 zlib 的静态库产物名是libz.a头文件同样是zlib.h和zconf.h。编译完这一步install/lib目录下应该能看到libz.a大小在 400KB 到 600KB 之间如果只有几 KB说明编出来的可能是对象文件缺失的不完整包需要检查 CMake 输出里有没有告警。3.3 目录结构与打包多包一层文件夹是常见翻车点编译产物的目录结构直接决定 Carla 的 CMake 能不能找到头文件和库文件。Carla 期望的依赖包解压后根目录下直接是include和lib两个文件夹不能出现zlib-1.2.13/include这种嵌套路径。打包前先确认 install 目录里的结构符合预期。install/ ├── include/ │ ├── zlib.h │ └── zconf.h └── lib/ ├── zlib.lib # Windows 静态库 └── zlib.pdb # Windows 调试符号可保留确认无误后进入 install 目录打包。Linux 直接使用 zip 命令cd install zip -r ../zlib-1.2.13-linux64.zip include lib cd .. sha256sum zlib-1.2.13-linux64.zipWindows 下没有原生 zip 命令可以用 PowerShell 的Compress-Archive或者用 Windows 自带的 tar 命令以 zip 模式打包cd install tar -a -c -f ..\zlib-1.2.13-win64.zip include lib cd .. Get-FileHash .\zlib-1.2.13-win64.zip -Algorithm SHA256这里反复强调在 install 目录内执行打包是因为在外面执行zip -r zlib.zip install会把整个install文件夹作为前缀打进去解压后结构变成install/include/zlib.hCarla 的 CMake 根本不会去嵌套目录里找头文件。这个错误在构建日志里表现为找不到 zlib.h但很多人第一反应是去改 CMake 路径实际上只需要重新打包。3.4 哈希值zip 包的第二张身份证打包完成后算出的 SHA256 必须记下来它比 zip 本身更重要。Carla 的构建脚本对每个依赖包都有哈希比对官方 zip 的哈希写死在清单里你自己打的 zip 哈希必然不同如果不更新清单里的哈希值构建脚本会在校验阶段直接判定文件无效然后尝试重新下载官方版本。Windows 和 Linux 的计算命令上面的代码块已经给出。建议把zlib-1.2.13-win64.zip和zlib-1.2.13-linux64.zip分开命名Linux 的包不要拿去给 Windows 的构建用虽然 zlib 源码跨平台但静态库文件完全不兼容混用只会让 CMake 在链接时报出莫名奇妙的格式错误。4. 把 zip 接入 Carla 0.9.15 的构建流程4.1 修改依赖清单URL 和哈希必须同步改Carla 0.9.15 的构建脚本里有一份依赖清单zlib-1.2.13.zip 对应的那一行写着官方下载地址和官方哈希。要让 Carla 用你本地打包的 zip核心动作是改这两处的值。打开脚本文件定位到 zlib 条目把 URL 改成你本地 zip 的路径把哈希改成第 3 章算出来的 SHA256。修改时建议保留原行并注释掉比如# 官方源网络不通时可注释 # https://官方的zlib下载路径/zlib-1.2.13.zip # 本地包 file:///home/user/deps/zlib-1.2.13-linux64.zip这里的逻辑是构建脚本只认清单里的地址和哈希两者必须配套。只改 URL 不改哈希脚本会下载本地文件后做哈希比对发现和官方哈希不一致仍然判定失败。只改哈希不改 URL脚本还是会去访问官方地址网络不通照样卡死。两条腿必须一起换。4.2 利用缓存目录单机最快的接入方式很多构建脚本在发起下载前会先检查一个本地缓存目录这个目录通常由脚本里的变量指定比如依赖根目录或专门的下载缓存路径。如果缓存目录里已经存在同名文件且哈希匹配脚本会直接跳过下载步骤。这种机制是接入自己打包的 zip 最省事的方式前提是你要找到脚本检查的到底是哪个目录。先在脚本里搜索zlib-1.2.13.zip这个字符串往上看附近有没有文件路径拼接的逻辑通常能看到缓存目录的变量名。把你的 zip 按清单里写的文件名放进那个目录保持文件名完全一致再用第 3 章的哈希更新脚本里的校验值。需要注意缓存目录的文件名大小写Linux 构建机大小写敏感zlib-1.2.13.ZIP和zlib-1.2.13.zip会被当成两个文件。Windows 上大小写不敏感这个问题不明显但团队里有人把包从 Windows 复制到 Linux 构建机时偶尔会踩到。4.3 验证接入成功编译日志里的关键标志接入是否成功不需要等到整个 Carla 编完才知道。在构建输出里搜索关键词编译过程中 CMake 配置阶段会输出ZLIB_FOUND、ZLIB_LIBRARIES、ZLIB_INCLUDE_DIR等相关状态看到这三个值都指向你自己打包的目录说明 zlib 确实被找到了。链接阶段也值得盯一下。Windows 构建日志里应该出现zlib.lib的完整路径作为输入文件Linux 构建日志里应该出现libz.a的完整路径。如果日志里出现Could NOT find ZLIB或者ZLIB not found说明依赖接入根本没生效回到第 4.1 步检查清单修改是否保存、路径是否可读。还有一种半失败状态CMake 找到了系统的 zlib而不是你提供的包。这种情况日志里不会报错但链接时的库路径会暴露看到/usr/lib/x86_64-linux-gnu/libz.so这种路径说明 Carla 用的是系统库而不是你打包的静态库版本不可控的问题依然存在。5. 避坑zlib 导致 Carla 编译失败的五个现场5.1 下载永远卡住换网络也没有好转现象构建日志停在 zlib-1.2.13.zip 的下载步骤长时间无响应或失败后反复重试。原因构建脚本在比对哈希时发现本地文件不匹配于是删掉或忽略本地文件回到清单里的原始 URL 重新下载。下载地址访问不了整个过程就表现为无限卡住。解决先确认脚本的缓存目录里有没有同名 zip有的话手动执行一次哈希比对用你自己算出的 SHA256 更新清单。然后断开网络再触发一次构建如果脚本不再尝试外连而是直接解压本地包说明接入成功。5.2 解压报错 CRC 校验失败或文件损坏现象脚本能读到本地 zip但解压时抛 CRC 错误。原因zip 在传输过程中损坏或者打包时用的是压缩率异常的旧版 zip 工具生成的索引和文件数据不一致。解决重新执行第 3.3 节的打包命令Linux 用系统 zip 或 7zWindows 用 tar。打包完成后立刻算一次 SHA256和清单里填的值比对不要等构建报错才回头查。我自己习惯把每次打包的哈希记录在一个文本文件里构建前扫一眼就能排除低级错误。5.3 找不到 zlib.hCMake 提示 ZLIB_INCLUDE_DIR 为空现象CMake 配置阶段报找不到zlib.h路径检查这一项直接飘红。原因zip 包根目录结构错误。最常见的是在 install 目录的上一级执行了打包把 install 文件夹本身也打进去了解压后的真实路径是install/include/zlib.h而 Carla 找的是include/zlib.h。解决重新打包命令必须是先cd install再执行zip -r确保 include 和 lib 在 zip 根目录。检验方法很简单unzip -l zlib-1.2.13-linux64.zip | head查看列表第一行是不是include/。5.4 链接时报 LNK2038 或 RunTimeLibrary 不匹配现象Windows 链接阶段报LNK2038 mismatch detected for RuntimeLibrary错误信息里出现MD_DynamicRelease和MT_StaticRelease的对比。原因编译 zlib 时用的 MSVC 运行时库和 Carla 编译时的设置不同。Carla 默认用动态运行时/MD如果你编 zlib 时用了静态运行时/MT链接器会拒绝混用。解决在 zlib 的 CMake 配置里显式指定运行时库加一条-DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreadedDLL保证和 Carla 一致。如果 Carla 那边也用静态运行时则反过来两边都设成/MT重点是保持一致不要凭感觉。5.5 Linux 链接阶段报 undefined reference to inflate现象构建走到链接 libpng 时抛出一串undefined reference to inflate、undefined reference to deflate。原因静态库的链接顺序问题。Carla 的目标文件引用了 libpng 的符号libpng 又引用 zlib 的符号但链接命令里 zlib 排在 libpng 前面超出符号则直接丢弃等到 libpng 再找 zlib 符号时已经迟了。解决在 Carla 的 CMake 配置里调整 zlib 库的链接顺序确保它出现在所有引用它的库之后。实际操作中我会在 Carla 的第三方库配置里把 zlib 从PRIVATE改成PUBLIC并移动到列表末尾。如果不想动 Carla 的配置另一个可行方案是编一个动态库版 zlib动态库不受链接顺序影响但要回到第 2.2 节提过的 DLL 部署问题。6. 进阶把 zlib 包固化进团队构建让离线编译成为常态单机接入成功后下一步是把这套能力复制到整个团队。我会把 zlib-1.2.13 的 zip 和一个自制的依赖清单文件一起放进一个独立的共享目录同事克隆 Carla 源码后只需执行一个环境变量指向这个目录构建脚本就会优先从共享目录里取依赖包完全不走外网。一个值得养成的习惯是每次构建前跑一遍哈希预检脚本。脚本做的事情很机械遍历共享目录里的依赖 zip逐个计算 SHA256和清单文件里的记录比对不一致直接退出构建并打印出错的包名。这个脚本帮我拦下了至少三次手滑重新打包后忘记更新哈希的问题。第一次是某同事重新打了 zlib 包没同步哈希就直接推到了共享目录如果没这个预检全组都要等一个小时的构建跑到中间才发现挂了。另外一条经验是关于升级的。Carla 升到 0.9.16 或更高版本时zlib 的依赖往往还在但哈希值和目录约定可能变了。不要直接把 0.9.15 用的 zip 复制过去用先看新版清单要求的版本是什么如果是 1.2.13 且目录结构一致那是运气好如果锁了 1.2.13 但改了哈希算法就得重新走一遍前缀预检流程再决定是否沿用。盲目复用旧包是升级时翻车率最高的操作没有之一。最后说一个我自己的教训。最开始处理这个问题时我花了整个上午排查一个zlib.h not found最后发现只是打包时没有进入 install 目录zip 里多了一层嵌套。从那以后我给自己立了个规矩凡是给 Carla 准备依赖包打包前先看一眼解压列表所有 zip 包操作都先列表后使用。也希望这几个坑能帮你在 Carla 0.9.15 的编译路上少走弯路祝顺利。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
