feat: Add docs and features to support library usage

Cargo.toml

@@ -15,12 +15,17 @@ description = "Build, cache, and run binaries scoped in Cargo.toml rather than i
 [[bin]]
 name = "cargo-bin"
 path = "src/main.rs"
+required-features = ["cli"]
+
+[features]
+default = ["cli"]
+cli = ["dep:clap", "dep:owo-colors"]
 
 [dependencies]
 anyhow = "=1.0.40"
 cfg-if = "=1.0.0"
-clap = "=4.3.19"
-owo-colors = "=3.5.0"
+clap = { version = "=4.3.19", optional = true }
+owo-colors = { version = "=3.5.0", optional = true }
 serde = { version = "=1.0.149", features = ["derive"] }
 toml = "=0.5.9"
 toml_edit = "=0.19.14"
@@ -47,6 +52,10 @@ git-cliff = { version = "1.3.1" }
 # Just added for testing
 dustinblackman-hello-world = { version = "0.2.1", git = "https://github.com/dustinblackman/rust-hello-world", bins = ["hello-world-first", "hello-world-second"] }
 
+[package.metadata.docs.rs]
+all-features = false
+features = []
+
 [package.metadata.gha]
 targets = ["aarch64-apple-darwin"]
 

README.md

@@ -34,6 +34,13 @@ cd my/rust/project
 echo ".bin/" >> .gitignore
 ```
 
+You can also use it as a library within your existing logic.
+
+```toml
+[dependencies]
+cargo-run-bin = { version = "1.7.0", default-features = false }
+```
+
 ## Usage
 
 `cargo-run-bin` keeps track of the binaries and their versions from within `Cargo.toml` under the `[package.metadata.bin]`.
@@ -87,6 +94,28 @@ will create aliases for any `cargo-*` crate, allowing you to execute commands su
 When pulling down a new repo, or adding a step to CI, `cargo bin --install` will install or build all binaries that have not been
 cached which are configured in `Cargo.toml`.
 
+### Library
+
+`run-bin` can also be used as a library and paired nicely with your `build.rs` or any other scripts. The following
+example demos having `dprint` configured within `[package.metadata.bin]`, and executing `dprint --help`.
+
+```rust
+use anyhow::Result;
+use cargo_run_bin::{binary, metadata};
+
+fn run_dprint() -> Result<()> {
+    let binary_package = metadata::get_binary_packages()?
+        .iter()
+        .find(|e| e.package == "dprint")
+        .unwrap()
+        .to_owned();
+    let bin_path = binary::install(binary_package)?;
+    binary::run(bin_path, vec!["--help".to_string()])?;
+
+    return Ok(());
+}
+```
+
 ## [License](./LICENSE)
 
 MIT.

src/binary.rs

@@ -14,6 +14,7 @@ use which::which;
 use crate::cargo_config;
 use crate::metadata;
 
+/// INTERNAL: Install binary with cargo install.
 pub fn cargo_install(
     binary_package: metadata::BinaryPackage,
     cache_path: path::PathBuf,
@@ -68,6 +69,7 @@ pub fn cargo_install(
     return Ok(());
 }
 
+/// INTERNAL: Install binary with binstall
 pub fn binstall(binary_package: metadata::BinaryPackage, cache_path: path::PathBuf) -> Result<()> {
     let mut cmd_prefix = process::Command::new("cargo");
 
@@ -103,6 +105,7 @@ pub fn binstall(binary_package: metadata::BinaryPackage, cache_path: path::PathB
     return Ok(());
 }
 
+/// Install the provided binary package if it has not been built already.
 pub fn install(binary_package: metadata::BinaryPackage) -> Result<String> {
     let mut rust_version = "unknown".to_string();
     if let Some(res) = rustc::triple() {
@@ -153,6 +156,8 @@ pub fn install(binary_package: metadata::BinaryPackage) -> Result<String> {
     return Ok(cache_bin_path.to_str().unwrap().to_string());
 }
 
+/// Executes provided binary and arguments, adding shims to PATH so any
+/// other run-bin configured binaries are available.
 pub fn run(bin_path: String, args: Vec<String>) -> Result<()> {
     // Silly hack to make cargo commands parse arguments correctly.
     let mut final_args = args.clone();

src/cargo_config.rs

@@ -8,6 +8,7 @@ use toml_edit::Document;
 
 use crate::metadata;
 
+/// Updates alias' in .cargo/config.toml with all configured cargo extensions.
 pub fn sync_aliases() -> Result<()> {
     let mut toml_str = "".to_string();
     let config_path = metadata::get_project_root()?.join(".cargo/config.toml");
@@ -57,6 +58,7 @@ pub fn sync_aliases() -> Result<()> {
     return Ok(());
 }
 
+/// Verifies in cargo-binstall is available in alias'.
 pub fn binstall_alias_exists() -> Result<bool> {
     let config_path = metadata::get_project_root()?.join(".cargo/config.toml");
     if !config_path.exists() {

src/lib.rs

@@ -1,8 +1,45 @@
+//! Installing tooling globally when working in teams or on CI is a silly
+//! problem to manage. `cargo-run-bin` builds, caches, and executes binaries
+//! from their locked down versions in `Cargo.toml`, and allows your teams to
+//! always be running the same tooling versions.
+//!
+//! For command lines that extend cargo such as `cargo-nextest`, run-bin will
+//! create and manage cargo aliases to allow using cargo extensions without any
+//! changes to your command line scripts! `cargo-run-bin` gets out of your way,
+//! and you'll forget you're even using it!
+//!
+//! ## Usage
+//!
+//! For command line usage, see the [GitHub repo](https://github.com/dustinblackman/cargo-run-bin).
+//!
+//! `run-bin` can also be used as a library and paired nicely with your
+//! `build.rs` or any other scripts. The following example demos having `dprint`
+//! configured within `[package.metadata.bin]`, and executing `dprint --help`.
+//!
+//! ```rust
+//! use anyhow::Result;
+//! use cargo_run_bin::{binary, metadata};
+//!
+//! fn run_dprint() -> Result<()> {
+//!     let binary_package = metadata::get_binary_packages()?
+//!         .iter()
+//!         .find(|e| e.package == "dprint")
+//!         .unwrap()
+//!         .to_owned();
+//!     let bin_path = binary::install(binary_package)?;
+//!     binary::run(bin_path, vec!["--help".to_string()])?;
+//!
+//!     return Ok(());
+//! }
+//! ```
+
 #![deny(clippy::implicit_return)]
 #![allow(clippy::needless_return)]
 
 pub mod binary;
 pub mod cargo_config;
+#[cfg(not(doc))]
+#[cfg(feature = "cli")]
 pub mod cli;
 pub mod metadata;
 pub mod shims;

src/metadata.rs

@@ -92,6 +92,7 @@ fn get_metadata_binaries() -> Result<MetadataBins> {
     return Ok(metadata_res?);
 }
 
+/// Returns all configured binary packages set in Cargo.toml.
 pub fn get_binary_packages() -> Result<Vec<BinaryPackage>> {
     let metadata = get_metadata_binaries()?;
 

src/shims.rs

@@ -58,6 +58,8 @@ cargo bin {binary} %*
     return Ok(());
 }
 
+/// Creates shims in `.bin/shims` for all non cargo extensions configured in
+/// Cargo.toml. This directory is added to PATH For all executes of `cargo bin`.
 pub fn sync() -> Result<()> {
     let bin_dir = metadata::get_project_root()?.join(".bin/.shims");
     if !bin_dir.exists() {