Merge pull request #2 from LittleBoxOfSunshine/chhenk/cacheinvalidation

Cache tests + helpers + documentation

src/lib.rs

@@ -16,8 +16,53 @@
 //! please contribute!
 //!
 //! # Examples
-//! - Use in `build.rs`
+//! - Use in `build.rs` with automatic discovery.
 //!
+//!   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
 //!
@@ -42,9 +87,9 @@
 //!
 //! 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/0.4.0/build_target/fn.target_triple.html)
+//!     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}`
 //!
 
@@ -57,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");
@@ -87,16 +138,45 @@ 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)?)
 }
 
 fn path_to_str(path: &Path) -> Result<&str> {
     path.to_str()
-        .ok_or(anyhow!("Could not convert file path to string"))
+        .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()
+            .ok_or(anyhow!("Could not convert project root path to string"))?,
+    );
+    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/cargo_cache_tests.rs

@@ -1,3 +1,14 @@
+use crate::common::{
+    build_environment, fake_crate_in_tempdir, get_target_path, validate, TestEnvironment,
+};
+use std::fs;
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::PathBuf;
+use std::time::SystemTime;
+
+pub mod common;
+
 // Verify cache clears occur by:
 //  1. Clone to temp dir and build
 //  2. Edit a resource file
@@ -6,15 +17,69 @@
 
 #[test]
 fn file_updated() {
-    assert_eq!(5, 5);
+    let environment = create_and_build();
+    let test_file = environment.path.join("res").join("test.txt");
+
+    edit_build_validate_updated(environment, test_file);
+}
+
+fn edit_build_validate_updated(environment: TestEnvironment, test_file: PathBuf) {
+    let target_file = get_target_path(&environment, None);
+    let original_modified = get_last_modified(&target_file);
+
+    edit_file(&test_file);
+    build_environment(&environment);
+    validate_updated(target_file, original_modified)
+}
+
+fn create_and_build() -> TestEnvironment {
+    let environment = fake_crate_in_tempdir();
+    build_environment(&environment);
+    validate(&environment, None);
+
+    environment
+}
+
+fn edit_file(path: &PathBuf) {
+    let mut file = OpenOptions::new()
+        .write(true)
+        .append(true)
+        .open(path)
+        .unwrap();
+
+    file.write_all("This causes cache invalidation".as_ref())
+        .unwrap();
 }
 
 #[test]
 fn directory_updated() {
-    assert_eq!(5, 5);
+    let environment = create_and_build();
+    let test_file = environment
+        .path
+        .join("res")
+        .join("nested")
+        .join("test2.txt");
+
+    edit_build_validate_updated(environment, test_file);
 }
 
 #[test]
 fn directory_updated_recuses() {
-    assert_eq!(5, 5);
+    let environment = create_and_build();
+    let test_file = environment
+        .path
+        .join("res")
+        .join("nested")
+        .join("doublenested")
+        .join("test3.txt");
+
+    edit_build_validate_updated(environment, test_file);
+}
+
+fn validate_updated(path: PathBuf, original_modified: SystemTime) {
+    assert!(fs::metadata(path).unwrap().modified().unwrap() > original_modified)
+}
+
+fn get_last_modified(path: &PathBuf) -> SystemTime {
+    fs::metadata(path).unwrap().modified().unwrap()
 }

tests/common.rs

@@ -73,15 +73,7 @@ pub fn build_environment_with_target(environment: &TestEnvironment, target: Stri
 }
 
 pub fn validate(environment: &TestEnvironment, target: Option<String>) {
-    let base_path = environment.path.join("target");
-
-    let base_path = if let Some(target) = target {
-        base_path.join(target)
-    } else {
-        base_path
-    };
-
-    let base_path = base_path.join("debug");
+    let base_path = get_target_path(environment, target);
 
     assert!(base_path.join("empty").exists());
     assert!(base_path.join("nested").exists());
@@ -112,6 +104,18 @@ pub fn validate(environment: &TestEnvironment, target: Option<String>) {
     assert!(base_path.join("test.txt").exists());
 }
 
+pub fn get_target_path(environment: &TestEnvironment, target: Option<String>) -> PathBuf {
+    let base_path = environment.path.join("target");
+
+    let base_path = if let Some(target) = target {
+        base_path.join(target)
+    } else {
+        base_path
+    };
+
+    base_path.join("debug")
+}
+
 // Just makes running the tests on a windows machine easier
 pub fn custom_test_target() -> String {
     if cfg!(target_os = "windows") {

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;