added documentation for automatic caching of resources fetched during installs

lib/spack/docs/developer_guide.rst

@@ -80,10 +80,11 @@ with a high level view of Spack's directory structure::
 
      var/
         spack/            <- build & stage directories
-        repos/            <- contains package repositories
+            repos/            <- contains package repositories
-           builtin/       <- pkg repository that comes with Spack
+               builtin/       <- pkg repository that comes with Spack
-              repo.yaml   <- descriptor for the builtin repository
+                  repo.yaml   <- descriptor for the builtin repository
-              packages/   <- directories under here contain packages
+                  packages/   <- directories under here contain packages
+            cache/        <- saves resources downloaded during installs
 
      opt/
         spack/            <- packages are installed here

lib/spack/docs/mirrors.rst

@@ -214,3 +214,21 @@ Adding a mirror really adds a line in ``~/.spack/mirrors.yaml``::
 If you want to change the order in which mirrors are searched for
 packages, you can edit this file and reorder the sections.  Spack will
 search the topmost mirror first and the bottom-most mirror last.
+
+.. _caching:
+
+Local Default Cache
+----------------------------
+
+Spack caches resources that are downloaded as part of installs. The cache is
+a valid spack mirror: it uses the same directory structure and naming scheme
+as other Spack mirrors (so it can be copied anywhere and referenced with a URL
+like other mirrors). The mirror is maintained locally (within the Spack 
+installation directory) at :file:`var/spack/cache/`. It is always enabled (and 
+is always searched first when attempting to retrieve files for an installation) 
+but can be cleared with :ref:`purge <spack-purge>`; the cache directory can also
+be deleted manually without issue. 
+
+Caching includes retrieved tarball archives and source control repositories, but
+only resources with an associated digest or commit ID (e.g. a revision number 
+for SVN) will be cached.

lib/spack/docs/packaging_guide.rst

@@ -703,6 +703,13 @@ Fetching a revision
 Subversion branches are handled as part of the directory structure, so
 you can check out a branch or tag by changing the ``url``.
 
+Automatic caching of files fetched during installation
+------------------------------------------------------
+
+Spack maintains a cache (described :ref:`here <caching>`) which saves files
+retrieved during package installations to avoid re-downloading in the case that
+a package is installed with a different specification (but the same version) or
+reinstalled on account of a change in the hashing scheme.
 
 .. _license:
 
@@ -2618,11 +2625,16 @@ build process will start from scratch.
 
 ``spack purge``
 ~~~~~~~~~~~~~~~~~
-Cleans up all of Spack's temporary files.  Use this to recover disk
+Cleans up all of Spack's temporary and cached files.  This can be used to 
-space if temporary files from interrupted or failed installs
+recover disk space if temporary files from interrupted or failed installs 
-accumulate in the staging area.  This is equivalent to running ``spack
+accumulate in the staging area.  
-clean`` for every package you have fetched or staged.
 
+When called with ``--stage`` or ``--all`` (or without arguments, in which case
+the default is ``--all``) this removes all staged files; this is equivalent to 
+running ``spack clean`` for every package you have fetched or staged.
+
+When called with ``--cache`` or ``--all`` this will clear all resources 
+:ref:`cached <caching>` during installs.
 
 Keeping the stage directory on success
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~