doc: add example of how to use with rustls 0.22

Also, add documentation about how roots are compiled in and what that
means in practice.

Cargo.toml

@@ -21,6 +21,7 @@ rcgen = "0.11.1"
 reqwest = { version = "0.11", features = ["rustls-tls-manual-roots"] }
 ring = "0.17.0"
 rustls-pemfile = "2.0.0"
+rustls = "0.22"
 serde = { version = "1.0.183", features = ["derive"] }
 tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
 webpki = { package = "rustls-webpki", version = "0.102", features = ["alloc"] }

src/lib.rs

@@ -1,10 +1,23 @@
+//! A compiled-in copy of the root certificates trusted by Mozilla.
 //!
-//! This library is automatically generated from the Mozilla
-//! IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+//! To use this library with rustls 0.22:
 //!
-//! The generation is done deterministically so you can verify it
-//! yourself by inspecting and re-running the generation process.
+//! ```rust
+//! let root_store = rustls::RootCertStore {
+//!   roots: webpki_roots::TLS_SERVER_ROOTS.iter().cloned().collect(),
+//! };
+//! ```
 //!
+//! This library is suitable for use in applications that can always be recompiled and instantly deployed.
+//! For applications that are deployed to end-users and cannot be recompiled, or which need certification
+//! before deployment, consider a library that loads certificates at runtime, like
+//! [rustls-native-certs](https://docs.rs/rustls-native-certs).
+//
+// This library is automatically generated from the Mozilla
+// IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+//
+// The generation is done deterministically so you can verify it
+// yourself by inspecting and re-running the generation process.
 
 #![no_std]
 #![forbid(unsafe_code, unstable_features)]

tests/codegen.rs

@@ -375,13 +375,26 @@ impl From<&str> for TrustBits {
     }
 }
 
-const HEADER: &str = r#"//!
-//! This library is automatically generated from the Mozilla
-//! IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+const HEADER: &str = r#"//! A compiled-in copy of the root certificates trusted by Mozilla.
 //!
-//! The generation is done deterministically so you can verify it
-//! yourself by inspecting and re-running the generation process.
+//! To use this library with rustls 0.22:
 //!
+//! ```rust
+//! let root_store = rustls::RootCertStore {
+//!   roots: webpki_roots::TLS_SERVER_ROOTS.iter().cloned().collect(),
+//! };
+//! ```
+//!
+//! This library is suitable for use in applications that can always be recompiled and instantly deployed.
+//! For applications that are deployed to end-users and cannot be recompiled, or which need certification
+//! before deployment, consider a library that loads certificates at runtime, like
+//! [rustls-native-certs](https://docs.rs/rustls-native-certs).
+//
+// This library is automatically generated from the Mozilla
+// IncludedCACertificateReportPEMCSV report via ccadb.org. Don't edit it.
+//
+// The generation is done deterministically so you can verify it
+// yourself by inspecting and re-running the generation process.
 
 #![no_std]
 #![forbid(unsafe_code, unstable_features)]