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 要求:

源码可获取性
- ZBar 完整源码位于 zbar-src/vendor/zbar-0.23.93/
- 上游地址: https://github.com/mchehab/zbar
- 版本: 0.23.93
库可替换性
- 使用 system feature 可切换到系统 ZBar 库
- 提供编译脚本和说明允许用户重新编译链接
版本对齐承诺
- 定期与上游 ZBar 对齐版本
- 快速响应安全公告 (CVE)
完整文档
- 详见 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!

变更日志

详见 CHANGELOG.md

作者

kookyleo kookyleo@gmail.com

许可证

Apache-2.0 (本 Rust 包装)

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

zbar-pack 0.1.4