From 7152c82ec714fcb2441c8ffc8b5a87445838a7c6 Mon Sep 17 00:00:00 2001
From: Todd Gamblin <tgamblin@llnl.gov>
Date: Mon, 10 Feb 2014 09:48:07 -0800
Subject: Document mirrors and change mirror precedence.

---
 lib/spack/docs/site_configuration.rst | 137 ++++++++++++++++++++++++++++++++++
 lib/spack/spack/package.py            |   3 +-
 lib/spack/spack/stage.py              |   2 +-
 3 files changed, 139 insertions(+), 3 deletions(-)

(limited to 'lib')

diff --git a/lib/spack/docs/site_configuration.rst b/lib/spack/docs/site_configuration.rst
index 2658e0a310..2a42cc3d1a 100644
--- a/lib/spack/docs/site_configuration.rst
+++ b/lib/spack/docs/site_configuration.rst
@@ -49,6 +49,143 @@ in the first directory it finds to which it has write access.  Add
 more elements to the list to indicate where your own site's temporary
 directory is.
 
+.. _mirrors:
+
+Mirrors
+----------------------------
+
+Some sites may not have access to the internet for fetching packages.
+These sites will need a local repository of tarballs from which they
+can get their files.  Spack has support for this with *mirrors*.  A
+mirror is a URL that points to a directory, either on the local
+filesystem or on some server, containing tarballs for all of Spack's
+packages.
+
+Here's an example of a mirror's directory structure::
+
+    mirror/
+        cmake/
+            cmake-2.8.10.2.tar.gz
+        dyninst/
+            DyninstAPI-8.1.1.tgz
+            DyninstAPI-8.1.2.tgz
+        libdwarf/
+            libdwarf-20130126.tar.gz
+            libdwarf-20130207.tar.gz
+            libdwarf-20130729.tar.gz
+        libelf/
+            libelf-0.8.12.tar.gz
+            libelf-0.8.13.tar.gz
+        libunwind/
+            libunwind-1.1.tar.gz
+        mpich/
+            mpich-3.0.4.tar.gz
+        mvapich2/
+        mvapich2-1.9.tgz
+
+The structure is very simple.  There is a top-level directory.  The
+second level directories are named after packages, and the third level
+contains tarballs for each package, named as they were in the
+package's fetch URL.
+
+``spack mirror``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create a mirror using the ``spack mirror`` command, assuming
+you're on a machine where you can access the internet.  ``spack
+mirror`` will iterate through all of Spack's packages and download the
+safe ones into a directory structure like the one above.  Here is what
+it looks like:
+
+.. code-block:: bash
+
+   $ spack mirror mirror-dir
+   ==> No safe (checksummed) versions for package callpath.  Skipping.
+   ==> Trying to fetch from http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz
+   ################################################################          90.2%
+   ==> Added mirror-dir/cmake/cmake-2.8.10.2.tar.gz to mirror
+   ==> Trying to fetch from http://www.dyninst.org/sites/default/files/downloads/dyninst/8.1.2/DyninstAPI-8.1.2.tgz
+   ###########################################################               82.0%
+   ==> Added mirror-dir/dyninst/DyninstAPI-8.1.2.tgz to mirror
+   ==> Trying to fetch from http://www.dyninst.org/sites/default/files/downloads/dyninst/8.1.2/DyninstAPI-8.1.1.tgz
+   ######################################################################## 100.0%
+   ==> Added mirror-dir/dyninst/DyninstAPI-8.1.1.tgz to mirror
+
+   ...
+
+   ==> Trying to fetch from http://www.mr511.de/software/libelf-0.8.12.tar.gz
+   ##############################################################            86.5%
+   ==> Added mirror-dir/libelf/libelf-0.8.12.tar.gz to mirror
+   ==> Trying to fetch from http://download.savannah.gnu.org/releases/libunwind/libunwind-1.1.tar.gz
+   ################################################################          89.3%
+   ==> Added mirror-dir/libunwind/libunwind-1.1.tar.gz to mirror
+   ==> Trying to fetch from http://www.mpich.org/static/downloads/3.0.4/mpich-3.0.4.tar.gz
+   #####################################################################     96.4%
+   ==> Added mirror-dir/mpich/mpich-3.0.4.tar.gz to mirror
+   ==> No safe (checksummed) versions for package mpileaks.  Skipping.
+   ==> Trying to fetch from http://mvapich.cse.ohio-state.edu/download/mvapich2/mv2/mvapich2-1.9.tgz
+   #######################################################################   99.2%
+   ==> Added mirror-dir/mvapich2/mvapich2-1.9.tgz to mirror
+   ==> Created Spack mirror in mirror-dir
+
+Once this is done, you can tar up the ``mirror-dir`` directory and
+copy it over to the machine you want it hosted on.
+
+Normally, ``spack mirror`` downloads all the archives it has checksums
+for.  If you want to only create a mirror for a subset of packages,
+you can do that by supplying a list of package names on the command
+line after ``spack mirror``.
+
+
+Setting up a mirror
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have a mirrror, you need to let spack know about it.  Find
+this section in ``globals.py``:
+
+.. code-block:: python
+
+   #
+   # Places to download tarballs from.  Examples:
+   #
+   # For a local directory:
+   #   mirrors = ['file:///Users/gamblin2/spack-mirror']
+   #
+   # For a website:
+   #   mirrors = ['http://spackports.org/spack-mirror/']
+   #
+   # For no mirrors:
+   #   mirrors = []
+   #
+   mirrors = []
+
+Change the list of mirrors to include the location where you copied
+your directory created by ``spack mirror``.  If it's on a local
+filesystem, you want to use a ``file://`` URL.  If it's on a private
+web server, you will need to use a ``http://`` or ``https://`` URL.
+
+Mirror precedence
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have specified mirrors in ``globals.py``, then Spack will try
+to find an archive in each mirror in the list, in order, before it
+downloads from the URL in a package file.
+
+You can test whether a mirror is working properly by first setting it
+in ``globals.py``, then running ``spack fetch`` to test fetching the
+archive. Example:
+
+.. code-block:: bash
+
+   $ spack fetch dyninst
+   ==> Trying to fetch from file:///Users/gamblin2/mirror-dir/dyninst/DyninstAPI-8.1.2.tgz
+
+   ==> Checksum passed for dyninst
+
+If the mirror setup worked, you should see the mirror URL in the fetch
+output, like the ``file://`` URL above.
+
+
 .. _concretization-policies:
 
 Concretization policies
diff --git a/lib/spack/spack/package.py b/lib/spack/spack/package.py
index e96da1a26a..24c3ffd35b 100644
--- a/lib/spack/spack/package.py
+++ b/lib/spack/spack/package.py
@@ -397,8 +397,7 @@ class Package(object):
             raise ValueError("Can only get a stage for a concrete package.")
 
         if self._stage is None:
-            mirror_path="%s/%s-%s.tar.gz" % (
-                self.name, self.name, self.version)
+            mirror_path = "%s/%s" % (self.name, os.path.basename(self.url))
             self._stage = Stage(
                 self.url, mirror_path=mirror_path, name=str(self.spec))
         return self._stage
diff --git a/lib/spack/spack/stage.py b/lib/spack/spack/stage.py
index a03b58c3a0..9777ca5d5a 100644
--- a/lib/spack/spack/stage.py
+++ b/lib/spack/spack/stage.py
@@ -247,7 +247,7 @@ class Stage(object):
         else:
             urls = [self.url]
             if self.mirror_path:
-                urls += ["%s/%s" % (m, self.mirror_path) for m in spack.mirrors]
+                urls = ["%s/%s" % (m, self.mirror_path) for m in spack.mirrors] + urls
 
             for url in urls:
                 tty.msg("Trying to fetch from %s" % url)
-- 
cgit v1.2.3-70-g09d2