Merge topic 'FindBLAS-LAPACK-docs'

5bf1651452 Find{BLAS,LAPACK}: Revise and extend Intel MKL usage documentation
8585a12bd9 Find{BLAS,LAPACK}: Move enabled language requirement to top of documentation
6a7c055f96 Find{BLAS,LAPACK}: Revise formatting of intro docs
43b581367d Find{BLAS,LAPACK}: Move implementation note from docs to comments
3beac78a13 Find{BLAS,LAPACK}: Revise imported targets documentation layout
6f305cd5fd Find{BLAS,LAPACK}: Factor out vendor documentation

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6218

1 files changed, 161 insertions, 85 deletions

diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake
index dc35f0124a..e04831803d 100644
--- a/Modules/FindBLAS.cmake
+++ b/Modules/FindBLAS.cmake
@@ -8,11 +8,11 @@ FindBLAS
 Find Basic Linear Algebra Subprograms (BLAS) library
 
 This module finds an installed Fortran library that implements the
-BLAS linear-algebra interface (see http://www.netlib.org/blas/).
+`BLAS linear-algebra interface`_.
 
-The approach follows that taken for the ``autoconf`` macro file,
-``acx_blas.m4`` (distributed at
-http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
+At least one of the ``C``, ``CXX``, or ``Fortran`` languages must be enabled.
+
+.. _`BLAS linear-algebra interface`: http://www.netlib.org/blas/
 
 Input Variables
 ^^^^^^^^^^^^^^^
@@ -23,68 +23,8 @@ The following variables may be set to influence this module's behavior:
   if ``ON`` use static linkage
 
 ``BLA_VENDOR``
-  If set, checks only the specified vendor, if not set checks all the
-  possibilities.  List of vendors valid in this module:
-
-  * ``Goto``
-  * ``FlexiBLAS``
-  * ``OpenBLAS``
-  * ``FLAME``
-  * ``ATLAS PhiPACK``
-  * ``CXML``
-  * ``DXML``
-  * ``SunPerf``
-  * ``SCSL``
-  * ``SGIMATH``
-  * ``IBMESSL``
-  * ``Intel10_32`` (intel mkl v10 32 bit, threaded code)
-  * ``Intel10_64lp`` (intel mkl v10+ 64 bit, threaded code, lp64 model)
-  * ``Intel10_64lp_seq`` (intel mkl v10+ 64 bit, sequential code, lp64 model)
-  * ``Intel10_64ilp`` (intel mkl v10+ 64 bit, threaded code, ilp64 model)
-  * ``Intel10_64ilp_seq`` (intel mkl v10+ 64 bit, sequential code, ilp64 model)
-  * ``Intel10_64_dyn`` (intel mkl v10+ 64 bit, single dynamic library)
-  * ``Intel`` (obsolete versions of mkl 32 and 64 bit)
-  * ``ACML``
-  * ``ACML_MP``
-  * ``ACML_GPU``
-  * ``Apple``
-  * ``NAS``
-  * ``Arm``
-  * ``Arm_mp``
-  * ``Arm_ilp64``
-  * ``Arm_ilp64_mp``
-  * ``EML``
-  * ``EML_mt``
-  * ``Fujitsu_SSL2`` (Fujitsu serial blas / lapack)
-  * ``Fujitsu_SSL2BLAMP`` (Fujitsu parallel blas / lapack)
-  * ``NVHPC``
-  * ``Generic``
-
-  .. versionadded:: 3.6
-    ``OpenBLAS`` support.
-
-  .. versionadded:: 3.11
-    ``FLAME`` support.
-
-  .. versionadded:: 3.13
-    Added ILP64 MKL variants (``Intel10_64ilp``, ``Intel10_64ilp_seq``).
-
-  .. versionadded:: 3.17
-    Added single dynamic library MKL variant (``Intel10_64_dyn``).
-
-  .. versionadded:: 3.18
-    Arm Performance Libraries support (``Arm``, ``Arm_mp``, ``Arm_ilp64``,
-    ``Arm_ilp64_mp``).
-
-  .. versionadded:: 3.19
-    ``FlexiBLAS`` support.
-
-  .. versionadded:: 3.20
-    Elbrus Math Library support (``EML``, ``EML_mt``).
-    Fujitsu SSL2 Library support (``Fujitsu_SSL2``, ``Fujitsu_SSL2BLAMP``)
-
-  .. versionadded:: 3.21
-    NVHPC support
+  Set to one of the :ref:`BLAS/LAPACK Vendors` to search for BLAS only
+  from the specified vendor.  If not set, all vendors are considered.
 
 ``BLA_F95``
   if ``ON`` tries to find the BLAS95 interfaces
@@ -98,13 +38,12 @@ The following variables may be set to influence this module's behavior:
 Imported targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.18
-
-This module defines the following :prop_tgt:`IMPORTED` target:
+This module defines the following :prop_tgt:`IMPORTED` targets:
 
 ``BLAS::BLAS``
-  The libraries to use for BLAS, if found.
+  .. versionadded:: 3.18
 
+  The libraries to use for BLAS, if found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -124,31 +63,168 @@ This module defines the following variables:
 ``BLAS95_FOUND``
   library implementing the BLAS95 interface is found
 
-.. note::
+.. _`BLAS/LAPACK Vendors`:
+
+BLAS/LAPACK Vendors
+^^^^^^^^^^^^^^^^^^^
+
+``Generic``
+  Generic reference implementation
+
+``ACML``, ``ACML_MP``, ``ACML_GPU``
+  AMD Core Math Library
+
+``Apple``, ``NAS``
+  Apple BLAS (Accelerate), and Apple NAS (vecLib)
+
+``Arm``, ``Arm_mp``, ``Arm_ilp64``, ``Arm_ilp64_mp``
+  .. versionadded:: 3.18
+
+  Arm Performance Libraries
+
+``ATLAS``
+  Automatically Tuned Linear Algebra Software
+
+``CXML``, ``DXML``
+  Compaq/Digital Extended Math Library
+
+``EML``, ``EML_mt``
+  .. versionadded:: 3.20
+
+  Elbrus Math Library
+
+``FLAME``
+  .. versionadded:: 3.11
+
+  BLIS Framework
+
+``FlexiBLAS``
+  .. versionadded:: 3.19
+
+``Fujitsu_SSL2``, ``Fujitsu_SSL2BLAMP``
+  .. versionadded:: 3.20
+
+  Fujitsu SSL2 serial and parallel blas/lapack
 
-  C, CXX or Fortran must be enabled to detect a BLAS library.
-  C or CXX must be enabled to use Intel Math Kernel Library (MKL).
+``Goto``
+  GotoBLAS
 
-  For example, to use Intel MKL libraries and/or Intel compiler:
+``IBMESSL``
+  IBM Engineering and Scientific Subroutine Library
 
-  .. code-block:: cmake
+``Intel``
+  Intel MKL 32 bit and 64 bit obsolete versions
 
-    set(BLA_VENDOR Intel10_64lp)
-    find_package(BLAS)
+``Intel10_32``
+  Intel MKL v10 32 bit, threaded code
 
-Hints
-^^^^^
+``Intel10_64lp``
+  Intel MKL v10+ 64 bit, threaded code, lp64 model
 
-``MKLROOT``
-  .. versionadded:: 3.15
+``Intel10_64lp_seq``
+  Intel MKL v10+ 64 bit, sequential code, lp64 model
 
-  Set this environment variable to a directory that contains an MKL
-  installation, or add the directory to the dynamic library loader environment
-  variable for your platform (``LIB``, ``DYLD_LIBRARY_PATH`` or
-  ``LD_LIBRARY_PATH``).
+``Intel10_64ilp``
+  .. versionadded:: 3.13
+
+  Intel MKL v10+ 64 bit, threaded code, ilp64 model
+
+``Intel10_64ilp_seq``
+  .. versionadded:: 3.13
+
+  Intel MKL v10+ 64 bit, sequential code, ilp64 model
+
+``Intel10_64_dyn``
+  .. versionadded:: 3.17
+
+  Intel MKL v10+ 64 bit, single dynamic library
+
+``NVHPC``
+  .. versionadded:: 3.21
+
+  NVIDIA HPC SDK
+
+``OpenBLAS``
+  .. versionadded:: 3.6
+
+``PhiPACK``
+  Portable High Performance ANSI C (PHiPAC)
+
+``SCSL``
+  Scientific Computing Software Library
+
+``SGIMATH``
+  SGI Scientific Mathematical Library
+
+``SunPerf``
+  Sun Performance Library
+
+.. _`Intel MKL`:
+
+Intel MKL
+^^^^^^^^^
+
+To use the Intel MKL implementation of BLAS, a project must enable at least
+one of the ``C`` or ``CXX`` languages.  Set ``BLA_VENDOR`` to an Intel MKL
+variant either on the command-line as ``-DBLA_VENDOR=Intel10_64lp`` or in
+project code:
+
+.. code-block:: cmake
+
+  set(BLA_VENDOR Intel10_64lp)
+  find_package(BLAS)
+
+In order to build a project using Intel MKL, and end user must first
+establish an Intel MKL environment:
+
+Intel oneAPI
+  Source the full Intel environment script:
+
+  .. code-block:: shell
+
+    . /opt/intel/oneapi/setvars.sh
+
+  Or, source the MKL component environment script:
+
+  .. code-block:: shell
+
+    . /opt/intel/oneapi/mkl/latest/env/vars.sh
+
+Intel Classic
+  Source the full Intel environment script:
+
+  .. code-block:: shell
+
+    . /opt/intel/bin/compilervars.sh intel64
+
+  Or, source the MKL component environment script:
+
+  .. code-block:: shell
+
+    . /opt/intel/mkl/bin/mklvars.sh intel64
+
+The above environment scripts set the ``MKLROOT`` environment variable
+to the top of the MKL installation.  They also add the location of the
+runtime libraries to the dynamic library loader environment variable for
+your platform (e.g. ``LD_LIBRARY_PATH``).  This is necessary for programs
+linked against MKL to run.
+
+.. note::
+
+  As of Intel oneAPI 2021.2, loading only the MKL component does not
+  make all of its dependencies available.  In particular, the ``iomp5``
+  library must be available separately, or provided by also loading
+  the compiler component environment:
+
+  .. code-block:: shell
+
+    . /opt/intel/oneapi/compiler/latest/env/vars.sh
 
 #]=======================================================================]
 
+# The approach follows that of the ``autoconf`` macro file, ``acx_blas.m4``
+# (distributed at http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
+
 # Check the language being used
 if(NOT (CMAKE_C_COMPILER_LOADED OR CMAKE_CXX_COMPILER_LOADED OR CMAKE_Fortran_COMPILER_LOADED))
   if(BLAS_FIND_REQUIRED)