tests: explain and test dependency flattening routines (#11993)

- Add comments to explain that `install_dependency_symlinks` and `flatten_dependencies` are actually used.
- Add a test that exercises the routines.

lib/spack/spack/package.py

@@ -2361,7 +2361,15 @@ class Package(PackageBase):
 
 
 def install_dependency_symlinks(pkg, spec, prefix):
-    """Execute a dummy install and flatten dependencies"""
+    """
+    Execute a dummy install and flatten dependencies.
+
+    This routine can be used in a ``package.py`` definition by setting
+    ``install = install_dependency_symlinks``.
+
+    This feature comes in handy for creating a common location for the
+    the installation of third-party libraries.
+    """
     flatten_dependencies(spec, prefix)
 
 

lib/spack/spack/test/install.py

@@ -140,6 +140,41 @@ def test_installed_dependency_request_conflicts(
         dependent.concretize()
 
 
+def test_install_dependency_symlinks_pkg(
+        install_mockery, mock_fetch, mutable_mock_packages):
+    """Test dependency flattening/symlinks mock package."""
+    spec = Spec('flatten-deps')
+    spec.concretize()
+    pkg = spec.package
+    pkg.do_install()
+
+    # Ensure dependency directory exists after the installation.
+    dependency_dir = os.path.join(pkg.prefix, 'dependency-install')
+    assert os.path.isdir(dependency_dir)
+
+
+def test_flatten_deps(
+        install_mockery, mock_fetch, mutable_mock_packages):
+    """Explicitly test the flattening code for coverage purposes."""
+    # Unfortunately, executing the 'flatten-deps' spec's installation does
+    # not affect code coverage results, so be explicit here.
+    spec = Spec('dependent-install')
+    spec.concretize()
+    pkg = spec.package
+    pkg.do_install()
+
+    # Demonstrate that the directory does not appear under the spec
+    # prior to the flatten operation.
+    dependency_name = 'dependency-install'
+    assert dependency_name not in os.listdir(pkg.prefix)
+
+    # Flatten the dependencies and ensure the dependency directory is there.
+    spack.package.flatten_dependencies(spec, pkg.prefix)
+
+    dependency_dir = os.path.join(pkg.prefix, dependency_name)
+    assert os.path.isdir(dependency_dir)
+
+
 def test_installed_upstream_external(
         tmpdir_factory, install_mockery, mock_fetch, gen_mock_layout):
     """Check that when a dependency package is recorded as installed in

var/spack/repos/builtin.mock/packages/flatten-deps/package.py

@@ -0,0 +1,19 @@
+# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+from spack import *
+
+
+class FlattenDeps(Package):
+    """Example install that flattens dependencies."""
+
+    homepage = "http://www.example.com"
+    url      = "http://www.example.com/a-1.0.tar.gz"
+
+    version('1.0', '0123456789abcdef0123456789abcdef')
+
+    depends_on('dependency-install')
+
+    install = install_dependency_symlinks