Cargo C-ABI helpers

cargo applet to build and install C-ABI compatibile 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

Since it depends on cargo you may pass --features=cargo/vendored-openssl if you have problems building openssl-sys on your platforms.

cargo install cargo-c --features=cargo/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 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:

• Create a capi.rs with the C-API you want to expose and use #[cfg(cargo_c)] 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.
• 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.

Advanced

You may override various aspects of cargo-c via settings in Cargo.toml under the package.metadata.capi key

[package.metadata.capi]
# Configures the minimum required cargo-c version. Trying to run with an
# older version causes an error.
min_version = "0.6.10"

Header Generation

[package.metadata.capi.header]
# 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`
name = "new_name"
# Install the header into a subdirectory with the name of the crate. This
# is enabled by default
subdirectory = true
# Generate the header file with `cbindgen`, or copy a pre-generated header
# from the `assets` subdirectory. By default a header is generated.
generation = true

pkg-config File Generation

[package.metadata.capi.pkg_config]
# Used as the package name in the pkg-config file and defaults to the crate name.
name = "libfoo"
# Used as the package description in the pkg-config file and defaults to the crate description.
description = "some description"
# Used as the package version in the pkg-config file and defaults to the crate version.
version = "1.2.3"

Library Generation

[package.metadata.capi.library]
# Used as the library name and defaults to the crate name. This might get
# prefixed with `lib` depending on the target platform.
name = "new_name"
# Used as library version and defaults to the crate version. How this is used
# depends on the target platform.
version = "1.2.3"

Users

• gcode-rs
• lewton
• rav1e
• sled
• pathfinder

Status

• cli
  • build command
  • install 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