[oneapi] fix mkl deps, externally installed, and docs (#22607)

2 files changed, 45 insertions, 24 deletions

diff --git a/lib/spack/docs/build_systems/inteloneapipackage.rst b/lib/spack/docs/build_systems/inteloneapipackage.rst
index 036fc738ad..1e535775e2 100644
--- a/lib/spack/docs/build_systems/inteloneapipackage.rst
+++ b/lib/spack/docs/build_systems/inteloneapipackage.rst
@@ -38,21 +38,25 @@ Intel no longer releases new versions of Parallel Studio, which can be
 used in Spack via the :ref:<intelpackage>. All of its components can
 now be found in oneAPI. 
 
-Example
-=======
+Examples
+========
 
-We start with a simple example that will be sufficient for most
-users. Install the oneAPI compilers::
+Building a Package With icx
+---------------------------
+
+In this example, we build patchelf with ``icc`` and ``icx``. The
+compilers are installed with spack.
+
+Install the oneAPI compilers::
 
   spack install intel-oneapi-compilers
 
-Add the oneAPI compilers to the set of compilers that Spack can use::
+Add the compilers to your ``compilers.yaml`` so spack can use them::
 
   spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin/intel64
   spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin
 
-This adds the compilers to your ``compilers.yaml``. Verify that the
-compilers are available::
+Verify that the compilers are available::
 
   spack compiler list
 
@@ -72,9 +76,11 @@ To build with with ``icx``, do ::
 
   spack install patchelf%oneapi
 
-In addition to compilers, oneAPI contains many libraries. The ``hdf5``
-package works with any compatible MPI implementation. To build
-``hdf5`` with Intel oneAPI MPI do::
+Using oneAPI MPI to Satisfy a Virtual Dependence
+------------------------------------------------------
+
+The ``hdf5`` package works with any compatible MPI implementation. To
+build ``hdf5`` with Intel oneAPI MPI do::
 
   spack install hdf5 +mpi ^intel-oneapi-mpi
 
@@ -95,11 +101,23 @@ To use the compilers, add some information about the installation to
   spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin
 
 Adapt the paths above if you did not install the tools in the default
-location. After adding the compilers, using them in Spack will be
-exactly the same as if you had installed the
-``intel-oneapi-compilers`` package.  Another option is to manually add
-the configuration to ``compilers.yaml`` as described in :ref:`Compiler
-configuration <compiler-config>`.
+location. After adding the compilers, using them is the same
+as if you had installed the ``intel-oneapi-compilers`` package.
+Another option is to manually add the configuration to
+``compilers.yaml`` as described in :ref:`Compiler configuration
+<compiler-config>`.
+
+Libraries
+---------
+
+If you want Spack to use MKL that you have installed without Spack in
+the default location, then add the following to
+``~/.spack/packages.yaml``, adjusting the version as appropriate::
+
+  intel-oneapi-mkl:
+    externals:
+    - spec: intel-oneapi-mkl@2021.1.1
+      prefix: /opt/intel/oneapi/
 
 
 Using oneAPI Tools Installed by Spack
diff --git a/lib/spack/spack/build_systems/oneapi.py b/lib/spack/spack/build_systems/oneapi.py
index e1a0c66a7e..dfa1e1da78 100644
--- a/lib/spack/spack/build_systems/oneapi.py
+++ b/lib/spack/spack/build_systems/oneapi.py
@@ -8,13 +8,13 @@
 """
 
 from sys import platform
-from os.path import basename, dirname, isdir, join
+from os.path import basename, dirname, isdir
 
 from spack.package import Package
 from spack.util.environment import EnvironmentModifications
 from spack.util.executable import Executable
 
-from llnl.util.filesystem import find_headers, find_libraries
+from llnl.util.filesystem import find_headers, find_libraries, join_path
 
 
 class IntelOneApiPackage(Package):
@@ -33,6 +33,11 @@ class IntelOneApiPackage(Package):
         """Subdirectory for this component in the install prefix."""
         raise NotImplementedError
 
+    @property
+    def component_path(self):
+        """Path to component <prefix>/<component>/<version>."""
+        return join_path(self.prefix, self.component_dir, str(self.spec.version))
+
     def install(self, spec, prefix, installer_path=None):
         """Shared install method for all oneapi packages."""
 
@@ -53,21 +58,20 @@ class IntelOneApiPackage(Package):
                  '--install-dir', prefix)
 
         # Some installers have a bug and do not return an error code when failing
-        if not isdir(join(prefix, self.component_dir)):
+        if not isdir(join_path(prefix, self.component_dir)):
             raise RuntimeError('install failed')
 
     def setup_run_environment(self, env):
-
         """Adds environment variables to the generated module file.
 
         These environment variables come from running:
 
         .. code-block:: console
 
-           $ source {prefix}/setvars.sh --force
+           $ source {prefix}/{component}/{version}/env/vars.sh
         """
         env.extend(EnvironmentModifications.from_sourcing_file(
-            join(self.prefix, self.component_dir, 'latest/env/vars.sh')))
+            join_path(self.component_path, 'env', 'vars.sh')))
 
 
 class IntelOneApiLibraryPackage(IntelOneApiPackage):
@@ -75,12 +79,11 @@ class IntelOneApiLibraryPackage(IntelOneApiPackage):
 
     @property
     def headers(self):
-        include_path = '%s/%s/latest/include' % (
-            self.prefix, self.component_dir)
+        include_path = join_path(self.component_path, 'include')
         return find_headers('*', include_path, recursive=True)
 
     @property
     def libs(self):
-        lib_path = '%s/%s/latest/lib/intel64' % (self.prefix, self.component_dir)
+        lib_path = join_path(self.component_path, 'lib', 'intel64')
         lib_path = lib_path if isdir(lib_path) else dirname(lib_path)
         return find_libraries('*', root=lib_path, shared=True, recursive=True)