Merged 'purge' command with 'clean' and deleted 'purge' (#4970)

* Merged 'purge' command with 'clean'. Deleted 'purge'. fixes #2942

'spack purge' has been merged with 'spack clean'. Documentation has been
updated accordingly. The 'clean' and 'purge' behavior are not mutually
exclusive, and they log brief information to tty while they go.

* Fixed a wrong reference to spack clean in the docs

* Added tests for 'spack clean'. Updated bash completion.

7 files changed, 131 insertions, 95 deletions

diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst
index 28b258c2e5..1c51db1b96 100644
--- a/lib/spack/docs/config_yaml.rst
+++ b/lib/spack/docs/config_yaml.rst
@@ -126,8 +126,8 @@ When Spack builds a package, it creates a temporary directory within the
 
 After a package is successfully installed, Spack deletes the temporary
 directory it used to build.  Unsuccessful builds are not deleted, but you
-can manually purge them with :ref:`spack purge --stage
-<cmd-spack-purge>`.
+can manually purge them with :ref:`spack clean --stage
+<cmd-spack-clean>`.
 
 .. note::
 
@@ -142,8 +142,8 @@ can manually purge them with :ref:`spack purge --stage
 
 Location to cache downloaded tarballs and repositories.  By default these
 are stored in ``$spack/var/spack/cache``.  These are stored indefinitely
-by default. Can be purged with :ref:`spack purge --downloads
-<cmd-spack-purge>`.
+by default. Can be purged with :ref:`spack clean --downloads
+<cmd-spack-clean>`.
 
 --------------------
 ``misc_cache``
@@ -151,7 +151,7 @@ by default. Can be purged with :ref:`spack purge --downloads
 
 Temporary directory to store long-lived cache files, such as indices of
 packages available in repositories.  Defaults to ``~/.spack/cache``.  Can
-be purged with :ref:`spack purge --misc-cache <cmd-spack-purge>`.
+be purged with :ref:`spack clean --misc-cache <cmd-spack-clean>`.
 
 --------------------
 ``verify_ssl``
diff --git a/lib/spack/docs/mirrors.rst b/lib/spack/docs/mirrors.rst
index c69496066f..8f4eea1f8c 100644
--- a/lib/spack/docs/mirrors.rst
+++ b/lib/spack/docs/mirrors.rst
@@ -237,7 +237,7 @@ 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 <cmd-spack-purge>`; the cache directory can also
+but can be cleared with :ref:`clean <cmd-spack-clean>`; the cache directory can also
 be deleted manually without issue.
 
 Caching includes retrieved tarball archives and source control repositories, but
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index af3f7b408a..7e789bc294 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -3432,24 +3432,12 @@ Does this in one of two ways:
 ``spack clean``
 ^^^^^^^^^^^^^^^
 
-Cleans up temporary files for a particular package, by deleting the
-expanded/checked out source code *and* any downloaded archive.  If
-``fetch``, ``stage``, or ``install`` are run again after this, Spack's
-build process will start from scratch.
-
-.. _cmd-spack-purge:
-
-^^^^^^^^^^^^^^^
-``spack purge``
-^^^^^^^^^^^^^^^
-
 Cleans up all of Spack's temporary and cached files.  This can be used to
 recover disk space if temporary files from interrupted or failed installs
 accumulate in the staging area.
 
 When called with ``--stage`` or without arguments this removes all staged
-files and will be equivalent to running ``spack clean`` for every package
-you have fetched or staged.
+files.
 
 When called with ``--downloads`` this will clear all resources
 :ref:`cached <caching>` during installs.
@@ -3459,6 +3447,11 @@ directory, including cached virtual indices.
 
 To remove all of the above, the command can be called with ``--all``.
 
+When called with positional arguments, cleans up temporary files only
+for a particular package. If ``fetch``, ``stage``, or ``install``
+are run again after this, Spack's build process will start from scratch.
+
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Keeping the stage directory on success
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -3472,7 +3465,7 @@ package has been successfully built and installed.  Use
    $ spack install --keep-stage <spec>
 
 This allows you to inspect the build directory and potentially debug
-the build.  You can use ``purge`` or ``clean`` later to get rid of the
+the build.  You can use ``clean`` later to get rid of the
 unwanted temporary files.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/lib/spack/spack/cmd/clean.py b/lib/spack/spack/cmd/clean.py
index b7812bffc4..634e20b4e4 100644
--- a/lib/spack/spack/cmd/clean.py
+++ b/lib/spack/spack/cmd/clean.py
@@ -29,21 +29,60 @@ import llnl.util.tty as tty
 import spack
 import spack.cmd
 
-description = "remove build stage and source tarball for packages"
+description = "remove temporary build files and/or downloaded archives"
 section = "build"
 level = "long"
 
 
+class AllClean(argparse.Action):
+    """Activates flags -s -d and -m simultaneously"""
+    def __call__(self, parser, namespace, values, option_string=None):
+        parser.parse_args(['-sdm'], namespace=namespace)
+
+
 def setup_parser(subparser):
-    subparser.add_argument('packages', nargs=argparse.REMAINDER,
-                           help="specs of packages to clean")
+    subparser.add_argument(
+        '-s', '--stage', action='store_true',
+        help="remove all temporary build stages (default)")
+    subparser.add_argument(
+        '-d', '--downloads', action='store_true',
+        help="remove cached downloads")
+    subparser.add_argument(
+        '-m', '--misc-cache', action='store_true',
+        help="remove long-lived caches, like the virtual package index")
+    subparser.add_argument(
+        '-a', '--all', action=AllClean, help="equivalent to -sdm", nargs=0
+    )
+    subparser.add_argument(
+        'specs',
+        nargs=argparse.REMAINDER,
+        help="removes the build stages and tarballs for specs"
+    )
 
 
 def clean(parser, args):
-    if not args.packages:
-        tty.die("spack clean requires at least one package spec.")
 
-    specs = spack.cmd.parse_specs(args.packages, concretize=True)
-    for spec in specs:
-        package = spack.repo.get(spec)
-        package.do_clean()
+    # If nothing was set, activate the default
+    if not any([args.specs, args.stage, args.downloads, args.misc_cache]):
+        args.stage = True
+
+    # Then do the cleaning falling through the cases
+    if args.specs:
+        specs = spack.cmd.parse_specs(args.specs, concretize=True)
+        for spec in specs:
+            msg = 'Cleaning build stage [{0}]'
+            tty.msg(msg.format(spec.short_spec))
+            package = spack.repo.get(spec)
+            package.do_clean()
+
+    if args.stage:
+        tty.msg('Removing all temporary build stages')
+        spack.stage.purge()
+
+    if args.downloads:
+        tty.msg('Removing cached downloads')
+        spack.fetch_cache.destroy()
+
+    if args.misc_cache:
+        tty.msg('Removing cached information on repositories')
+        spack.misc_cache.destroy()
diff --git a/lib/spack/spack/cmd/purge.py b/lib/spack/spack/cmd/purge.py
deleted file mode 100644
index ac2aa1c21f..0000000000
--- a/lib/spack/spack/cmd/purge.py
+++ /dev/null
@@ -1,60 +0,0 @@
-##############################################################################
-# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-#
-# This file is part of Spack.
-# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
-# LLNL-CODE-647188
-#
-# For details, see https://github.com/llnl/spack
-# Please also see the NOTICE and LICENSE files for our notice and the LGPL.
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License (as
-# published by the Free Software Foundation) version 2.1, February 1999.
-#
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-# conditions of the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-##############################################################################
-import spack
-import spack.stage as stage
-
-description = "remove temporary build files and/or downloaded archives"
-section = "admin"
-level = "long"
-
-
-def setup_parser(subparser):
-    subparser.add_argument(
-        '-s', '--stage', action='store_true', default=True,
-        help="remove all temporary build stages (default)")
-    subparser.add_argument(
-        '-d', '--downloads', action='store_true',
-        help="remove cached downloads")
-    subparser.add_argument(
-        '-m', '--misc-cache', action='store_true',
-        help="remove long-lived caches, like the virtual package index")
-    subparser.add_argument(
-        '-a', '--all', action='store_true',
-        help="remove all of the above")
-
-
-def purge(parser, args):
-    # Special case: no flags.
-    if not any((args.stage, args.downloads, args.misc_cache, args.all)):
-        stage.purge()
-        return
-
-    # handle other flags with fall through.
-    if args.stage or args.all:
-        stage.purge()
-    if args.downloads or args.all:
-        spack.fetch_cache.destroy()
-    if args.misc_cache or args.all:
-        spack.misc_cache.destroy()
diff --git a/lib/spack/spack/test/cmd/clean.py b/lib/spack/spack/test/cmd/clean.py
new file mode 100644
index 0000000000..a905cd9e1e
--- /dev/null
+++ b/lib/spack/spack/test/cmd/clean.py
@@ -0,0 +1,68 @@
+##############################################################################
+# Copyright (c) 2013-2017, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the NOTICE and LICENSE files for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+import pytest
+import spack
+import spack.main
+import spack.package
+
+clean = spack.main.SpackCommand('clean')
+
+
+@pytest.fixture()
+def mock_calls_for_clean(monkeypatch):
+
+    class Counter(object):
+        def __init__(self):
+            self.call_count = 0
+
+        def __call__(self, *args, **kwargs):
+            self.call_count += 1
+
+    monkeypatch.setattr(spack.package.PackageBase, 'do_clean', Counter())
+    monkeypatch.setattr(spack.stage, 'purge', Counter())
+    monkeypatch.setattr(spack.fetch_cache, 'destroy', Counter(), raising=False)
+    monkeypatch.setattr(spack.misc_cache, 'destroy', Counter())
+
+
+@pytest.mark.usefixtures(
+    'builtin_mock', 'config', 'mock_calls_for_clean'
+)
+@pytest.mark.parametrize('command_line,counters', [
+    ('mpileaks', [1, 0, 0, 0]),
+    ('-s', [0, 1, 0, 0]),
+    ('-sd', [0, 1, 1, 0]),
+    ('-a', [0, 1, 1, 1]),
+])
+def test_function_calls(command_line, counters):
+
+    # Call the command with the supplied command line
+    clean(command_line)
+
+    # Assert that we called the expected functions the correct
+    # number of times
+    assert spack.package.PackageBase.do_clean.call_count == counters[0]
+    assert spack.stage.purge.call_count == counters[1]
+    assert spack.fetch_cache.destroy.call_count == counters[2]
+    assert spack.misc_cache.destroy.call_count == counters[3]
diff --git a/share/spack/spack-completion.bash b/share/spack/spack-completion.bash
index e60d587c18..46070d68cc 100755
--- a/share/spack/spack-completion.bash
+++ b/share/spack/spack-completion.bash
@@ -175,7 +175,8 @@ function _spack_checksum {
 function _spack_clean {
     if $list_options
     then
-        compgen -W "-h --help" -- "$cur"
+        compgen -W "-h --help -s --stage -d --downloads
+                   -m --misc-cache -a --all" -- "$cur"
     else
         compgen -W "$(_all_packages)" -- "$cur"
     fi
@@ -598,11 +599,6 @@ function _spack_providers {
     fi
 }
 
-function _spack_purge {
-    compgen -W "-h --help -s --stage -d --downloads
-                -m --misc-cache -a --all" -- "$cur"
-}
-
 function _spack_python {
     if $list_options
     then