zbar-pack

zbar-pack 是一个 ZBar 条码扫描库的 Rust 包装,提供静态链接和跨平台支持。

特性

• ✅ 静态链接: 默认编译并静态链接内置的 ZBar 源码,无需系统依赖
• ✅ musl 构建: 完整支持 musl 目标,便于创建完全静态的可执行文件
• ✅ 跨平台: 支持 Linux (glibc/musl)、macOS、Windows (MSVC/GNU)
• ✅ 安全 API: 提供符合 Rust 习惯的安全高层 API
• ✅ 灵活配置: 通过 feature flags 控制编解码器和链接方式
• ✅ 许可证合规: 完整的 LGPL 合规说明和源码可替换性

快速开始

安装

在 Cargo.toml 中添加:

[dependencies]
zbar-pack = "0.1"

基础用法

use zbar_pack::{ImageScanner, Image, SymbolType};

fn main() {
    // 创建扫描器
    let mut scanner = ImageScanner::new().unwrap();

    // 配置扫描器 (可选)
    scanner.set_config(SymbolType::QRCODE, 0, 1).unwrap();

    // 从灰度图像数据创建图像
    let image = Image::from_gray(&data, width, height).unwrap();

    // 扫描图像
    let symbols = scanner.scan_image(&image).unwrap();

    // 遍历识别到的符号
    for symbol in symbols {
        println!("类型: {:?}", symbol.symbol_type());
        println!("数据: {}", symbol.data());
        println!("质量: {}", symbol.quality());
    }
}

Feature Flags

链接模式

• vendored (默认): 编译并静态链接内置的 ZBar 源码
• system: 使用 pkg-config 查找系统安装的 ZBar 库
• dynamic: 动态链接系统 ZBar 库

编解码器

• all-codecs (默认): 启用所有编解码器
• minimal: 最小化构建,需手动启用需要的编解码器
• codec-qrcode: QR 码
• codec-ean: EAN/UPC 系列
• codec-code128: Code 128
• codec-code93: Code 93
• codec-code39: Code 39
• codec-codabar: Codabar
• codec-i25: Interleaved 2 of 5
• codec-databar: GS1 DataBar
• codec-sqcode: SQ 码

示例配置

# 仅支持 QR 码的最小化构建
[dependencies]
zbar-pack = { version = "0.1", default-features = false, features = ["vendored", "codec-qrcode"] }

# 使用系统 ZBar 库
[dependencies]
zbar-pack = { version = "0.1", default-features = false, features = ["system"] }

构建要求

vendored 模式 (默认)

• Rust 1.70+
• C 编译器 (gcc/clang/msvc)
• 无需系统 ZBar 库

system 模式

• Rust 1.70+
• 系统已安装 ZBar 库 (版本 >= 0.10)
• pkg-config (Linux/macOS)

musl 静态构建

# 安装 musl 工具链
rustup target add x86_64-unknown-linux-musl

# 编译静态可执行文件
cargo build --release --target x86_64-unknown-linux-musl

许可证与合规

本项目许可证

• zbar-pack (本 Rust 包装): Apache-2.0

ZBar 上游许可证

• ZBar 库: LGPLv2.1+

LGPL 静态链接合规

本项目在 vendored 模式下静态链接 ZBar (LGPLv2.1+),为满足 LGPL 要求:

1. 源码可获取性

   • ZBar 完整源码位于 zbar-src/vendor/zbar-0.23.93/
   • 上游地址: https://github.com/mchehab/zbar
   • 版本: 0.23.93

2. 库可替换性

   • 使用 system feature 可切换到系统 ZBar 库
   • 提供编译脚本和说明允许用户重新编译链接

3. 版本对齐承诺

   • 定期与上游 ZBar 对齐版本
   • 快速响应安全公告 (CVE)

4. 完整文档

   • 详见 COMPLIANCE.md
   • 重新链接指南见 RELINKING.md

何时使用 system 模式

建议在以下场景使用 system 模式:

• 企业发行版策略要求使用系统库
• Linux 发行版打包
• 需要快速获得发行版安全补丁
• 简化合规流程

平台差异说明

Linux

• glibc: 支持动态和静态链接,但静态链接 glibc 存在已知问题,不推荐
• musl: 推荐用于全静态构建,兼容性好

macOS

• 使用 Clang 和系统 SDK
• 自动处理 rpaths

Windows

• 支持 MSVC 和 GNU 工具链
• MSVC: 使用 UCRT
• GNU: 使用 MSVCRT

包体积控制

为符合 crates.io 的体积限制:

• 使用精简的 ZBar 源码快照
• 不包含完整 git 历史
• 排除测试资源和示例图片
• 移除不必要的平台特定代码

故障排除

编译失败

# 清理构建缓存
cargo clean

# 尝试使用 system 模式
cargo build --no-default-features --features system

musl 链接错误

确保使用正确的目标三元组:

cargo build --target x86_64-unknown-linux-musl

Windows MSVC 问题

确保安装了 Visual Studio Build Tools 或完整的 Visual Studio。

贡献

欢迎提交 Issue 和 Pull Request!

相关项目

• zbar - 上游 ZBar C 库
• zbar-rust - 另一个 Rust 绑定

变更日志

详见 CHANGELOG.md

作者

kookyleo kookyleo@gmail.com

许可证

Apache-2.0 (本 Rust 包装)

ZBar 库遵循 LGPLv2.1+ 许可证,详见 zbar-src/vendor/zbar-0.23.93/LICENSE.md