Merge pull request #884 from wischi-chr/customizable-cache-location

Make cache location customizable

Author: pkgw

crates/bundles/src/cache.rs

@@ -19,6 +19,7 @@
 use fs2::FileExt;
 use std::{
     collections::HashMap,
+    env,
     fs::{self, File},
     io::{BufRead, BufReader, Error as IoError, ErrorKind as IoErrorKind, Read, Write},
     path::{Path, PathBuf},
@@ -43,13 +44,26 @@ pub struct Cache {
 impl Cache {
     /// Get a handle to a bundle cache, using default per-user settings.
     ///
+    /// The cache location defaults to the `AppDataType::UserCache`
+    /// provided by `app_dirs2` but can be overwritten using the
+    /// `TECTONIC_CACHE_DIR` environment variable.
+    ///
     /// This method may perform I/O to create the user cache directory, so it is
     /// fallible. (Due to its `app_dirs2` implementation, it would have to be
     /// fallible even if it didn't perform I/O.)
     pub fn get_user_default() -> Result<Self> {
-        Ok(Cache {
-            root: app_dirs::ensure_user_cache_dir("")?,
-        })
+        let env_cache_path = env::var_os("TECTONIC_CACHE_DIR");
+
+        let cache_path = match env_cache_path {
+            Some(env_cache_path) => {
+                let env_cache_path = env_cache_path.into();
+                fs::create_dir_all(&env_cache_path)?;
+                env_cache_path
+            }
+            None => app_dirs::ensure_user_cache_dir("")?,
+        };
+
+        Ok(Cache { root: cache_path })
     }
 
     /// Get a handle to a bundle cache, using a custom cache directory.

docs/src/getting-started/first-document.md

@@ -105,7 +105,7 @@ $ tectonic -X build
 
 If you haven’t run Tectonic on your computer before, this command will take a
 minute or two as it downloads the support files that it needs and generates the
-LaTeX “format file” storing the default macro collection. Tectonic will cache
+LaTeX “format file” storing the default macro collection. Tectonic will [cache](#cache)
 these files and avoid downloading them again. Test it out by running the build
 again:
 
@@ -134,3 +134,18 @@ Tectonic’s “user experience” is substantially different from those engines
 
 We hope that you’ll agree that these changes make for a program that is much
 more pleasant to use than the traditional tools.
+
+
+## Cache
+
+The location of the cache depends on your operating system. You can use the
+[V2 Interface][v2cli-ref] to find the exact cache location on your machine
+or take a look [at the implementation][user-cache-impl].
+
+If you need to change the location of the cache, you can do that by setting
+the environment variable `TECTONIC_CACHE_DIR` to the path of a directory.
+We recommend leaving the cache location at the default unless there is a
+compelling reason to change it.
+
+[v2cli-ref]: ../ref/v2cli.md
+[user-cache-impl]: https://docs.rs/tectonic_io_base/latest/tectonic_io_base/app_dirs/fn.ensure_user_cache_dir.html

tests/cached_itarbundle.rs

@@ -6,13 +6,13 @@ use hyper::rt::Future;
 use hyper::service::service_fn;
 use hyper::{Body, Method, Request, Response, Server, StatusCode};
 use std::collections::HashMap;
-use std::fs;
 use std::io::{self, Write};
 use std::net::SocketAddr;
 use std::ops::Bound;
 use std::path::Path;
 use std::sync::{Arc, Mutex};
 use std::thread;
+use std::{env, fs};
 use tectonic::config::PersistentConfig;
 use tectonic::driver::ProcessingSessionBuilder;
 use tectonic::io::OpenResult;
@@ -459,3 +459,48 @@ fn test_bundle_update() {
         }
     });
 }
+
+#[test]
+fn test_cache_location_redirect() {
+    const CACHE_DIR_KEY: &str = "TECTONIC_CACHE_DIR";
+    let tempdir = tempfile::tempdir().unwrap();
+
+    // In this test we intentionally set the environment variable and don't use the custom cache root parameter,
+    // to test the internal mechanism for a custom cache location based on an environment variable.
+    env::set_var(CACHE_DIR_KEY, tempdir.path().as_os_str());
+
+    let tar_index = {
+        let mut builder = TarIndexBuilder::new();
+        builder.push("plain.tex", b"simple").push(
+            tectonic::digest::DIGEST_NAME,
+            b"0000000000000000000000000000000000000000000000000000000000000000",
+        );
+
+        builder.finish()
+    };
+
+    run_test(Some(tar_index), |_, url| {
+        let mut status = TermcolorStatusBackend::new(ChatterLevel::Minimal);
+        let config = PersistentConfig::default();
+
+        let mut cache = config
+            .make_cached_url_provider(url, false, None, &mut status)
+            .unwrap();
+
+        match cache.input_open_name("plain.tex", &mut status) {
+            OpenResult::Ok(_) => {}
+            _ => panic!("Failed to open plain.tex"),
+        }
+
+        // the filename of the target location is the SHA256 hash of the file content "simple"
+        let expected_file_path = tempdir
+            .path()
+            .join("files")
+            .join("a7")
+            .join("a39b72f29718e653e73503210fbb597057b7a1c77d1fe321a1afcff041d4e1");
+
+        if !expected_file_path.exists() {
+            panic!("Couldn't find the cached file in the expected location.");
+        }
+    });
+}