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.

cargo install cargo-c

The rustc version supported is the same as the one supported by the cargo version embedded in the package version, or as set in the rust-version field.

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.

cargo install cargo-c --features=vendored-openssl

Usage

# build the library, create the .h header, create the .pc file
$ cargo cbuild --destdir=${D} --prefix=/usr --libdir=/usr/lib64

# build the library, create the .h header, create the .pc file, build and run the tests
$ cargo ctest

# build the library, create the .h header, create the .pc file and install all of it
$ cargo cinstall --destdir=${D} --prefix=/usr --libdir=/usr/lib64

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:

This is the ideal setup for a project that wants to keep their C-API within the main crate:

• 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" crate-type. Do not specify the 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 do cargo cinstall --prefix=/usr --destdir=/tmp/some-place or something along those lines.

If you plan to keep the bindings as a separate crate and do not need to autogenerate the headers you may just populate Cargo.toml:

• Add a capi feature, since it is used by cargo-c to identify packages that has to be built as C-libraries within a workspace.
• Set the entry in package.metadata.capi.header.generation to false.
• Optionally override the path to the header to a custom one instead of the default one.

Documentation

• Configuration — package.metadata.capi keys
• Plugin directory vs plugin module
• Header generation — cbindgen and cheadergen
• Troubleshooting

Users

• ebur128
• gcode-rs
• gst-plugins-rs
• lewton
• libdovi
• libimagequant
• librsvg
• rav1e
• rustls-ffi
• sled
• pathfinder
• udbserver

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

Availability

Acknowledgements

This software has been partially developed in the scope of the H2020 project SIFIS-Home with GA n. 952652.