Rename build logs and make names consistent (spack#11806)

Fixes spack#11781

* Rename build log to spack-build-log.txt
* Rename environment variables file to spack-build-env.txt
* The name of the log and env files is now the same during the build
  and after the build completes
* Update packages which referred to the build log/env files
* For packages installed before this commit using older names for the
  build and env files, search for the older names

lib/spack/docs/tutorial_advanced_packaging.rst

@@ -347,7 +347,7 @@ we'll notice that this time the installation won't complete:
        11            options.extend([
 
   See build log for details:
-    /usr/local/var/spack/stage/arpack-ng-3.5.0-bloz7cqirpdxj33pg7uj32zs5likz2un/arpack-ng-3.5.0/spack-build.out
+    /usr/local/var/spack/stage/arpack-ng-3.5.0-bloz7cqirpdxj33pg7uj32zs5likz2un/arpack-ng-3.5.0/spack-build-out.txt
 
 Unlike ``openblas`` which provides a library named ``libopenblas.so``,
 ``netlib-lapack`` provides ``liblapack.so``, so it needs to implement
@@ -459,7 +459,7 @@ Let's look at an example and try to install ``netcdf ^mpich``:
        56                config_args.append('--enable-pnetcdf')
 
   See build log for details:
-    /usr/local/var/spack/stage/netcdf-4.4.1.1-gk2xxhbqijnrdwicawawcll4t3c7dvoj/netcdf-4.4.1.1/spack-build.out
+    /usr/local/var/spack/stage/netcdf-4.4.1.1-gk2xxhbqijnrdwicawawcll4t3c7dvoj/netcdf-4.4.1.1/spack-build-out.txt
 
 We can see from the error that ``netcdf`` needs to know how to link the *high-level interface*
 of ``hdf5``, and thus passes the extra parameter ``hl`` after the request to retrieve it.

lib/spack/docs/tutorial_packaging.rst

@@ -123,7 +123,7 @@ to build this package:
     >> 3    make: *** No targets specified and no makefile found.  Stop.
 
   See build log for details:
-    /home/ubuntu/packaging/spack/var/spack/stage/mpileaks-1.0-sv75n3u5ev6mljwcezisz3slooozbbxu/mpileaks-1.0/spack-build.out
+    /home/ubuntu/packaging/spack/var/spack/stage/mpileaks-1.0-sv75n3u5ev6mljwcezisz3slooozbbxu/mpileaks-1.0/spack-build-out.txt
 
 This obviously didn't work; we need to fill in the package-specific
 information.  Specifically, Spack didn't try to build any of mpileaks'
@@ -256,7 +256,7 @@ Now when we try to install this package a lot more happens:
     >> 3    make: *** No targets specified and no makefile found.  Stop.
 
   See build log for details:
-    /home/ubuntu/packaging/spack/var/spack/stage/mpileaks-1.0-csoikctsalli4cdkkdk377gprkc472rb/mpileaks-1.0/spack-build.out
+    /home/ubuntu/packaging/spack/var/spack/stage/mpileaks-1.0-csoikctsalli4cdkkdk377gprkc472rb/mpileaks-1.0/spack-build-out.txt
 
 Note that this command may take a while to run and produce more output if
 you don't have an MPI already installed or configured in Spack.
@@ -319,14 +319,15 @@ If we re-run we still get errors:
     >> 31    configure: error: unable to locate adept-utils installation
 
   See build log for details:
-    /home/ubuntu/packaging/spack/var/spack/stage/mpileaks-1.0-csoikctsalli4cdkkdk377gprkc472rb/mpileaks-1.0/spack-build.out
+    /home/ubuntu/packaging/spack/var/spack/stage/mpileaks-1.0-csoikctsalli4cdkkdk377gprkc472rb/mpileaks-1.0/spack-build-out.txt
 
 Again, the problem may be obvious.  But let's pretend we're not
 all intelligent developers and use this opportunity spend some
 time debugging.  We have a few options that can tell us about
 what's going wrong:
 
-As per the error message, Spack has given us a ``spack-build.out`` debug log:
+As per the error message, Spack has given us a ``spack-build-out.txt`` debug
+log:
 
 .. code-block:: console
 

lib/spack/spack/build_environment.py

@@ -993,7 +993,7 @@ def long_message(self):
 
         if self.build_log and os.path.exists(self.build_log):
             out.write('See build log for details:\n')
-            out.write('  %s' % self.build_log)
+            out.write('  %s\n' % self.build_log)
 
         return out.getvalue()
 

lib/spack/spack/directory_layout.py

@@ -193,9 +193,7 @@ def __init__(self, root, **kwargs):
         self.metadata_dir        = '.spack'
         self.spec_file_name      = 'spec.yaml'
         self.extension_file_name = 'extensions.yaml'
-        self.build_log_name      = 'build.txt'  # build log.
-        self.build_env_name      = 'build.env'  # build environment
-        self.packages_dir        = 'repos'      # archive of package.py files
+        self.packages_dir        = 'repos'  # archive of package.py files
 
     @property
     def hidden_file_paths(self):
@@ -242,12 +240,6 @@ def disable_upstream_check(self):
     def metadata_path(self, spec):
         return os.path.join(spec.prefix, self.metadata_dir)
 
-    def build_log_path(self, spec):
-        return os.path.join(self.metadata_path(spec), self.build_log_name)
-
-    def build_env_path(self, spec):
-        return os.path.join(self.metadata_path(spec), self.build_env_name)
-
     def build_packages_path(self, spec):
         return os.path.join(self.metadata_path(spec), self.packages_dir)
 

lib/spack/spack/package.py

@@ -63,6 +63,13 @@
 from spack.package_prefs import get_package_dir_permissions, get_package_group
 
 
+# Filename for the Spack build/install log.
+_spack_build_logfile = 'spack-build-out.txt'
+
+# Filename for the Spack build/install environment file.
+_spack_build_envfile = 'spack-build-env.txt'
+
+
 class InstallPhase(object):
     """Manages a single phase of the installation.
 
@@ -432,8 +439,9 @@ class PackageBase(with_metaclass(PackageMeta, PackageViewMixin, object)):
 
     #: List of glob expressions. Each expression must either be
     #: absolute or relative to the package source path.
-    #: Matching artifacts found at the end of the build process will
-    #: be copied in the same directory tree as build.env and build.txt.
+    #: Matching artifacts found at the end of the build process will be
+    #: copied in the same directory tree as _spack_build_logfile and
+    #: _spack_build_envfile.
     archive_files = []
 
     #
@@ -782,11 +790,55 @@ def stage(self, stage):
 
     @property
     def env_path(self):
-        return os.path.join(self.stage.path, 'spack-build.env')
+        """Return the build environment file path associated with staging."""
+        # Backward compatibility: Return the name of an existing log path;
+        # otherwise, return the current install env path name.
+        old_filename = os.path.join(self.stage.path, 'spack-build.env')
+        if os.path.exists(old_filename):
+            return old_filename
+        else:
+            return os.path.join(self.stage.path, _spack_build_envfile)
+
+    @property
+    def install_env_path(self):
+        """
+        Return the build environment file path on successful installation.
+        """
+        install_path = spack.store.layout.metadata_path(self.spec)
+
+        # Backward compatibility: Return the name of an existing log path;
+        # otherwise, return the current install env path name.
+        old_filename = os.path.join(install_path, 'build.env')
+        if os.path.exists(old_filename):
+            return old_filename
+        else:
+            return os.path.join(install_path, _spack_build_envfile)
 
     @property
     def log_path(self):
-        return os.path.join(self.stage.path, 'spack-build.txt')
+        """Return the build log file path associated with staging."""
+        # Backward compatibility: Return the name of an existing log path.
+        for filename in ['spack-build.out', 'spack-build.txt']:
+            old_log = os.path.join(self.stage.path, filename)
+            if os.path.exists(old_log):
+                return old_log
+
+        # Otherwise, return the current log path name.
+        return os.path.join(self.stage.path, _spack_build_logfile)
+
+    @property
+    def install_log_path(self):
+        """Return the build log file path on successful installation."""
+        install_path = spack.store.layout.metadata_path(self.spec)
+
+        # Backward compatibility: Return the name of an existing install log.
+        for filename in ['build.out', 'build.txt']:
+            old_log = os.path.join(install_path, filename)
+            if os.path.exists(old_log):
+                return old_log
+
+        # Otherwise, return the current install log path name.
+        return os.path.join(install_path, _spack_build_logfile)
 
     def _make_fetcher(self):
         # Construct a composite fetcher that always contains at least
@@ -1394,7 +1446,6 @@ def bootstrap_compiler(self, **kwargs):
             )
 
     def do_install(self, **kwargs):
-
         """Called by commands to install a package and its dependencies.
 
         Package implementations should override install() to describe
@@ -1617,6 +1668,9 @@ def build_process():
                 if mode != perms:
                     os.chmod(self.prefix, perms)
 
+                # Ensure the metadata path exists as well
+                mkdirp(spack.store.layout.metadata_path(self.spec), mode=perms)
+
             # Fork a child to do the actual installation
             # we preserve verbosity settings across installs.
             PackageBase._verbose = spack.build_environment.fork(
@@ -1724,24 +1778,24 @@ def _do_install_pop_kwargs(self, kwargs):
                     .format(self.last_phase, self.name))
 
     def log(self):
-        # Copy provenance into the install directory on success
-        log_install_path = spack.store.layout.build_log_path(self.spec)
-        env_install_path = spack.store.layout.build_env_path(self.spec)
+        """Copy provenance into the install directory on success."""
         packages_dir = spack.store.layout.build_packages_path(self.spec)
 
         # Remove first if we're overwriting another build
         # (can happen with spack setup)
         try:
-            # log_install_path and env_install_path are inside this
+            # log and env install paths are inside this
             shutil.rmtree(packages_dir)
         except Exception as e:
             # FIXME : this potentially catches too many things...
             tty.debug(e)
 
         # Archive the whole stdout + stderr for the package
-        install(self.log_path, log_install_path)
+        install(self.log_path, self.install_log_path)
+
         # Archive the environment used for the build
-        install(self.env_path, env_install_path)
+        install(self.env_path, self.install_env_path)
+
         # Finally, archive files that are specific to each package
         with working_dir(self.stage.path):
             errors = StringIO()
@@ -1816,10 +1870,12 @@ def check_paths(path_list, filetype, predicate):
 
     @property
     def build_log_path(self):
-        if self.installed:
-            return spack.store.layout.build_log_path(self.spec)
-        else:
-            return self.log_path
+        """
+        Return the expected (or current) build log file path.  The path points
+        to the staging build file until the software is successfully installed,
+        when it points to the file in the installation directory.
+        """
+        return self.install_log_path if self.installed else self.log_path
 
     @classmethod
     def inject_flags(cls, name, flags):