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 日 |
#135 在 FFI
每月 78 次下载
在 4 个 Crates 中使用 (直接使用 2 个)
32KB
385 行
用途
使用 Cargo.toml 文件中嵌入的元数据来生成 C 库的绑定。
这是一个一站式解决方案,是 -sys
Crates 的替代品,每个 Crates 都应该为单个 C 库单独生成绑定。
要求
-
C 库可以使用
bindgen
的默认配置编译。 -
C 库提供 pkg-config 文件,或者其安装与此 Crates 的假设一致。
-
此库的下游 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-config
在 tk86.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