link_cplusplus/lib.rs
1//! [![github]](https://github.com/dtolnay/link-cplusplus) [![crates-io]](https://crates.io/crates/link-cplusplus) [![docs-rs]](https://docs.rs/link-cplusplus)
2//!
3//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
6//!
7//! <br>
8//!
9//! # `-lstdc++` or `-lc++`
10//!
11//! This crate exists for the purpose of passing `-lstdc++` or `-lc++` to the
12//! linker, while making it possible for an application to make that choice on
13//! behalf of its library dependencies.
14//!
15//! Without this crate, a library would need to:
16//!
17//! - pick one or the other to link, with no way for downstream applications to
18//! override the choice;
19//! - or link neither and require an explicit link flag provided by downstream
20//! applications even if they would be fine with a default choice;
21//!
22//! neither of which are good experiences.
23//!
24//! <br>
25//!
26//! # Options
27//!
28//! An application or library that is fine with either of libstdc++ or libc++
29//! being linked, whichever is the platform's default, should use the following
30//! in Cargo.toml:
31//!
32//! ```toml
33//! [dependencies]
34//! link-cplusplus = "1.0"
35//! ```
36//!
37//! An application that wants a particular one or the other linked should use:
38//!
39//! ```toml
40//! [dependencies]
41//! link-cplusplus = { version = "1.0", features = ["libstdc++"] }
42//!
43//! # or
44//!
45//! link-cplusplus = { version = "1.0", features = ["libc++"] }
46//! ```
47//!
48//! An application that wants to handle its own more complicated logic for link
49//! flags from its build script can make this crate do nothing by using:
50//!
51//! ```toml
52//! [dependencies]
53//! link-cplusplus = { version = "1.0", features = ["nothing"] }
54//! ```
55//!
56//! Lastly, make sure to add an explicit `extern crate` dependency to your crate
57//! root, since the link-cplusplus crate will be otherwise unused and its link
58//! flags dropped.
59//!
60//! ```
61//! // src/lib.rs
62//!
63//! extern crate link_cplusplus;
64//! ```
65
66#![no_std]