libc_abi_tools/
lib.rs

1//! Release-specific libc ABI metadata. Currently supports x86_64 Linux glibc.
2//!
3//! Adapted from Zig's libc ABI tools; see NOTICE.md and LICENSES/Zig-MIT.txt.
4//! Collects metadata and emits experimental link-only assembly sources.
5//! It supplies no libc runtime implementation; see the qualified example scope.
6//!
7//! # What it does
8//!
9//! - **ABI metadata** ([`glibc`], [`matrix`]): every versioned symbol that each
10//!   glibc release from 2.17 through 2.44 exports from its eight public libraries
11//!   (`libc`, `libm`, `ld`, ...), read from glibc's own ABI lists. A [`Matrix`]
12//!   answers whether a link against a release can use `name@GLIBC_x.y`.
13//! - **Link-only stubs** ([`stub`], [`elf`], [`libgcc`]): assembly and version
14//!   scripts for shared libraries that define exactly a release's symbols and
15//!   versions, with no code. Linking against them fails on anything newer than
16//!   the release.
17//! - **Providers** ([`provider`]): everything a linker needs to build for one
18//!   release (headers, startup objects, nonshared archives, stubs), prepared and
19//!   cached locally in `source` or `container` mode, and described by a
20//!   descriptor that cargo-libc reads.
21//!
22//! The `libc-abi` binary exposes these as commands (`libc-abi glibc ...`,
23//! `libc-abi libgcc stub`, `libc-abi provider ...`); run `libc-abi --help`.
24//!
25//! # Features
26//!
27//! Both are on by default.
28//!
29//! - **`bundled-glibc-data`** compiles in the GNU C Library's ABI lists from the
30//!   `glibc-abilists` crate (LGPL-2.1-or-later), taken from glibc's signed release
31//!   tags. Without it, the data is read from a directory instead
32//!   ([`glibc::Snapshot::load`], `--data DIR`).
33//! - **`provider-sources`** compiles in the recorded glibc sources of the
34//!   `glibc-provider-sources` crate (LGPL-2.1-or-later, and the Linux UAPI
35//!   headers' licenses), which `source`-mode providers compile with the host's
36//!   GCC. Without it, only `container` mode prepares providers.
37//!
38//! This crate's own code is MIT licensed.
39//!
40//! # Example
41//!
42//! Whether a program linked for glibc 2.17 or 2.28 may import `memfd_create`,
43//! which glibc added in 2.27:
44//!
45//! ```
46//! # #[cfg(feature = "bundled-glibc-data")]
47//! # fn main() -> Result<(), String> {
48//! use libc_abi_tools::glibc::{Kind, Snapshot};
49//! use libc_abi_tools::matrix::{Expectation, Matrix};
50//! use libc_abi_tools::version::Version;
51//!
52//! let v = |text: &str| text.parse::<Version>();
53//! let matrix = Matrix::from_snapshots([
54//!     Snapshot::bundled(v("2.17")?)?,
55//!     Snapshot::bundled(v("2.28")?)?,
56//! ])?;
57//! let memfd = |release| matrix.expect(release, "c", "memfd_create", "2.27".parse().unwrap());
58//! assert_eq!(memfd(v("2.17")?), Expectation::Reject);
59//! assert_eq!(memfd(v("2.28")?), Expectation::Accept(Kind::Function));
60//! // A release outside the matrix is unknown, not rejected.
61//! assert_eq!(memfd(v("2.22")?), Expectation::Unknown);
62//! # Ok(())
63//! # }
64//! # #[cfg(not(feature = "bundled-glibc-data"))]
65//! # fn main() {}
66//! ```
67//!
68//! [`Matrix`]: matrix::Matrix
69#![forbid(unsafe_code)]
70#![warn(missing_docs)]
71
72pub mod elf;
73pub mod glibc;
74pub mod libgcc;
75pub mod matrix;
76pub mod provider;
77mod sha256;
78pub mod stub;
79pub mod version;
libc_abi_tools/lib.rs

libc_abi_tools/
lib.rs
