From a551e4329ef97f3215591c768f49fd7fc04fdc90 Mon Sep 17 00:00:00 2001
From: Tamara Dahlgren <35777542+tldahlgren@users.noreply.github.com>
Date: Mon, 17 Jun 2019 02:36:22 -0700
Subject: docs: updates for `stage.source_path` (#11702)
---
lib/spack/docs/packaging_guide.rst | 18 +++++++++++++-----
lib/spack/spack/fetch_strategy.py | 22 +++++++++++++++++-----
lib/spack/spack/stage.py | 10 +++++++---
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:
--
cgit v1.2.3-70-g09d2