docs: updates for `stage.source_path` (#11702)

3 files changed, 37 insertions, 13 deletions

diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 204a5a3d0e..b5f1b60cbb 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -541,9 +541,10 @@ Skipping the expand step
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 Spack normally expands archives (e.g. ``*.tar.gz`` and ``*.zip``) automatically
-after downloading them. If you want to skip this step (e.g., for
-self-extracting executables and other custom archive types), you can add
-``expand=False`` to a ``version`` directive.
+into a standard stage source directory (``self.stage.source_path``) after
+downloading them. If you want to skip this step (e.g., for self-extracting
+executables and other custom archive types), you can add ``expand=False`` to a
+``version`` directive.
 
 .. code-block:: python
 
@@ -814,7 +815,8 @@ For some packages, source code is provided in a Version Control System
 (VCS) repository rather than in a tarball.  Spack can fetch packages
 from VCS repositories. Currently, Spack supports fetching with `Git
 <git-fetch_>`_, `Mercurial (hg) <hg-fetch_>`_, `Subversion (svn)
-<svn-fetch_>`_, and `Go <go-fetch_>`_.
+<svn-fetch_>`_, and `Go <go-fetch_>`_.  In all cases, the destination
+is the standard stage source path.
 
 To fetch a package from a source repository, Spack needs to know which
 VCS to use and where to download from. Much like with ``url``, package
@@ -881,6 +883,8 @@ Git fetching supports the following parameters to ``version``:
 
 Only one of ``tag``, ``branch``, or ``commit`` can be used at a time.
 
+The destination directory for the clone is the standard stage source path.
+
 Default branch
   To fetch a repository's default branch:
 
@@ -981,6 +985,7 @@ Mercurial
 
 Fetching with Mercurial works much like `Git <git-fetch>`_, but you
 use the ``hg`` parameter.
+The destination directory is still the standard stage source path.
 
 Default branch
   Add the ``hg`` attribute with no ``revision`` passed to ``version``:
@@ -1019,6 +1024,7 @@ Subversion
 ^^^^^^^^^^
 
 To fetch with subversion, use the ``svn`` and ``revision`` parameters.
+The destination directory will be the standard stage source path.
 
 Fetching the head
   Simply add an ``svn`` parameter to the package:
@@ -1063,7 +1069,9 @@ Go
 Go isn't a VCS, it is a programming language with a builtin command,
 `go get <https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies>`_,
 that fetches packages and their dependencies automatically.
-It can clone a Git repository, or download from another source location.
+The destination directory will be the standard stage source path.
+
+This strategy can clone a Git repository, or download from another source location.
 For example:
 
 .. code-block:: python
diff --git a/lib/spack/spack/fetch_strategy.py b/lib/spack/spack/fetch_strategy.py
index 9ab9af3b7e..3072e3d583 100644
--- a/lib/spack/spack/fetch_strategy.py
+++ b/lib/spack/spack/fetch_strategy.py
@@ -13,7 +13,8 @@ in order to build it.  They need to define the following methods:
         Apply a checksum to the downloaded source code, e.g. for an archive.
         May not do anything if the fetch method was safe to begin with.
     * expand()
-        Expand (e.g., an archive) downloaded file to source.
+        Expand (e.g., an archive) downloaded file to source, with the
+        standard stage source path as the destination directory.
     * reset()
         Restore original state of downloaded code.  Used by clean commands.
         This may just remove the expanded source and re-expand an archive,
@@ -111,7 +112,7 @@ class FetchStrategy(with_metaclass(FSMeta, object)):
         """Checksum the archive fetched by this FetchStrategy."""
 
     def expand(self):
-        """Expand the downloaded archive."""
+        """Expand the downloaded archive into the stage source path."""
 
     def reset(self):
         """Revert to freshly downloaded state.
@@ -172,8 +173,10 @@ class FetchStrategyComposite(object):
 
 
 class URLFetchStrategy(FetchStrategy):
-    """FetchStrategy that pulls source code from a URL for an archive,
-       checks the archive against a checksum,and decompresses the archive.
+    """
+    FetchStrategy that pulls source code from a URL for an archive, check the
+    archive against a checksum, and decompresses the archive.  The destination
+    for the resulting file(s) is the standard stage source path.
     """
     enabled = True
     url_attr = 'url'
@@ -537,7 +540,10 @@ class GoFetchStrategy(VCSFetchStrategy):
        version('name',
                go='github.com/monochromegane/the_platinum_searcher/...')
 
-    Go get does not natively support versions, they can be faked with git
+    Go get does not natively support versions, they can be faked with git.
+
+    The fetched source will be moved to the standard stage sourcepath directory
+    during the expand step.
     """
     enabled = True
     url_attr = 'go'
@@ -614,6 +620,8 @@ class GitFetchStrategy(VCSFetchStrategy):
                       repository's default branch)
         * ``tag``: Particular tag to check out
         * ``commit``: Particular commit hash in the repo
+
+    Repositories are cloned into the standard stage source path directory.
     """
     enabled = True
     url_attr = 'git'
@@ -783,6 +791,8 @@ class SvnFetchStrategy(VCSFetchStrategy):
 
            version('name', svn='http://www.example.com/svn/trunk',
                    revision='1641')
+
+    Repositories are checked out into the standard stage source path directory.
     """
     enabled = True
     url_attr = 'svn'
@@ -877,6 +887,8 @@ class HgFetchStrategy(VCSFetchStrategy):
     discouraged.
 
         * ``revision``: Particular revision, branch, or tag.
+
+    Repositories are cloned into the standard stage source path directory.
     """
     enabled = True
     url_attr = 'hg'
diff --git a/lib/spack/spack/stage.py b/lib/spack/spack/stage.py
index 474fda3538..9e2c8865e4 100644
--- a/lib/spack/spack/stage.py
+++ b/lib/spack/spack/stage.py
@@ -106,7 +106,7 @@ class Stage(object):
         with Stage() as stage:      # Context manager creates and destroys the
                                     # stage directory
             stage.fetch()           # Fetch a source archive into the stage.
-            stage.expand_archive()  # Expand the source archive.
+            stage.expand_archive()  # Expand the archive into source_path.
             <install>               # Build and install the archive.
                                     # (handled by user of Stage)
 
@@ -122,7 +122,7 @@ class Stage(object):
         try:
             stage.create()          # Explicitly create the stage directory.
             stage.fetch()           # Fetch a source archive into the stage.
-            stage.expand_archive()  # Expand the source archive.
+            stage.expand_archive()  # Expand the archive into source_path.
             <install>               # Build and install the archive.
                                     # (handled by user of Stage)
         finally:
@@ -594,7 +594,11 @@ class StageComposite:
 
 
 class DIYStage(object):
-    """Simple class that allows any directory to be a spack stage."""
+    """
+    Simple class that allows any directory to be a spack stage.  Consequently,
+    it does not expect or require that the source path adhere to the standard
+    directory naming convention.
+    """
 
     def __init__(self, path):
         if path is None: