Purpose

Use metadata embeded in Cargo.toml files to generate bindings to C libraries.

It is an all-in-one solution, an alternative to -sys crates, each of which should have generated bindings separately for one single C library.

Requirements

1. C libraries can be compiled with bindgen's default configuration.

2. C libraries provides pkg-config file, or its installation is consistent with the assumption of this crate.

3. The downstream crates of this library should invoke inwelling::to( "clib" ) in their build.rs, and cargo add --build inwelling is required.

Usage demonstration: step-by-step explanation of tk library metadata

Sample Cargo.toml files of tcl and tk libraries are in examples/ folder. Let's take tk's metadata for demonstration.

Section of metadata

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

All metadata are located in section [package.metadata.inwelling.clib], because this crate depends on crate lib, which utilizes crate inwelling to collect metadata from downstream users.

The value build = ["tk86"] indicates that crate tk is asking crate clib to build the C library of tk86.

Section of build specification

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

This section provides necessary information to probe library's headers, include/link paths and C libraries that needs to link against, with or without pkg-config.

Note that "spec" is placed between "clib" and "tk86" in the section name. It is the specification for building tk86, but not asking crate clib to build. As mentioned above, it is build = ["tk86"] which makes clib to build tk86.

Enumerating names of pkg-config file

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

This value tells pkg-config to find tk.pc if tk86.pc does not exist.

Enumerating header files of tk library

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

This value tells crate bindgen that "tk.h" is the header file of tk86 library.

Enumerating dependencies

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

This value specifies tcl86 as the dependency of tk86. The crate clib will probe tcl86 and its dependencies recusively, if any( actually, none in this example).

The metadata of tcl86 is in section [package.metadata.inwelling.clib.spec.tcl86] of examples/tcl/Cargo.toml which will be collected by crate inwelling as well.

Enumerating possible executable file names

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

The value exe = ["wish86", "wish"] tells that the executable file name of tk shell may be "wish86" or "wish". It is optional, only used if pkg-config is missing or failed to probe library. The crate clib will try to locate the executable file and expect the include and link path to be "../include/{some-dir-in-includedir}" and "../lib" respectively. Note that "wish86.exe" and "wish.exe" are not necessary for Windows.

Enumerating possible include paths

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

The value includedir = ["tk8.6", "tk"] tells the possible names of include path under "../include" which is mentioned previously. If none of the path exists, the include path will be expected to be "../include". It is optional, only used if pkg-config is missing or failed to probe library.

Importing extra include paths

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

This value tells crate clib to add include paths of x11 and its "header-dependencies" recusively, if any, to tk's.

The libs section

[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"]

The value tk = [..] enumerates possible library file names that need link against. Note that the key name "tk" is for human readability only.

Once file of some name has been found under link path, the crate clib will stop searching and emit "cargo:rustc-link-lib={the-stripped-name}" to cargo. For example, if "libtk86.so" has been found, the prefix "lib" and suffix ".so" will be stripped and "cargo:rustc-link-lib=tk86" will be emitted.

Global namespace

All generated functions, types and constants are in the root namespace of this crate. You can prefix them with clib::, e.g. clib::Tcl_Init()/clib::Tk_Init(), or use clib::*; and use Tcl_Init()/Tk_Init() directly. On the other hand, traditional "-sys" crates of tcl-sys and tk-sys generate tcl_sys::Tcl_Init() and tk_sys::Tk_Init() respectively.

Caveat

Windows does not support pkg-config well

This crate works well if pkg-config works on the OS. When it is not the case, e.g. on Windows, crate clib will search the installation location with some assumptions, and the search may fail in a larger probability.

License

Under Apache License 2.0 or MIT License, at your will.