cargo_libc/lib.rs
1//! cargo-libc: build Rust programs for an older glibc.
2//!
3//! cargo-libc is a Cargo subcommand, `cargo libc`. It builds x86_64 Linux programs on
4//! a current machine for a glibc release you choose, 2.17 through 2.44. It links
5//! against exactly what that release defines, checks the executables' requirements,
6//! and runs tests under a simulation of the target's kernel.
7//!
8//! ```sh
9//! cargo libc build --target x86_64-unknown-linux-gnu.2.17 \
10//! --artifact target/x86_64-unknown-linux-gnu/release/myapp -- --release
11//! ```
12//!
13//! Install it with `cargo install cargo-libc --locked`, and read how to use it in the
14//! [user guide](https://github.com/rustcommons/cargo-libc/blob/main/docs/USER-GUIDE.md)
15//! and the [README](https://github.com/rustcommons/cargo-libc#readme).
16//!
17//! # The library
18//!
19//! This library is the implementation of cargo-libc's five executables, and is not
20//! meant to be used directly. Its public items are their entry points:
21//!
22//! | Executable | Entry point | Role |
23//! | --- | --- | --- |
24//! | `cargo-libc` | [`cli::run`] | The `cargo libc` command |
25//! | `libc-linker` | [`toolchain::run_linker`] | The linker Cargo calls for target units |
26//! | `libc-runner` | [`simulate::run_program`] | Cargo's target runner for `test` and `run` |
27//! | `libc-cc` | [`cc::run`] with [`cc::Language::C`] | The C compiler for the `cc` crate and CMake |
28//! | `libc-cxx` | [`cc::run`] with [`cc::Language::Cxx`] | The C++ compiler: host units only |
29//!
30//! To use provider preparation or ELF scanning from your own code, depend on
31//! [`libc-abi-tools`](https://docs.rs/libc-abi-tools) and
32//! [`linux-abi-scan`](https://docs.rs/linux-abi-scan).
33#![forbid(unsafe_code)]
34#![warn(missing_docs)]
35
36mod cargo_output;
37pub mod cc;
38pub mod cli;
39mod elf;
40mod provider;
41mod report;
42pub mod simulate;
43pub mod toolchain;
44mod version;