Use Package.headers for -I options (#10623)

This restores the use of Package.headers when computing -I options
for building a package that was added in #8136 and reverted in
#10604. #8136 used utility logic that located all header files in
an installation prefix, and calculated the -I options as the
immediate roots containing those header files.

In some cases, for a package containing a directory structure like

  prefix/
    include/
	  ex1.h
	  subdir/
	    ex2.h

dependents may expect to include ex2.h relative to 'include', and
adding 'prefix/include/subdir' as a -I was causing errors,
in particular if ex2.h has the same name as a system header.

This updates header utility logic to by default return the base
"include" directory when it exists, rather than subdirectories.
It also makes it possible for package implementers to override
Package.headers to return the subdirectory when it is required
(for example with libxml2).

var/spack/repos/builtin/packages/libxml2/package.py

@@ -36,6 +36,13 @@ class Libxml2(AutotoolsPackage):
     resource(name='xmlts', url='http://www.w3.org/XML/Test/xmlts20080827.tar.gz',
              sha256='96151685cec997e1f9f3387e3626d61e6284d4d6e66e0e440c209286c03e9cc7')
 
+    @property
+    def headers(self):
+        include_dir = self.spec.prefix.include.libxml2
+        hl = find_all_headers(include_dir)
+        hl.directories = include_dir
+        return hl
+
     def configure_args(self):
         spec = self.spec
 
@@ -51,10 +58,6 @@ def configure_args(self):
 
         return args
 
-    def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
-        spack_env.prepend_path('CPATH', self.prefix.include.libxml2)
-        run_env.prepend_path('CPATH', self.prefix.include.libxml2)
-
     @run_after('install')
     @on_package_attributes(run_tests=True)
     def import_module_test(self):