documentation

src/lib.rs

@@ -16,12 +16,54 @@
 //! please contribute!
 //!
 //! # Examples
-//! - Use in `build.rs`
+//! - Use in `build.rs` with automatic discovery.
 //!
-//!   ```rust
+//!   Path is relative to project root. If your resources are in your project, cargo will automatically detect
+//!   changes and invalidate the cache as needed.
 //!
+//!   ```no_run
+//!   use omnicopy_to_output::copy_to_output;
+//!
+//!   fn main() {
+//!       // Copy everything recursively from the res folder and place into output.
+//!       copy_to_output("res").expect("Could not copy");
+//!   }
+//!   ```
+//!
+//! - Use in `build.rs` with custom target (e.g. if your have different shared libraries for debug).
+//!
+//!   Note, if you used both your builds will fail. Each target directory only exists when that
+//!   build is run. A full example would have conditional logic.
+//!
+//!   ```no_run
+//!   use omnicopy_to_output::copy_to_output_for_build_type;
+//!
+//!   fn main() {
+//!       // Manually specify the profile (i.e. env:PROFILE)
+//!       copy_to_output_for_build_type("res/foo.dll", "release").expect("Could not copy");
+//!       copy_to_output_for_build_type("res/food.dll", "debug").expect("Could not copy");
+//!       
+//!   }
 //!   ```
 //!
+//! - Invalidate Cache for external resources
+//!
+//!   Large resources may not exist in your project. We can still copy those to output, but cargo will
+//!   not detect changes and invalidate the cache. Emitting [cargo:rerun-if-changed](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
+//!   instructions will inform cargo these files exist, but then will change cache invalidation to _only_
+//!   what you specify. We can use the helper [`cargo_rerun_if_project_changed`] to restore the default
+//!   behavior along with the helper [`cargo_rerun_if_changed`] to include the out of project resources.
+//!
+//!   ```no_run
+//!   use omnicopy_to_output::{copy_to_output, cargo_rerun_if_project_changed, cargo_rerun_if_changed};
+//!
+//!   fn main() {
+//!       cargo_rerun_if_project_changed().expect("Could not determine project root");
+//!       let path_to_large_resources = "/path/to/large/resources";
+//!       cargo_rerun_if_changed(path_to_large_resources);
+//!       copy_to_output(path_to_large_resources).expect("Could not copy");
+//!   }
+//!
 //! # Scenario Coverage
 //!
 //! Key motivations for the original fork were supporting workspaces + managed experience for cargo
@@ -45,7 +87,7 @@
 //!
 //! 1. Project root (to support workspaces) is determined using [project_root](https://docs.rs/project-root/latest/project_root/)
 //! 2. From the root, the next path element is always `/target`
-//! 3. Next, is either `/{profile}` if no specific target selector was provided or `/{target}/{profile}` if one is provided
+//! 3. Next is either `/{profile}` if no specific target selector was provided or `/{target}/{profile}` if one is provided
 //!     a. Get `{profile}` from `env:PROFILE`
 //!     b. Get `{target}` from [build_target::target_triple](https://docs.rs/build-target/latest/build_target/fn.target_triple.html)
 //!     c. Determine which scheme is in use by testing if `env:OUT_DIR` contains `target/{target}`
@@ -60,10 +102,16 @@ use project_root::get_project_root;
 use std::env;
 use std::path::Path;
 
+/// Copies files to output recursively
 pub fn copy_to_output(path: &str) -> Result<()> {
     copy_to_output_for_build_type(path, &env::var("PROFILE")?)
 }
 
+/// Copies files to output recursively
+///
+/// # Arguments
+///
+/// * `build_type` - Manually specify the profile (i.e. env:PROFILE). Default is `debug` or `release`.
 pub fn copy_to_output_for_build_type(path: &str, build_type: &str) -> Result<()> {
     let mut out_path = get_project_root()?;
     out_path.push("target");
@@ -90,7 +138,7 @@ pub fn copy_to_output_for_build_type(path: &str, build_type: &str) -> Result<()>
     Ok(())
 }
 
-/// Copies files to output
+/// Copies files to output recursively
 pub fn copy_to_output_by_path(path: &Path) -> Result<()> {
     copy_to_output(path_to_str(path)?)
 }
@@ -100,14 +148,23 @@ fn path_to_str(path: &Path) -> Result<&str> {
         .ok_or(anyhow!("Could not convert path to string"))
 }
 
+/// Copies files to output recursively
+///
+/// # Arguments
+///
+/// * `build_type` - Manually specify the profile (i.e. env:PROFILE). Default is `debug` or `release`.
 pub fn copy_to_output_by_path_for_build_type(path: &Path, build_type: &str) -> Result<()> {
     copy_to_output_for_build_type(path_to_str(path)?, build_type)
 }
 
+/// Emits [cargo:rerun-if-changed](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed).
+/// NOTE: Once any `rerun-if-changed` is emitted, only the files specified are monitored. You can emit multiple times.
 pub fn cargo_rerun_if_changed(path: &str) {
     println!("cargo:rerun-if-changed={}", path)
 }
 
+/// Emits [cargo:rerun-if-changed](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed).
+/// NOTE: Once any `rerun-if-changed` is emitted, only the files specified are monitored. You can emit multiple times.
 pub fn cargo_rerun_if_path_changed(path: &Path) -> Result<()> {
     cargo_rerun_if_changed(
         path.to_str()
@@ -116,6 +173,10 @@ pub fn cargo_rerun_if_path_changed(path: &Path) -> Result<()> {
     Ok(())
 }
 
+/// Restores the default cargo cache invalidation, which is to monitor the project directory. If you emit
+/// [cargo:rerun-if-changed](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
+/// it will only monitor what you provide. In this context, if you're just looking to also monitor external
+/// files in additional to your project (including source code) you can use this to achieve that goal.
 pub fn cargo_rerun_if_project_changed() -> Result<()> {
     cargo_rerun_if_path_changed(&get_project_root()?)
 }

tests/fake_workspace/fake_crate/build.rs

@@ -1,4 +1,4 @@
-use omnicopy_to_output::copy_to_output;
+use omnicopy_to_output::{copy_to_output, copy_to_output_for_build_type};
 use std::fs;
 use std::path::Path;