c_compat/lib.rs
1//! c-compat
2//!
3//! This crate's aim is to bring a one-stop solution to the problem of compiling/linking C libraries
4//! (and therefore *-sys crates) by using the least amount of friction possible.
5//!
6//! # Practical Setup
7//!
8//! In your *-sys crate's build script, which will be using `bindgen` and `cc`, you can access the
9//! includes folder that `c-compat` exposes via the `DEP_C_COMPAT_METADATA` environmental variable.
10//!
11//!
12//! ```no_run
13//! let c_compat_includes = std::env::var("DEP_C_COMPAT_METADATA").expect("DEP_C_COMPAT_METADATA not set");
14//! let c_compat_includes = c_compat_includes.strip_prefix("include=").unwrap();
15//! ```
16//!
17//! You can then make sure that bindgen discards any system includes (which vary across versions,
18//! might not be available, or simply risk to not be architecture independent) and use the
19//! `c-compat` includes as a substitute:
20//!
21//! ```no_run
22//! let bindings = bindgen::Builder::default()
23//! .clang_arg(&format!("-I{c_compat_includes}"))
24//! .clang_arg("-nostdinc")
25//! .clang_arg("-nobuiltininc")
26//! ...
27//! ```
28//!
29//! For `cc` just make sure the headers are available and we also are not using any standard
30//! included headers:
31//!
32//! ```no_run
33//! let mut cc_build = cc::Build::new();
34//! cc_build
35//! .include(&c_compat_includes)
36//! .flag("-nostdinc")
37//! ...
38//! ```
39//!
40//! Then in your *-sys crate you can import the symbols so that they are visible by the linker
41//!
42//! ```no_run
43//! // Make sure we automatically make the necessary symbols available
44//! use c_compat as _;
45//! ```
46//!
47//! and that's it! As long as all the `c-compat` includes cover the needs of your *-sys crate, you
48//! should be in a position where you are leveraging the power of `clang` to cross-compile a C
49//! library with Rust without needing any extra sysroots, compilers, etc...
50#![no_std]
51
52pub mod math;
53pub mod stdlib;