facebook/openzl

# OpenZL OpenZL 提供了高压缩率，同时保持了高速度，这是通用压缩器无法企及的性能水平。**请查看我们的[博客文章](https://engineering.fb.com/2025/10/06/developer-tools/openzl-open-source-format-aware-compression-framework/)和[白皮书](https://arxiv.org/abs/2510.03203)，了解其工作原理的详细解析。** OpenZL 会获取您的数据描述，并据此构建一个专为您的特定格式优化的专用压缩器。[了解其工作原理 →](https://facebook.github.io/openzl/getting-started/introduction/) OpenZL 由一个核心库和用于生成专用压缩器的工具组成 —— 所有这些都与单一的通用解压器兼容。 它专为处理大量专用数据集（例如 AI 工作负载）且要求处理管道具备高速度的工程师而设计。 请参阅我们的[文档](https://facebook.github.io/openzl)获取更多信息，或通过我们的[快速入门指南](https://facebook.github.io/openzl/getting-started/quick-start)开始引导式教程。 ## 项目状态 本项目正在积极开发中。OpenZL 的 API、压缩格式以及包含的编解码器和图谱都可能会（并且一定会！）随着项目的成熟而发生改变。 然而，我们打算在不断演进的过程中维持一定的稳定性保证。特别是，使用任何带有发布标签的库版本压缩的 payload，在至少未来几年内仍可被该库的新版本解压。并且该库的新版本将能够生成至少兼容上一个版本的帧。 （`dev` 分支上的提交不提供任何保证。对于任何非实验性部署，请仅使用带有发布标签的提交。） 尽管有上述严厉的警告，但我们认为其核心已经达到生产就绪状态，并且 OpenZL 已在 Meta 的生产环境中得到广泛应用。 ## 构建 OpenZL ### 前置条件 OpenZL 需要支持 C11 和 C++17 的编译器。使用 `cmake` 构建时，需要 `cmake 3.20.2` 或更高版本。我们正在努力放宽这些限制。随着相关进展，本节将及时更新。 ### 使用 `make` 构建 可以使用 `make` 构建 OpenZL 库和基础工具： ``` make ``` #### 构建选项 `Makefile` 支持所有标准的构建变量，例如 `CC`、`CFLAGS`、`CPPFLAGS`、`LDFLAGS`、`LDLIBS` 等。 它默认构建时启用多线程，会自动检测本地核心数，并可以使用标准的 `-j#` 标志进行覆盖（例如：`make -j8`）。 #### 构建类型 可以通过显式指定构建类型来更改二进制文件的生成方式： 示例： ``` make lib BUILD_TYPE=DEV ``` 构建类型已在 `make help` 中详细说明，其具体标志则通过 `make show-config` 详述。 常用的构建类型包括： * `BUILD_TYPE=DEV`：启用断言及 ASAN / UBSAN 的 debug 构建 * `BUILD_TYPE=OPT`：禁用断言的优化构建（默认） ### 使用 `cmake` 构建 OpenZL 可以使用 `cmake` 构建。基本用法如下： ``` mkdir build cd build cmake -DCMAKE_BUILD_TYPE=Release -DOPENZL_BUILD_TESTS=ON .. make -j make -j test ``` 有关设置 CMake 变量的详细信息请见下文。 #### 构建模式 默认情况下，我们提供了几种不同的预定义构建模式，可以通过 `OPENZL_BUILD_MODE` 变量进行设置： * `none`（默认）：由 `CMAKE_BUILD_TYPE` 控制的 CMake 默认构建模式 * `dev`：启用断言及 ASAN / UBSAN 的 debug 构建 * `dev-nosan`：启用断言的 debug 构建 * `opt`：禁用断言的优化构建 * `opt-asan`：禁用断言并启用 ASAN / UBSAN 的优化构建 * `dbgo`：启用断言的优化构建 * `dbgo-asan`：启用断言及 ASAN / UBSAN 的优化构建 对于 ASAN / UBSAN，请确保机器上已安装 `libasan` 和 `libubsan`。 #### 编辑器集成 OpenZL 附带了相关设置，可将 VSCode 配置为与 CMake 构建系统配合使用。要启用此功能，请安装以下两个扩展： 1. `cmake-tools` 2. `clangd`（或任何其他支持 `compile_commands.json` 的 C++ 语言服务器） **重要提示：** 为了获得完善的 C++ 语言服务器支持，您需要生成 `compile_commands.json`： 首选方法是使用 CMake Tools 扩展命令“`CMake: Configure`”。 如果此方法无效或设置过于繁琐，您可以使用手动设置： ``` mkdir -p cmakebuild cmake -B cmakebuild -DOPENZL_BUILD_TESTS=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON . cp cmakebuild/compile_commands.json . ``` **何时需要重新生成：** * 在克隆仓库之后（首次设置） * 添加或删除源文件时 * 修改 `CMakeLists.txt` 时 #### CMake 变量 * `CMAKE_C_COMPILER` = 设置用于 OpenZL 和依赖项构建的 C 编译器 * `CMAKE_CXX_COMPILER` = 设置用于 OpenZL 和依赖项构建的 C++ 编译器 * `CMAKE_C_FLAGS` = 用于 OpenZL 和依赖项构建的 C 标志 * `CMAKE_CXX_FLAGS` = 用于 OpenZL 和依赖项构建的 C++ 标志 * `OPENZL_BUILD_TESTS=ON` = 拉取测试依赖并构建单元/集成测试 * `OPENZL_BUILD_BENCHMARKS=ON` = 拉取基准测试依赖并构建基准测试可执行文件 * `OPENZL_BUILD_MODE` = 设置 OpenZL 及其依赖项的构建模式 * `OPENZL_SANITIZE_ADDRESS=ON` = 为 OpenZL 启用 ASAN & UBSAN（不包含依赖项） * `OPENZL_COMMON_COMPILE_OPTIONS` = 仅用于 OpenZL 的共享 C/C++ 编译器选项 * `OPENZL_C_COMPILE_OPTIONS` = 仅用于 OpenZL 的 C 编译器选项 * `OPENZL_CXX_COMPILE_OPTIONS` = 仅用于 OpenZL 的 C++ 编译器选项 * `OPENZL_COMMON_COMPILE_DEFINITIONS` = 仅用于 OpenZL 的共享 C/C++ 编译器定义 (-D) * `OPENZL_C_COMPILE_DEFINITIONS` = 仅用于 OpenZL 的 C 编译器定义 (-D) * `OPENZL_CXX_COMPILE_DEFINITIONS` = 仅用于 OpenZL 的 C++ 编译器定义 (-D) * `OPENZL_COMMON_FLAGS` = 所有目标中使用的额外编译器标志 ### Windows 构建 OpenZL 使用了 MSVC 可能无法完全支持的现代 C11 特性。对于 Windows 构建，我们推荐使用 **clang-cl** 以获得最佳兼容性。 #### 快速入门 (Windows) 1. **推荐**：使用 `clang-cl` 以获得完整的 C11 支持 ``` cmake -S . -B build -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl cmake --build build --config Release ``` 2. **备选方案**：使用 MinGW-w64 以兼容 GNU 工具链。 ``` cmake -S . -B build -G "MinGW Makefiles" cmake --build build --config Release ``` 3. **有限支持**：MSVC 可能由于对 C11 的支持有限而产生 C2099 错误。 #### 编译器检测 运行我们的检测脚本以检查可用的编译器并获取建议： ``` # PowerShell ./build-scripts/cmake/detect_windows_compiler.ps1 # Command Prompt ./build-scripts/cmake/detect_windows_compiler.bat ``` 有关详细的 Windows 构建说明、故障排除和安装指南，请参阅 [build-scripts/cmake/WINDOWS_BUILD.md](build-scripts/cmake/WINDOWS_BUILD.md)。 ## 许可证 OpenZL 采用 BSD 许可证，详见 [LICENSE](LICENSE) 文件。

标签：AI数据集, Bash脚本, C++, DNS解析, Meta, 专用压缩器, 大规模数据处理, 客户端加密, 工程工具, 开源框架, 开源项目, 快速压缩, 持续集成, 数据压缩, 数据处理流水线, 数据擦除, 数据编解码, 文件压缩, 无损压缩, 格式感知压缩, 算法优化, 系统库, 通用解压器, 高压缩率