vips-sys

English | 简体中文

Crates.io Rust docs.rs License Downloads

libvips 的 Rust 低层 FFI 绑定。追求稳定、精简，可作为更高层安全封装的基础。

核心特性

  默认 feature bindgen
绑定来源 预生成 src/bindings/prebuilt.rs 现场 bindgen + clang
需要 libclang？ 否 是
典型 cargo build 秒级 首次较慢
适用场景 日常开发 / CI 更新 API / 跟进新版 libvips

默认构建不跑 bindgen，只需要能链接到 libvips 库。

0.3.0 兼容性

helpers::shutdown 改为 unsafe：调用者必须确认全部 libvips 对象和线程已结束， 且之后不会再调用 libvips。常规应用应保持初始化状态直至进程退出；初始化失败允许重试。

v8_18 feature 请求 libvips 8.18+ 的链接探测。默认预生成文件也包含较新声明， 但声明不代表旧系统库具有相应符号，使用前必须满足各 API 的版本要求。

子模块固定至最新正式版 8.18.7，其公开头文件相对 8.18.6 没有变化。 完整核查见 upstream review。

安装

macOS

brew install vips pkg-config
# Apple Silicon：
export PKG_CONFIG_PATH=/opt/homebrew/lib/pkgconfig

Debian / Ubuntu

sudo apt-get install -y libvips-dev pkg-config

Windows（MSVC）

set VCPKG_ROOT=C:\path\to\vcpkg
vcpkg install libvips:x64-windows
set VCPKGRS_TRIPLET=x64-windows
set VCPKGRS_DYNAMIC=1
set PATH=%VCPKG_ROOT%\installed\x64-windows\bin;%PATH%
cargo test --features helpers

官方端口名是 libvips，Unix 下的 pkg-config 名称仍是 vips。 实际库名及依赖从安装清单读取；动态 triplet 还需要 VCPKGRS_DYNAMIC=1， 并将对应 DLL 目录加入 PATH。

静态 libvips 配合 Rust 默认动态 CRT：

vcpkg install libvips:x64-windows-static-md
set VCPKGRS_TRIPLET=x64-windows-static-md
cargo test --features helpers,static

静态 CRT 使用 x64-windows-static，同时设置 RUSTFLAGS=-Ctarget-feature=+crt-static。架构按 Rust target 将 x64 替换为 arm64 或 x86。VCPKGRS_TRIPLET 优先于 VCPKG_DEFAULT_TRIPLET；未指定时， 静态请求匹配目标架构与 CRT，其他请求遵循 vcpkg-rs 默认策略：通常为 static-md， 显式动态链接或静态 CRT 时采用对应 triplet。

MSVC 探测跟随 Cargo 目标环境，支持交叉编译时选择目标头文件和链接元数据； 实际生成可运行程序仍需交叉链接器和针对目标构建的库。

Cargo 用法

[dependencies]
vips-sys = { version = "0.3.0", features = ["helpers"] }

Features

Feature 默认 说明
(无) ✓ 预生成绑定 + 链接探测
helpers   init / is_initialized / unsafe shutdown / 带缓存的版本查询
static   优先静态链接（可用 LIBVIPS_STATIC=1 覆盖）
dynamic   优先动态链接
bindgen   用 clang 按本机头文件重新生成绑定
stub   无系统库时链接 stub/vips_stub.c（仅测试）

无系统 libvips 时跑测试

cargo test --features helpers,stub

找不到真实库时，stub 会编译最小 C 桩（vips_init / vips_version 等）以便链接单测。 有真实库时永远优先用真实库；生产二进制不要带 stub 构建。

静态链接

vips-sys = { version = "0.3.0", features = ["static"] }

LIBVIPS_STATIC=1 cargo build

解析顺序：

  1. 已装静态库时走 pkg-config --static / vcpkg static triplet
  2. 有 meson + ninja 时从 vendor/libvips 构建到 OUT_DIR
  3. 否则给出明确错误

static 选择 libvips 静态归档，系统 codec 依赖仍可动态链接。 原生 vendor 构建需要 Meson 0.60+、Ninja 及 GLib/codec 开发文件。 MESON_PATH / NINJA_PATH 指定工具，CXXSTDLIB 可覆盖自定义工具链的 C++ 运行库。 仅构建归档与开发文件；源文件变化由 Ninja 增量重建，编译环境变化会重置 Meson 配置。 交叉目标需要预先构建的目标库。

子模块中的 libvips

vendor/libvips 固定 libvips v8.18.7 （参见 rust-sys-crate）：

git clone --recurse-submodules <本仓库>
# 或：
git submodule update --init --recursive

链接 / 头文件解析：

  1. LIBVIPS_LIB_DIR / LIBVIPS_INCLUDE_DIR（可选 LIBVIPS_STATIC=1）
  2. 系统库：pkg-config（Unix）或 vcpkg（MSVC）
  3. 请求静态时尝试 vendor + meson
  4. 回退 vendor 头文件（仍需可链接的库）

刷新预生成绑定

# 需要：libclang、glib 头文件，以及 vips 头文件（系统或 vendor 子模块）
cargo build --features bindgen
# build.rs 会打印 OUT_DIR 路径，复制覆盖即可：
python3 scripts/refresh-prebuilt.py target/debug/build/<exact-build-id>/out/binding.rs --version 8.18.7

wrapper.h 作为唯一 bindgen 入口保留；generate.sh 已移除，改用 bindgen feature。

构建期导出：

刷新完整预生成接口时，头文件应启用 deprecated API。脚本会核对版本并拒绝意外删除现有声明，且不会把维护者的 codec 配置写入通用默认文件。

示例（helpers）

use vips_sys::helpers;

fn main() {
    helpers::init("vips-sys-example").expect("vips init failed");
    let (a, b, c) = helpers::version();
    println!("libvips {}.{}.{} ({})", a, b, c, helpers::version_string());
    // 全局资源保持可用，由操作系统在进程退出时回收。
}

环境变量

变量 作用
PKG_CONFIG_PATH 查找 vips.pc
LIBVIPS_LIB_DIR / LIBVIPS_INCLUDE_DIR 显式指定库 / 头文件
LIBVIPS_STATIC 1 优先静态；0/false/off 关闭
LIBVIPS_NO_VENDOR 忽略 vendor/libvips
LIBVIPS_NO_BINDGEN 与 bindgen 合用时复制预生成绑定，无需解析头文件
LIBVIPS_VERSION 覆盖用于 cfg 的版本字符串
VCPKG_ROOT Windows vcpkg 根目录
VCPKGRS_TRIPLET / VCPKG_DEFAULT_TRIPLET 显式 triplet，前者优先
VCPKGRS_DYNAMIC 使用动态 vcpkg 库时必须设置
BINDGEN_EXTRA_CLANG_ARGS 额外 clang 参数（bindgen feature）
LIBCLANG_PATH libclang 路径（bindgen feature）
MESON_PATH / NINJA_PATH 原生 vendor 构建工具
CXXSTDLIB 静态 provider 的 C++ 运行库覆盖

故障排查

许可证

本 crate 的 Rust 源码（含 build.rs、src/）采用 MIT 许可。

libvips 本体为 LGPL-2.1 （并依赖 GLib 等兼容组件）。该许可不是 MIT，也不会把本 crate 改成 LGPL。

对使用者的含义

产物 许可
vips-sys 源码 / 预生成 FFI 声明 MIT
链接的 libvips 库（系统包、vcpkg 或 vendor/ 构建） LGPL-2.1
你最终链接 libvips 的二进制 必须满足 libvips 的 LGPL-2.1 义务

实务建议：

以上为工程实践说明，不构成法律意见；商用合规请咨询律师。

更新日志

参见 CHANGELOG.md。

This site is open source. Improve this page.