7 个版本

0.2.4 2023 年 3 月 22 日
0.2.3 2023 年 3 月 17 日
0.2.1 2021 年 3 月 19 日
0.1.0 2020 年 11 月 16 日
0.0.1 2020 年 2 月 11 日

#135FFI

Download history 24/week @ 2024-03-11 21/week @ 2024-03-18 18/week @ 2024-03-25 34/week @ 2024-04-01 16/week @ 2024-04-08 9/week @ 2024-04-15 25/week @ 2024-04-22 19/week @ 2024-04-29 14/week @ 2024-05-13 24/week @ 2024-05-20 16/week @ 2024-05-27 15/week @ 2024-06-03 22/week @ 2024-06-10 15/week @ 2024-06-17 25/week @ 2024-06-24

每月 78 次下载
4 个 Crates 中使用 (直接使用 2 个)

MIT/Apache

32KB
385

用途

使用 Cargo.toml 文件中嵌入的元数据来生成 C 库的绑定。

这是一个一站式解决方案,是 -sys Crates 的替代品,每个 Crates 都应该为单个 C 库单独生成绑定。

要求

  1. C 库可以使用 bindgen 的默认配置编译。

  2. C 库提供 pkg-config 文件,或者其安装与此 Crates 的假设一致。

  3. 此库的下游 Crates 应在其 build.rs 中调用 inwelling::to( "clib" ),并且需要 cargo add --build inwelling

使用演示:tk 库元数据的逐步解释

tcl 和 tk 库的示例 Cargo.toml 文件位于 examples/ 文件夹中。让我们以 tk 的元数据为例。

元数据部分

[package.metadata.inwelling.clib]
build = ["tk86"]

所有元数据都位于部分 [package.metadata.inwelling.clib],因为此 Crates 依赖于 Crates lib,它利用 Crates inwelling 从下游用户收集元数据。

build = ["tk86"] 表示 Crates tk 正在请求 Crates clib 构建 tk86 的 C 库。

构建规范部分

[package.metadata.inwelling.clib.spec.tk86]

本节提供了必要的信托来探测库的头文件、包含/链接路径以及需要链接的C库,无论是否使用 pkg-config

注意,“spec”放在“clib”和“tk86”之间在章节名称中。这是构建tk86的规范,但不是要求crate clib构建。如上所述,它是 build = ["tk86"],这使得clib构建tk86。

列举pkg-config文件的名称

[package.metadata.inwelling.clib.spec.tk86]
pc-alias = ["tk"]

此值告诉 pkg-configtk86.pc 不存在时查找 tk.pc

列举tk库的头文件

[package.metadata.inwelling.clib.spec.tk86]
headers = ["tk.h"]

此值告诉crate bindgen,“tk.h”是tk86库的头文件。

列举依赖项

[package.metadata.inwelling.clib.spec.tk86]
dependencies = ["tcl86"]

此值指定tcl86作为tk86的依赖项。crate clib将递归探测tcl86及其依赖项(实际上,本例中没有)。

tcl86的元数据位于 [package.metadata.inwelling.clib.spec.tcl86] 部分,位于 examples/tcl/Cargo.toml,它将由crate inwelling收集。

列举可能的可执行文件名称

[package.metadata.inwelling.clib.spec.tk86]
exe = ["wish86", "wish"]

exe = ["wish86", "wish"] 表示tk外壳的可执行文件名称可能是“wish86”或“wish”。这是可选的,仅在 pkg-config 缺失或未能探测库时使用。crate clib将尝试定位可执行文件,并期望包含和链接路径分别为“../include/{some-dir-in-includedir}”和“../lib”。请注意,“wish86.exe”和“wish.exe”在Windows中不是必需的。

列举可能的包含路径

[package.metadata.inwelling.clib.spec.tk86]
includedir = ["tk8.6", "tk"]

includedir = ["tk8.6", "tk"] 表示位于“../include”中可能存在的包含路径的名称。如果这些路径中任何一个都不存在,则期望包含路径为“../include”。这是可选的,仅在 pkg-config 缺失或未能探测库时使用。

导入额外的包含路径

[package.metadata.inwelling.clib.spec.tk86]
header-dependencies = ["x11"]

此值告诉crate clib递归地将x11及其“header-dependencies”的包含路径(如果有的话)添加到tk的。

库部分

[package.metadata.inwelling.clib.spec.tk86.libs]
tk = ["libtk86.so", "libtk8.6.so", "libtk.so", "libtk86.a", "libtk.a", "libtk86.dll.a", "libtk.dll.a", "tk86t.dll", "tk86t.lib"]
tkstub = ["libtkstub86.a", "libtkstub8.6.a", "libtkstub.a", "tkstub86.lib"]

tk = [..] 列举需要链接的可能库文件名称。请注意,键名“tk”仅用于人类可读性。

一旦在链接路径下找到某些名称的文件,crate clib将停止搜索并向cargo发出“cargo:rustc-link-lib={the-stripped-name}”消息。例如,如果找到“libtk86.so”,则将前缀“lib”和后缀“.so”删除,并发出“cargo:rustc-link-lib=tk86”。

全局命名空间

所有生成的函数、类型和常量都位于此crate的根命名空间中。您可以用clib::来作为它们的前缀,例如:clib::Tcl_Init()/clib::Tk_Init(),或者使用use clib::*;并直接使用Tcl_Init()/Tk_Init()。另一方面,tcl-sys和tk-sys的传统"-sys" crate分别生成tcl_sys::Tcl_Init()tk_sys::Tk_Init()

注意事项

Windows对pkg-config支持不佳

如果操作系统上pkg-config工作正常,则此crate运行良好。当这种情况不成立时,例如在Windows上,crate clib将根据一些假设搜索安装位置,搜索可能会以更高的概率失败。

许可证

根据Apache License 2.0或MIT License,由您决定。

无运行时依赖

~0–2.6MB
~42K SLoC