MongoDB 内置 Zstd 单文件库实战从 amalgamation 生成到解压、压缩与 WebGL 示例全解析【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo本文围绕 MongoDB 源码树中随 zstd 一并内置的“单文件 ZStandard 库”工具集src/third_party/zstandard/zstd/build/single_file_libs/展开以其中的示例目录 README 为核心完整讲解zstddeclib.c/zstd.c两个聚合源文件的生成方式、combine.py工具的参数与排除机制以及simple.c、emscripten.c、roundtrip.c三个官方示例的编译、运行与验证方法。读完后你可以独立复现“一个 .c 文件接入 Zstd”的集成流程并理解示例中的测试数据、桩函数stub与自动化测试脚本是如何工作的。上图为示例中 DXT1 纹理压缩数据的原始来源图片 testcard.png256x256 的 PNG 先被编码为 32KB 的 DXT1 硬件压缩块再用 Zstd 进一步压缩作为 simple.c 与 emscripten.c 的内联测试数据。1. 背景为什么需要“单文件 ZStandard 库”MongoDB 以源码树形式内置了 zstd位于src/third_party/zstandard/其中保留了上游完整的build/single_file_libs/工具集。根据 single_file_libs/README.md 的说明聚合amalgamation脚本combine.sh以及更快的 Python 版 combine.py可以把 zstd 的多个 C 源文件内联合并成一个 .c 文件这不是 header-only 库但集成复杂度类似——“往项目里加一个文件如果用公共头则两个文件无需任何配置或额外构建步骤”两种产物面向不同场景解压器decompressor最常见的场景体积很小——例如给 Emscripten 编译的 WebAssembly 工程增加约 26kB原生实现视编译器与平台增加 40–70kB完整库把压缩与解压都打包进来由zstd-in.c聚合而成体积超过 1.2MB需要搭配原始的zstd.h使用。需要注意仓库中并不直接存放生成后的zstddeclib.c/zstd.c它们是构建产物而是存放了两个聚合入口模板zstddeclib-in.c单文件解压缩器的入口模板zstd-in.c完整库压缩 解压的入口模板。2. 示例总览examples/README.md 的三个核心样例examples/README.md 给出了两条总纲是理解全部示例的钥匙示例文件直接#include生成好的zstddeclib.c但同样适用于“包含zstd.h 单独编译聚合源码”的常规方式。也就是说每个示例都支持两种编译形态形态做法说明直接内联示例文件#include ../zstddeclib.c一次编译即得到可执行文件头文件 独立编译示例#include zstd.hzstddeclib.c/zstd.c作为独立源文件一起编译更贴近常规工程组织作者说明两种方式产物大小略有差异但行为一致具体到三个样例simple.c最基本的解压与校验示例emscripten.c一个极简的 Emscripten/WebGL 演示用 Zstd 进一步压缩 DXT1 纹理原始 PNG 见同目录 testcard.png——256x256 纹理原始 DXT1 数据为 32kB但连同 Zstd 解压器一起打包后产出的 WebAssembly 仅 41kBshell.html是运行该 Wasm 的支撑文件roundtrip.c搭配完整聚合库的示例展示“压缩 → 解压 → 比对”的完整往返流程。此外 README 明确了许可证该目录下的所有示例文件以 Creative Commons ZeroCC0即公共领域视各司法辖区适用法律而定发布。3. simple.c最小可运行的单文件解压示例simple.c 是理解整个机制的最佳入口全文不到 80 行结构如下。3.1 测试数据两级压缩的 DXT1 纹理/** * Raw 256x256 DXT1 data (used to compare the result). */ static uint8_t const rawDxt1[] { #include testcard-dxt1.inl }; /** * Zstd compressed version of #rawDxt1. */ static uint8_t const srcZstd[] { #include testcard-zstd.inl }; /** * Destination for decoding #srcZstd. */ static uint8_t dstDxt1[sizeof rawDxt1] {};两个.inl文件是字节数组的字面量展开见 testcard-dxt1.inl 与 testcard-zstd.inlrawDxt1是 32768 字节的原始 DXT1 数据srcZstd是它的 Zstd 压缩形态。#include进数组体是 C 语言中内联二进制数据的常见手法——无需外部资源文件单文件即可自包含运行。3.2 桩函数让示例在“库未参与编译”时也能编译#ifndef ZSTD_VERSION_MAJOR /** * For the case where the decompression library hasnt been included we add a * dummy function to fake the process and stop the buffers being optimised out. */ size_t ZSTD_decompress(void* dst, size_t dstLen, const void* src, size_t srcLen) { return (memcmp(dst, src, (srcLen dstLen) ? srcLen : dstLen)) ? 0 : dstLen; } #endif这是示例设计的精妙之处ZSTD_VERSION_MAJOR只有在真正的 zstd 头/源码参与编译时才会被定义。若你只是单独编译simple.c例如还没生成zstddeclib.c这个假实现会顶替真实ZSTD_decompress——一方面保证工程能编译另一方面通过引用 buffer 防止编译器把它们优化掉。真实解压时memcmp比对必然不匹配返回 0测试自然判 FAILED逻辑闭环。3.3 main一次调用 双重校验int main() { size_t size ZSTD_decompress(dstDxt1, sizeof dstDxt1, srcZstd, sizeof srcZstd); int compare memcmp(rawDxt1, dstDxt1, sizeof dstDxt1); printf(Decompressed size: %s\n, (size sizeof dstDxt1) ? PASSED : FAILED); printf(Byte comparison: %s\n, (compare 0) ? PASSED : FAILED); if (size sizeof dstDxt1 compare 0) { return EXIT_SUCCESS; } return EXIT_FAILURE; }校验分两层返回值必须等于输出缓冲长度Zstd API 约定成功时返回解压实测大小且解出字节与原始 DXT1 数据逐字节相等。文件注释中还给出了体积参考在该环境下去掉 Zstd 用-Os -g0编译为 44kB 二进制加入 Zstd 后经strip增加约 56kBmacOS 10.14、Clang 10 的对比数据。4. emscripten.cWebGL Zstd 的 WebAssembly 实战emscripten.c 展示单文件解压器在极端体积约束下的用法一个旋转纹理四边形的 WebGL 演示纹理数据为硬件压缩DXT1 Zstd 再压缩的 32KB 纹理块。4.1 关键尺寸与数据流/** * Zstd compressed DXT1 256x256 texture source. */ static uint8_t const srcZstd[] { #include testcard-zstd.inl }; /** * Uncompressed size of #srcZstd. */ #define DXT1_256x256 32768 static uint8_t dstDxt1[DXT1_256x256] {};数据流为testcard.png约 12KB→ 32768 字节的 DXT1 块 → Zstd 压缩后的内联数组。main()中先用ZSTD_decompress还原 DXT1 块再通过glCompressedTexImage2D(GL_TEXTURE_2D, 0, GL_COMPRESSED_RGB_S3TC_DXT1_EXT, 256, 256, 0, DXT1_256x256, dstDxt1)直接上传压缩纹理由 GPU 硬件解码全程不把像素展开成 RGBA 数组。注释中给出对照数据去掉 Zstd 用-Os -g0 -s WASM1 -lGL编译约为 15kB 的 Wasm加入 Zstd 解压器后 Wasm 增加 26kB——与 examples/README.md 中“连同解压器总重 41kB”的说法吻合41kB ≈ 15kB 基线 26kB 解压器 内联压缩纹理数据。4.2 官方编译命令文件头部注释给出了完整的 Emscripten 编译方式export CC_FLAGS-Wall -Wextra -Werror -Os -g0 -flto --llvm-lto 3 -lGL -DNDEBUG1 export EM_FLAGS-s WASM1 -s ENVIRONMENTweb --shell-file shell.html --closure 1 emcc $CC_FLAGS $EM_FLAGS -o out.html emscripten.c要点--shell-file shell.html指向同目录的 shell.html它承载 canvas 并加载产物 Wasm--closure 1启用 Closure 压缩进一步缩小体积-Os -g0与-flto兼顾优化级别与链接期优化。5. roundtrip.c完整库的压缩 解压往返示例roundtrip.c 使用完整聚合库zstd.c与 single_file_libs/README.md 中“Full Library”一节配套。它演示了 Zstd 一次性 API 的标准调用序列size_t bounds ZSTD_compressBound(sizeof rawData); // 1. 计算最坏情况上界 void* compBuf malloc(bounds); void* testBuf malloc(sizeof rawData); ... size_t compSize ZSTD_compress(compBuf, bounds, rawData, sizeof rawData, ZSTD_maxCLevel()); // 2. 压缩 if (!ZSTD_isError(compSize)) { // 3. 错误检查 size_t decSize ZSTD_decompress(testBuf, sizeof rawData, compBuf, compSize); // 4. 解压 ... compare memcmp(rawData, testBuf, decSize); // 5. 逐字节比对 }这五个步骤正是接入任何 Zstd 场景的通用模板ZSTD_compressBound按源长度计算压缩输出所需缓冲上界避免压缩失败ZSTD_maxCLevel取当前库支持的最大压缩级别示例中桩实现返回 20即窗口日志级别的极限档ZSTD_isError所有返回size_t的 Zstd API 都用高位编码错误必须经此判断不能直接当成功处理解压与比对的逻辑与simple.c相同。示例同样内置了#ifndef ZSTD_VERSION_MAJOR保护的桩函数ZSTD_compressBound、ZSTD_maxCLevel、ZSTD_compress、ZSTD_isError、ZSTD_decompress使文件脱离聚合库也能独立编译。官方推荐编译命令见文件头注释cc -Wall -Wextra -Werror -I. -Os -g0 zstd.c examples/roundtrip.c即zstd.c聚合源码与roundtrip.c分开编译——注意这里roundtrip.c包含的是zstd.h而非聚合 .c 文件本身。6. combine.py聚合工具的参数与排除机制示例要能运行前提是先生成聚合文件。combine.py 是一个通用的 C/C 源文件“内联打包”工具同目录还有功能等价的纯 shell 版 combine.sh。6.1 参数速查参数含义-r, --root可重复文件搜索根路径等价于编译器的-I搜索路径-x, --exclude可重复完全排除某文件遇到对它的#include时在输出中写入#error Using excluded file: ...指令-k, --keep可重复保留 include 指令不内联用于项目公共 API 头如zstd.h-p, --pragma保留#pragma once指令默认会被删除因为聚合后无意义且会告警-o, --output输出文件缺省写 stdout位置参数输入入口文件-x与-k的语义差异值得注意见 combine.py 头部注释-x用于“确定 100% 不会用到”的功能把 include 替换成#error这样若有人误启用了被排除功能编译期立刻报错提示“重新聚合即可修复”-k则用于希望由使用方手动包含的公共头首次出现保留之后的重复 include 会被跳过。6.2 生成命令两个官方命令都以zstd/build/single_file_libs为工作目录在本仓库即src/third_party/zstandard/zstd/build/single_file_libs仅解压器生成zstddeclib.ccd zstd/build/single_file_libs python3 combine.py -r ../../lib -x legacy/zstd_legacy.h -o zstddeclib.c zstddeclib-in.c完整库生成zstd.c保留zstd.h的 include 指令cd zstd/build/single_file_libs python3 combine.py -r ../../lib -x legacy/zstd_legacy.h -k zstd.h -o zstd.c zstd-in.c两者共同的-x legacy/zstd_legacy.h表示关闭旧版本格式兼容legacy support这也是体积控制的一部分README 同时提醒可以构造“仅压缩器”库删掉zstd-in.c末尾 decompress 部分即可但由于解压器本身很小收益有限。6.3 内联过程做了什么结合 combine.py 源码聚合过程可以归纳为从入口文件zstddeclib-in.c/zstd-in.c逐行读取用正则^\s*#\s*include\s*(.?)识别带引号的 include尖括号系统头、被注释掉的 include 均不处理先按-r根路径集合、再按当前文件所在目录解析命中排除集 → 写#error命中保留集 → 原样保留指令已处理过的文件 → 写skipping注释去重依赖规范化路径否则递归内联并包裹/**** start inlining ... ****/标记默认丢弃#pragma once行解析不到文件时输出#error Unable to find: ...并记录 stderr 日志——所有过程性信息走 stderr保证 stdout 可以纯净地作为源码管道传递。6.4 zstddeclib-in.c 预置的编译配置入口模板 zstddeclib-in.c 在 include 任何源码之前预置了一组宏相当于把“最有用的编译开关”提前烘焙进聚合文件#define DEBUGLEVEL 0 #define MEM_MODULE #undef XXH_NAMESPACE #define XXH_NAMESPACE ZSTD_ #undef XXH_PRIVATE_API #define XXH_PRIVATE_API #undef XXH_INLINE_ALL #define XXH_INLINE_ALL #define ZSTD_LEGACY_SUPPORT 0 #define ZSTD_STRIP_ERROR_STRINGS #define ZSTD_TRACE 0 /* TODO: Cant amalgamate ASM function */ #define ZSTD_DISABLE_ASM 1 #define ZSTD_DEPS_NEED_MALLOC #include common/zstd_deps.h #include common/debug.c #include common/entropy_common.c #include common/error_private.c #include common/fse_decompress.c #include common/zstd_common.c #include decompress/huf_decompress.c #include decompress/zstd_ddict.c #include decompress/zstd_decompress.c #include decompress/zstd_decompress_block.c逐项解读注释与源码均在此文件中XXH_NAMESPACE ZSTD_XXH_PRIVATE_APIXXH_INLINE_ALL把 xxHash 以私有命名空间、内联全量方式并入既避免与使用方自己链接的 xxHash 冲突XXH_NAMESPACE的 undef/define 对也保证了这一点又保证单文件自足MEM_MODULE阻止 xxhash 重新定义BYTE、U16等与mem.h冲突的类型保持 C99 兼容ZSTD_LEGACY_SUPPORT 0不编译旧版格式解包代码对应命令行里的-x legacy/zstd_legacy.hZSTD_STRIP_ERROR_STRINGS裁掉错误描述字符串以减小体积ZSTD_TRACE 0关闭 libchardet 风格的 trace 支持ZSTD_DISABLE_ASM 1注释明确说明原因是“无法聚合汇编函数”纯 C 路径保证跨工具链可编译ZSTD_DEPS_NEED_MALLOC让zstd_deps.h引入 malloc 声明使文件在无 POSIX 头的环境下也能自成体系。文件列表也印证了“仅解压”的裁剪边界只包含common/中与解码相关的 5 个文件debug.c、entropy_common.c、error_private.c、fse_decompress.c、zstd_common.c与decompress/的全部 4 个文件没有任何compress/模块。7. 一键脚本与自动化测试单文件工具集配套了四个脚本把“生成 → 编译 → 运行 → 可选Wasm 编译”串成一键流程7.1 生成脚本create_single_file_decoder.sh生成zstddeclib.c。它会先探测 Python 版本——python3 -c import sys; assert sys.version_info (3,8)通过则用combine.py否则回退到 shell 版combine.sh脚本会提示 shell 版“较慢可能需要一会儿”create_single_file_library.sh生成zstd.c命令即 6.2 节的-k zstd.h变体。7.2 测试脚本build_decoder_test.sh 的验证链路./create_single_file_decoder.sh # 1. 生成 zstddeclib.c cc -Wall -Wextra -Wshadow -Werror -Os -g0 -o tempbin examples/simple.c ./tempbin # 2. 编译 运行 native 测试 try_emscripten_build # 3. 可选emcc 或 docker 编译 Wasm其中try_emscripten_build的策略值得借鉴优先检测本机emcc其次检测docker并用emscripten/emsdk:latest镜像挂载当前目录构建两者都没有则打印(Skipping Emscripten test)优雅跳过——即 Wasm 验证是尽力而为不阻塞核心测试。build_library_test.sh 同理先./create_single_file_library.sh生成zstd.c然后把../../lib/zstd.h复制进examples/cp $ZSTD_SRC_ROOT/zstd.h examples/zstd.h再用cc -Wall -Wextra -Werror -Wshadow -pthread -I. -Os -g0 -o tempbin zstd.c examples/roundtrip.c编译并运行 roundtrip 测试。两个脚本都以严格告警-Werror解压器测试还加-Wshadow保证聚合产物在干净编译标准下无告警任何临时产物tempbin、temp.wasm用后即删。8. 接入要点小结选型只需要解压如资源解包、Wasm 纹理解码就用zstddeclib.c增量仅 26–70kB 量级需要压缩则用zstd.czstd.h两文件方案两种 include 风格等价#include ../zstddeclib.c的“单文件全包”与#include zstd.h 独立编译聚合源码的“常规工程式”均可三个示例分别示范了前者simple.c、emscripten.c与后者roundtrip.c桩函数技巧#ifndef ZSTD_VERSION_MAJOR下的假实现让示例文件可独立编译且不会把真实测试数据优化掉这种“缺库即自测失败”的防御写法可直接借鉴重聚合时机一旦修改了zstd-in.c/zstddeclib-in.c的宏配置例如想开启ZSTD_LEGACY_SUPPORT就必须去掉-x legacy/zstd_legacy.h重新聚合必须重新运行 combine 脚本——被-x排除的文件被误用时#error指令会直接提示“re-amalgamate source to fix”许可注意示例文件为 CC0 公共领域但聚合产物内含 zstd 本体源码仍遵循 zstd 的 BSD/GPLv2 双许可见 zstddeclib-in.c 头部版权声明接入产品时按原库许可合规即可验证跑build_decoder_test.sh/build_library_test.sh可一次性验证聚合、native 编译、运行结果与 Wasm 编译四个环节全部通过标志为逐条PASSED输出。以上路径均位于 MongoDB 仓库的src/third_party/zstandard/zstd/build/single_file_libs/之下与 MongoDB 自身构建解耦可单独取用于任何 C/C 工程。【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MongoDB 内置 Zstd 单文件库实战：从 amalgamation 生成到解压、压缩与 WebGL 示例全解析
MongoDB 内置 Zstd 单文件库实战从 amalgamation 生成到解压、压缩与 WebGL 示例全解析【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo本文围绕 MongoDB 源码树中随 zstd 一并内置的“单文件 ZStandard 库”工具集src/third_party/zstandard/zstd/build/single_file_libs/展开以其中的示例目录 README 为核心完整讲解zstddeclib.c/zstd.c两个聚合源文件的生成方式、combine.py工具的参数与排除机制以及simple.c、emscripten.c、roundtrip.c三个官方示例的编译、运行与验证方法。读完后你可以独立复现“一个 .c 文件接入 Zstd”的集成流程并理解示例中的测试数据、桩函数stub与自动化测试脚本是如何工作的。上图为示例中 DXT1 纹理压缩数据的原始来源图片 testcard.png256x256 的 PNG 先被编码为 32KB 的 DXT1 硬件压缩块再用 Zstd 进一步压缩作为 simple.c 与 emscripten.c 的内联测试数据。1. 背景为什么需要“单文件 ZStandard 库”MongoDB 以源码树形式内置了 zstd位于src/third_party/zstandard/其中保留了上游完整的build/single_file_libs/工具集。根据 single_file_libs/README.md 的说明聚合amalgamation脚本combine.sh以及更快的 Python 版 combine.py可以把 zstd 的多个 C 源文件内联合并成一个 .c 文件这不是 header-only 库但集成复杂度类似——“往项目里加一个文件如果用公共头则两个文件无需任何配置或额外构建步骤”两种产物面向不同场景解压器decompressor最常见的场景体积很小——例如给 Emscripten 编译的 WebAssembly 工程增加约 26kB原生实现视编译器与平台增加 40–70kB完整库把压缩与解压都打包进来由zstd-in.c聚合而成体积超过 1.2MB需要搭配原始的zstd.h使用。需要注意仓库中并不直接存放生成后的zstddeclib.c/zstd.c它们是构建产物而是存放了两个聚合入口模板zstddeclib-in.c单文件解压缩器的入口模板zstd-in.c完整库压缩 解压的入口模板。2. 示例总览examples/README.md 的三个核心样例examples/README.md 给出了两条总纲是理解全部示例的钥匙示例文件直接#include生成好的zstddeclib.c但同样适用于“包含zstd.h 单独编译聚合源码”的常规方式。也就是说每个示例都支持两种编译形态形态做法说明直接内联示例文件#include ../zstddeclib.c一次编译即得到可执行文件头文件 独立编译示例#include zstd.hzstddeclib.c/zstd.c作为独立源文件一起编译更贴近常规工程组织作者说明两种方式产物大小略有差异但行为一致具体到三个样例simple.c最基本的解压与校验示例emscripten.c一个极简的 Emscripten/WebGL 演示用 Zstd 进一步压缩 DXT1 纹理原始 PNG 见同目录 testcard.png——256x256 纹理原始 DXT1 数据为 32kB但连同 Zstd 解压器一起打包后产出的 WebAssembly 仅 41kBshell.html是运行该 Wasm 的支撑文件roundtrip.c搭配完整聚合库的示例展示“压缩 → 解压 → 比对”的完整往返流程。此外 README 明确了许可证该目录下的所有示例文件以 Creative Commons ZeroCC0即公共领域视各司法辖区适用法律而定发布。3. simple.c最小可运行的单文件解压示例simple.c 是理解整个机制的最佳入口全文不到 80 行结构如下。3.1 测试数据两级压缩的 DXT1 纹理/** * Raw 256x256 DXT1 data (used to compare the result). */ static uint8_t const rawDxt1[] { #include testcard-dxt1.inl }; /** * Zstd compressed version of #rawDxt1. */ static uint8_t const srcZstd[] { #include testcard-zstd.inl }; /** * Destination for decoding #srcZstd. */ static uint8_t dstDxt1[sizeof rawDxt1] {};两个.inl文件是字节数组的字面量展开见 testcard-dxt1.inl 与 testcard-zstd.inlrawDxt1是 32768 字节的原始 DXT1 数据srcZstd是它的 Zstd 压缩形态。#include进数组体是 C 语言中内联二进制数据的常见手法——无需外部资源文件单文件即可自包含运行。3.2 桩函数让示例在“库未参与编译”时也能编译#ifndef ZSTD_VERSION_MAJOR /** * For the case where the decompression library hasnt been included we add a * dummy function to fake the process and stop the buffers being optimised out. */ size_t ZSTD_decompress(void* dst, size_t dstLen, const void* src, size_t srcLen) { return (memcmp(dst, src, (srcLen dstLen) ? srcLen : dstLen)) ? 0 : dstLen; } #endif这是示例设计的精妙之处ZSTD_VERSION_MAJOR只有在真正的 zstd 头/源码参与编译时才会被定义。若你只是单独编译simple.c例如还没生成zstddeclib.c这个假实现会顶替真实ZSTD_decompress——一方面保证工程能编译另一方面通过引用 buffer 防止编译器把它们优化掉。真实解压时memcmp比对必然不匹配返回 0测试自然判 FAILED逻辑闭环。3.3 main一次调用 双重校验int main() { size_t size ZSTD_decompress(dstDxt1, sizeof dstDxt1, srcZstd, sizeof srcZstd); int compare memcmp(rawDxt1, dstDxt1, sizeof dstDxt1); printf(Decompressed size: %s\n, (size sizeof dstDxt1) ? PASSED : FAILED); printf(Byte comparison: %s\n, (compare 0) ? PASSED : FAILED); if (size sizeof dstDxt1 compare 0) { return EXIT_SUCCESS; } return EXIT_FAILURE; }校验分两层返回值必须等于输出缓冲长度Zstd API 约定成功时返回解压实测大小且解出字节与原始 DXT1 数据逐字节相等。文件注释中还给出了体积参考在该环境下去掉 Zstd 用-Os -g0编译为 44kB 二进制加入 Zstd 后经strip增加约 56kBmacOS 10.14、Clang 10 的对比数据。4. emscripten.cWebGL Zstd 的 WebAssembly 实战emscripten.c 展示单文件解压器在极端体积约束下的用法一个旋转纹理四边形的 WebGL 演示纹理数据为硬件压缩DXT1 Zstd 再压缩的 32KB 纹理块。4.1 关键尺寸与数据流/** * Zstd compressed DXT1 256x256 texture source. */ static uint8_t const srcZstd[] { #include testcard-zstd.inl }; /** * Uncompressed size of #srcZstd. */ #define DXT1_256x256 32768 static uint8_t dstDxt1[DXT1_256x256] {};数据流为testcard.png约 12KB→ 32768 字节的 DXT1 块 → Zstd 压缩后的内联数组。main()中先用ZSTD_decompress还原 DXT1 块再通过glCompressedTexImage2D(GL_TEXTURE_2D, 0, GL_COMPRESSED_RGB_S3TC_DXT1_EXT, 256, 256, 0, DXT1_256x256, dstDxt1)直接上传压缩纹理由 GPU 硬件解码全程不把像素展开成 RGBA 数组。注释中给出对照数据去掉 Zstd 用-Os -g0 -s WASM1 -lGL编译约为 15kB 的 Wasm加入 Zstd 解压器后 Wasm 增加 26kB——与 examples/README.md 中“连同解压器总重 41kB”的说法吻合41kB ≈ 15kB 基线 26kB 解压器 内联压缩纹理数据。4.2 官方编译命令文件头部注释给出了完整的 Emscripten 编译方式export CC_FLAGS-Wall -Wextra -Werror -Os -g0 -flto --llvm-lto 3 -lGL -DNDEBUG1 export EM_FLAGS-s WASM1 -s ENVIRONMENTweb --shell-file shell.html --closure 1 emcc $CC_FLAGS $EM_FLAGS -o out.html emscripten.c要点--shell-file shell.html指向同目录的 shell.html它承载 canvas 并加载产物 Wasm--closure 1启用 Closure 压缩进一步缩小体积-Os -g0与-flto兼顾优化级别与链接期优化。5. roundtrip.c完整库的压缩 解压往返示例roundtrip.c 使用完整聚合库zstd.c与 single_file_libs/README.md 中“Full Library”一节配套。它演示了 Zstd 一次性 API 的标准调用序列size_t bounds ZSTD_compressBound(sizeof rawData); // 1. 计算最坏情况上界 void* compBuf malloc(bounds); void* testBuf malloc(sizeof rawData); ... size_t compSize ZSTD_compress(compBuf, bounds, rawData, sizeof rawData, ZSTD_maxCLevel()); // 2. 压缩 if (!ZSTD_isError(compSize)) { // 3. 错误检查 size_t decSize ZSTD_decompress(testBuf, sizeof rawData, compBuf, compSize); // 4. 解压 ... compare memcmp(rawData, testBuf, decSize); // 5. 逐字节比对 }这五个步骤正是接入任何 Zstd 场景的通用模板ZSTD_compressBound按源长度计算压缩输出所需缓冲上界避免压缩失败ZSTD_maxCLevel取当前库支持的最大压缩级别示例中桩实现返回 20即窗口日志级别的极限档ZSTD_isError所有返回size_t的 Zstd API 都用高位编码错误必须经此判断不能直接当成功处理解压与比对的逻辑与simple.c相同。示例同样内置了#ifndef ZSTD_VERSION_MAJOR保护的桩函数ZSTD_compressBound、ZSTD_maxCLevel、ZSTD_compress、ZSTD_isError、ZSTD_decompress使文件脱离聚合库也能独立编译。官方推荐编译命令见文件头注释cc -Wall -Wextra -Werror -I. -Os -g0 zstd.c examples/roundtrip.c即zstd.c聚合源码与roundtrip.c分开编译——注意这里roundtrip.c包含的是zstd.h而非聚合 .c 文件本身。6. combine.py聚合工具的参数与排除机制示例要能运行前提是先生成聚合文件。combine.py 是一个通用的 C/C 源文件“内联打包”工具同目录还有功能等价的纯 shell 版 combine.sh。6.1 参数速查参数含义-r, --root可重复文件搜索根路径等价于编译器的-I搜索路径-x, --exclude可重复完全排除某文件遇到对它的#include时在输出中写入#error Using excluded file: ...指令-k, --keep可重复保留 include 指令不内联用于项目公共 API 头如zstd.h-p, --pragma保留#pragma once指令默认会被删除因为聚合后无意义且会告警-o, --output输出文件缺省写 stdout位置参数输入入口文件-x与-k的语义差异值得注意见 combine.py 头部注释-x用于“确定 100% 不会用到”的功能把 include 替换成#error这样若有人误启用了被排除功能编译期立刻报错提示“重新聚合即可修复”-k则用于希望由使用方手动包含的公共头首次出现保留之后的重复 include 会被跳过。6.2 生成命令两个官方命令都以zstd/build/single_file_libs为工作目录在本仓库即src/third_party/zstandard/zstd/build/single_file_libs仅解压器生成zstddeclib.ccd zstd/build/single_file_libs python3 combine.py -r ../../lib -x legacy/zstd_legacy.h -o zstddeclib.c zstddeclib-in.c完整库生成zstd.c保留zstd.h的 include 指令cd zstd/build/single_file_libs python3 combine.py -r ../../lib -x legacy/zstd_legacy.h -k zstd.h -o zstd.c zstd-in.c两者共同的-x legacy/zstd_legacy.h表示关闭旧版本格式兼容legacy support这也是体积控制的一部分README 同时提醒可以构造“仅压缩器”库删掉zstd-in.c末尾 decompress 部分即可但由于解压器本身很小收益有限。6.3 内联过程做了什么结合 combine.py 源码聚合过程可以归纳为从入口文件zstddeclib-in.c/zstd-in.c逐行读取用正则^\s*#\s*include\s*(.?)识别带引号的 include尖括号系统头、被注释掉的 include 均不处理先按-r根路径集合、再按当前文件所在目录解析命中排除集 → 写#error命中保留集 → 原样保留指令已处理过的文件 → 写skipping注释去重依赖规范化路径否则递归内联并包裹/**** start inlining ... ****/标记默认丢弃#pragma once行解析不到文件时输出#error Unable to find: ...并记录 stderr 日志——所有过程性信息走 stderr保证 stdout 可以纯净地作为源码管道传递。6.4 zstddeclib-in.c 预置的编译配置入口模板 zstddeclib-in.c 在 include 任何源码之前预置了一组宏相当于把“最有用的编译开关”提前烘焙进聚合文件#define DEBUGLEVEL 0 #define MEM_MODULE #undef XXH_NAMESPACE #define XXH_NAMESPACE ZSTD_ #undef XXH_PRIVATE_API #define XXH_PRIVATE_API #undef XXH_INLINE_ALL #define XXH_INLINE_ALL #define ZSTD_LEGACY_SUPPORT 0 #define ZSTD_STRIP_ERROR_STRINGS #define ZSTD_TRACE 0 /* TODO: Cant amalgamate ASM function */ #define ZSTD_DISABLE_ASM 1 #define ZSTD_DEPS_NEED_MALLOC #include common/zstd_deps.h #include common/debug.c #include common/entropy_common.c #include common/error_private.c #include common/fse_decompress.c #include common/zstd_common.c #include decompress/huf_decompress.c #include decompress/zstd_ddict.c #include decompress/zstd_decompress.c #include decompress/zstd_decompress_block.c逐项解读注释与源码均在此文件中XXH_NAMESPACE ZSTD_XXH_PRIVATE_APIXXH_INLINE_ALL把 xxHash 以私有命名空间、内联全量方式并入既避免与使用方自己链接的 xxHash 冲突XXH_NAMESPACE的 undef/define 对也保证了这一点又保证单文件自足MEM_MODULE阻止 xxhash 重新定义BYTE、U16等与mem.h冲突的类型保持 C99 兼容ZSTD_LEGACY_SUPPORT 0不编译旧版格式解包代码对应命令行里的-x legacy/zstd_legacy.hZSTD_STRIP_ERROR_STRINGS裁掉错误描述字符串以减小体积ZSTD_TRACE 0关闭 libchardet 风格的 trace 支持ZSTD_DISABLE_ASM 1注释明确说明原因是“无法聚合汇编函数”纯 C 路径保证跨工具链可编译ZSTD_DEPS_NEED_MALLOC让zstd_deps.h引入 malloc 声明使文件在无 POSIX 头的环境下也能自成体系。文件列表也印证了“仅解压”的裁剪边界只包含common/中与解码相关的 5 个文件debug.c、entropy_common.c、error_private.c、fse_decompress.c、zstd_common.c与decompress/的全部 4 个文件没有任何compress/模块。7. 一键脚本与自动化测试单文件工具集配套了四个脚本把“生成 → 编译 → 运行 → 可选Wasm 编译”串成一键流程7.1 生成脚本create_single_file_decoder.sh生成zstddeclib.c。它会先探测 Python 版本——python3 -c import sys; assert sys.version_info (3,8)通过则用combine.py否则回退到 shell 版combine.sh脚本会提示 shell 版“较慢可能需要一会儿”create_single_file_library.sh生成zstd.c命令即 6.2 节的-k zstd.h变体。7.2 测试脚本build_decoder_test.sh 的验证链路./create_single_file_decoder.sh # 1. 生成 zstddeclib.c cc -Wall -Wextra -Wshadow -Werror -Os -g0 -o tempbin examples/simple.c ./tempbin # 2. 编译 运行 native 测试 try_emscripten_build # 3. 可选emcc 或 docker 编译 Wasm其中try_emscripten_build的策略值得借鉴优先检测本机emcc其次检测docker并用emscripten/emsdk:latest镜像挂载当前目录构建两者都没有则打印(Skipping Emscripten test)优雅跳过——即 Wasm 验证是尽力而为不阻塞核心测试。build_library_test.sh 同理先./create_single_file_library.sh生成zstd.c然后把../../lib/zstd.h复制进examples/cp $ZSTD_SRC_ROOT/zstd.h examples/zstd.h再用cc -Wall -Wextra -Werror -Wshadow -pthread -I. -Os -g0 -o tempbin zstd.c examples/roundtrip.c编译并运行 roundtrip 测试。两个脚本都以严格告警-Werror解压器测试还加-Wshadow保证聚合产物在干净编译标准下无告警任何临时产物tempbin、temp.wasm用后即删。8. 接入要点小结选型只需要解压如资源解包、Wasm 纹理解码就用zstddeclib.c增量仅 26–70kB 量级需要压缩则用zstd.czstd.h两文件方案两种 include 风格等价#include ../zstddeclib.c的“单文件全包”与#include zstd.h 独立编译聚合源码的“常规工程式”均可三个示例分别示范了前者simple.c、emscripten.c与后者roundtrip.c桩函数技巧#ifndef ZSTD_VERSION_MAJOR下的假实现让示例文件可独立编译且不会把真实测试数据优化掉这种“缺库即自测失败”的防御写法可直接借鉴重聚合时机一旦修改了zstd-in.c/zstddeclib-in.c的宏配置例如想开启ZSTD_LEGACY_SUPPORT就必须去掉-x legacy/zstd_legacy.h重新聚合必须重新运行 combine 脚本——被-x排除的文件被误用时#error指令会直接提示“re-amalgamate source to fix”许可注意示例文件为 CC0 公共领域但聚合产物内含 zstd 本体源码仍遵循 zstd 的 BSD/GPLv2 双许可见 zstddeclib-in.c 头部版权声明接入产品时按原库许可合规即可验证跑build_decoder_test.sh/build_library_test.sh可一次性验证聚合、native 编译、运行结果与 Wasm 编译四个环节全部通过标志为逐条PASSED输出。以上路径均位于 MongoDB 仓库的src/third_party/zstandard/zstd/build/single_file_libs/之下与 MongoDB 自身构建解耦可单独取用于任何 C/C 工程。【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
