Cargo C-ABI helpers
cargo applet to build and install C-ABI compatible dynamic and static libraries.
It produces and installs a correct pkg-config file, a static library and a dynamic library, and a C header to be used by any C (and C-compatible) software.
Installation
cargo-c may be installed from crates.io.
You must have the cargo build requirements satisfied in order to build cargo-c:
git
pkg-config
(on Unix, used to figure out the host-provided headers/libraries)curl
(on Unix)- OpenSSL headers (only for Unix, this is the
libssl-dev
package on deb-based distributions)
You may pass --features=vendored-openssl
if you have problems building openssl-sys using the host-provided OpenSSL.
Usage
# build the library, create the .h header, create the .pc file
# build the library, create the .h header, create the .pc file, build and run the tests
# build the library, create the .h header, create the .pc file and install all of it
For a more in-depth explanation of how cargo-c
works and how to use it for
your crates, read Building Crates so they Look Like C ABI Libraries.
The TL;DR:
- Create a
capi.rs
with the C-API you want to expose and use#[cfg(cargo_c)]
#[cfg(feature="capi")]
to hide it when you build a normal rust library. - Make sure you have a lib target and if you are using a workspace the first member is the crate you want to export, that means that you might have to add a "." member at the start of the list.
Since Rust 1.38, also add "staticlib" to the "lib"Do not specify thecrate-type
.crate-type
, cargo-c will add the correct library target by itself.- You may use the feature
capi
to add C-API-specific optional dependencies.NOTE: It must be always present in
Cargo.toml
- Remember to add a
cbindgen.toml
and fill it with at least the include guard and probably you want to set the language to C (it defaults to C++) - Once you are happy with the result update your documentation to tell the user
to install
cargo-c
and docargo cinstall --prefix=/usr --destdir=/tmp/some-place
or something along those lines.
Advanced
You may override various aspects of cargo-c
via settings in Cargo.toml
under the package.metadata.capi
key
[]
# Configures the minimum required cargo-c version. Trying to run with an
# older version causes an error.
= "0.6.10"
Header Generation
[]
# Used as header file name. By default this is equal to the crate name.
# The name can be with or without the header filename extension `.h`
= "new_name"
# Install the header into a subdirectory with the name of the crate. This
# is enabled by default
= true
# Generate the header file with `cbindgen`, or copy a pre-generated header
# from the `assets` subdirectory. By default a header is generated.
= true
# Can be use to disable header generation completely.
# This can be used when generating dynamic modules instead of an actual library.
= true
pkg-config
File Generation
[]
# Used as the package name in the pkg-config file and defaults to the crate name.
= "libfoo"
# Used as the package description in the pkg-config file and defaults to the crate description.
= "some description"
# Used as the package version in the pkg-config file and defaults to the crate version.
= "1.2.3"
# Used as the Requires field in the pkg-config file, if defined
= "gstreamer-1.0, gstreamer-base-1.0"
# Used as the Requires.private field in the pkg-config file, if defined
= "gobject-2.0, glib-2.0 >= 2.56.0, gmodule-2.0"
Library Generation
[]
# Used as the library name and defaults to the crate name. This might get
# prefixed with `lib` depending on the target platform.
= "new_name"
# Used as library version and defaults to the crate version. How this is used
# depends on the target platform.
= "1.2.3"
# Used to install the library to a subdirectory of `libdir`.
= "gstreamer-1.0"
# Used to disable versioning links when installing the dynamic library
= false
# Add `-Cpanic=abort` to the RUSTFLAGS automatically, it may be useful in case
# something might panic in the crates used by the library.
= "-Cpanic=abort"
Users
Status
- cli
- build command
- install command
- test command
- cargo applet support
- build targets
- pkg-config generation
- header generation (cbindgen integration)
-
staticlib
support -
cdylib
support - Generate version information in the header
- Make it tunable
- Extra Cargo.toml keys
- Better status reporting
Acknowledgements
This software has been partially developed in the scope of the H2020 project SIFIS-Home with GA n. 952652.