battery_pack/
lib.rs

1//! battery-pack: Framework for building and using battery packs.
2//!
3//! Battery packs are curated collections of crates that work well together.
4//! The CLI (`cargo bp`) syncs real dependencies into your Cargo.toml,
5//! and this library provides build-time documentation generation and
6//! drift validation.
7//!
8//! # For Battery Pack Authors
9//!
10//! Your `build.rs` generates documentation:
11//!
12//! ```rust,ignore
13//! fn main() {
14//!     battery_pack::build::generate_docs().unwrap();
15//! }
16//! ```
17//!
18//! Your `lib.rs` includes the generated docs:
19//!
20//! ```rust,ignore
21//! #![doc = include_str!(concat!(env!("OUT_DIR"), "/docs.md"))]
22//! ```
23
24pub use bphelper_manifest::{BatteryPackSpec, CrateSpec, DepKind};
25
26/// Build-time documentation generation.
27///
28/// Use from your battery pack's `build.rs`:
29///
30/// ```rust,ignore
31/// fn main() {
32///     battery_pack::build::generate_docs().unwrap();
33/// }
34/// ```
35///
36/// See the [docgen spec](https://battery-pack-rs.github.io/battery-pack/spec/docgen.html)
37/// for details on templates and helpers.
38pub mod build {
39    pub use bphelper_build::{
40        CrateEntry, DocsContext, Error, FeatureEntry, PackageInfo, build_context, generate_docs,
41        render_docs,
42    };
43}
44
45/// Validate that the calling crate's dependencies match a battery pack's specs.
46///
47/// Call this from your battery pack's `validate()` function, passing
48/// the embedded manifest string. This reads the user's Cargo.toml via
49/// the runtime `CARGO_MANIFEST_DIR` env var (which, in build.rs, points
50/// to the user's crate) and compares against the battery pack specs.
51///
52/// Emits `cargo:warning` messages for any drift. Never fails the build.
53pub fn validate(self_manifest: &str) {
54    let _bp_spec = match bphelper_manifest::parse_battery_pack(self_manifest) {
55        Ok(spec) => spec,
56        Err(e) => {
57            println!("cargo:warning=battery-pack: failed to parse battery pack manifest: {e}");
58            return;
59        }
60    };
61
62    let user_toml_path = match std::env::var("CARGO_MANIFEST_DIR") {
63        Ok(dir) => format!("{dir}/Cargo.toml"),
64        Err(_) => {
65            println!("cargo:warning=battery-pack: CARGO_MANIFEST_DIR not set, skipping validation");
66            return;
67        }
68    };
69
70    // TODO: implement drift detection against user's Cargo.toml
71    // For now, just ensure we rerun when the user's manifest changes.
72    println!("cargo:rerun-if-changed={user_toml_path}");
73}
74
75/// Test utilities for battery pack authors.
76///
77/// In your `src/lib.rs`:
78///
79/// ```rust,ignore
80/// #[cfg(test)]
81/// mod tests {
82///     #[test]
83///     fn validate_templates() {
84///         battery_pack::testing::validate_templates(env!("CARGO_MANIFEST_DIR")).unwrap();
85///     }
86/// }
87/// ```
88pub mod testing {
89    pub use bphelper_cli::validate_templates;
90}
91
92#[cfg(test)]
93mod tests {
94    #[test]
95    fn validate_templates() {
96        battery_pack::testing::validate_templates(env!("CARGO_MANIFEST_DIR")).unwrap();
97    }
98}
battery_pack/lib.rs

battery_pack/
lib.rs
