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 `_, `Mercurial (hg) `_, `Subversion (svn) -`_, and `Go `_. +`_, and `Go `_. 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 `_, 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 `_, 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. # 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. # 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