better doc by wrapping @cond on include mkl spblas, private find_package(MKL) compile options fixes build fail for test-drive

Author: Jared Frazier

CMakeLists.txt

@@ -20,8 +20,9 @@ project(
 # Set paths to Intel oneAPI MKL
 if(${ENABLE_SPBLAS})
     if (${ENABLE_FIND_INTEL_MKL})
-        find_package(MKL CONFIG)
-        get_target_property(MKLINCLUDE MKL::MKL INTERFACE_INCLUDE_DIRECTORIES)
+        #find_package(MKL CONFIG)
+        find_package(MKL REQUIRED)
+        #get_target_property(MKLINCLUDE MKL::MKL INTERFACE_INCLUDE_DIRECTORIES)
     endif()
 
     # manually set MKL vars  
@@ -36,33 +37,6 @@ if(${ENABLE_SPBLAS})
     else()
         message(STATUS "Found MKL")
     endif()
-
-    if(NOT EXISTS "${MKLINCLUDE}/mkl_spblas.mod")
-        set(NO_MKL_SPBLAS_MOD "
-        =======================================================================
-            ${MKLINCLUDE} does not contain mkl_spblas.mod
-            If you installed Intel MKL to a directory 
-            that requires root permissions,
-            (e.g., /opt/intel/oneapi/mkl/latest/)
-            ```
-            # alternatively... you could update secure path in sudo visudo
-            sudo -i
-            echo 'source /opt/intel/oneapi/setvars.sh > /dev/null' >> ~/.bashrc
-            source ~/.bashrc
-            your_mkl_include=/opt/intel/oneapi/mkl/latest/include
-            ifx -c your_mkl_include/mkl_spblas.f90
-            ```
-            otherwise if you installed to a directory
-            that does not require root permissions, it 
-            should be sufficient to call
-            ```
-            cd /your/mkl/include # replace with your local path
-            ifx -c mkl_spblas.f90
-            ```
-        =======================================================================
-        ")
-        message(FATAL_ERROR "${NO_MKL_SPBLAS_MOD}")
-    endif()
 endif()
 
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake")

README.md

@@ -7,17 +7,12 @@ projects.
 Can easily use `pFUnit` or `test-drive` for unit testing.
 
 Make sure you have the [Intel oneAPI HPC Toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit-download.html?packages=hpc-toolkit&hpc-toolkit-os=linux&hpc-toolkit-lin=apt) or [Intel Fortran Essentials](https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit-download.html?packages=fortran-essentials&fortran-essentials-os=linux&fortran-essentials-lin=apt).
-
-Make sure also that in your `${MKLROOT}/include` directory there is a file
-called `mkl_spblas.mod`. The most up to date version of Intel MKL does not 
-ship with `mkl_spblas.mod` by default, so you have to compile it separately
-via `ifx -c /path/to/mkl_spblas.f90`.
 
 Then, you can configure, build, and run tests for the project. 
 
 ```shell 
 # test-drive builds faster than pfunit
-./config/intel_ubuntu_test_drive
+./config/intel_ubuntu_test_drive_fftpack_spblas
 ```
 
 Alternatively, if on a system where you need to specify a different MKL library

cmake/helper.cmake

@@ -8,12 +8,15 @@
 function(link_spblas targ)
     if (MKL_FOUND)
         # https://www.intel.com/content/www/us/en/docs/onemkl/developer-guide-macos/2023-0/cmake-config-for-onemkl.html
-        target_compile_options(
-            ${targ} PUBLIC $<TARGET_PROPERTY:MKL::MKL,INTERFACE_COMPILE_OPTIONS>)
         target_include_directories(
             ${targ} PUBLIC $<TARGET_PROPERTY:MKL::MKL,INTERFACE_INCLUDE_DIRECTORIES>)
         target_link_libraries(
             ${targ} PUBLIC $<LINK_ONLY:MKL::MKL>)
+
+        # NOTE: If these are PUBLIC, it means(?) the unit tests inherit these
+        # options and this leads to an error where `CALL check` is unrecognized...
+        target_compile_options(
+            ${targ} PRIVATE $<TARGET_PROPERTY:MKL::MKL,INTERFACE_COMPILE_OPTIONS>)
     else()
         # Add include directories
         target_include_directories(
@@ -107,7 +110,7 @@ endfunction()
 
 # Links the supplied library
 function(link_library targ lib include_dir)
-    target_link_libraries(${targ} ${lib})
+    target_link_libraries(${targ} PUBLIC ${lib})
     target_include_directories(${targ} PUBLIC $<BUILD_INTERFACE:${include_dir}>)
 endfunction()
 

config/intel_ubuntu_test_drive renamed to config/intel_ubuntu_test_drive_fftpack_spblas

@@ -1,6 +1,8 @@
 #!/usr/bin/bash
 # @brief Baseline configuration assuming standard oneapi installation via apt.
 builddocs=$1
+DEFAULT_FIND_INTEL_MKL="ON"
+FIND_INTEL_MKL="${FIND_INTEL_MKL:-$DEFAULT_FIND_INTEL_MKL}"
 (
 curdir=$(pwd)
 [[ $curdir == *"config"* ]] && echo "must be in root project dir" && exit 1 
@@ -11,15 +13,15 @@ cmake -S . -B build\
     -DENABLE_TEST_DRIVE=ON\
     -DENABLE_FFTPACK=ON\
     -DENABLE_SPBLAS=ON\
-    -DENABLE_FIND_INTEL_MKL=OFF\
+    -DENABLE_FIND_INTEL_MKL=${FIND_INTEL_MKL}\
     -DENABLE_PFUNIT=OFF\
     -DCMAKE_INSTALL_PREFIX=build/installed
 cmake --build build
 cmake --build build --target install
 cd build
 # name from test/CMakeLists.txt build_tests(FIRST_ARG ...)
 ctest -R test_drive_square_tests
-# test/test_spblas
+test/test_spblas
 # build docs
 [[ -n $builddocs ]] && cmake --build . --target doxygen_docs 
 )

src/mo_square.f90

@@ -1,12 +1,11 @@
-!> @file mo_square.f90 
-!! @brief Defines a module of simple mathematical operations.
-
-!! \cond
+! Prevents doxygen from documenting the included module 
+!! @cond
 #ifdef INTEL_SPBLAS
     INCLUDE "mkl_spblas.f90" 
 #endif
-!! \endcond
+!! @endcond
 
+!> Defines a module of simple mathematical operations.
 MODULE mo_square
 
 #ifdef FFTPACK
@@ -22,6 +21,7 @@ MODULE mo_square
     PRIVATE
 
     PUBLIC :: sum_cube_square
+    PUBLIC :: square 
 
 CONTAINS
 
@@ -35,7 +35,6 @@ END FUNCTION square
 
     !> @brief Computes the cube of a real number.
     PURE REAL FUNCTION cube(x) result(r)
-        ! An undocumented function
         REAL, INTENT(in) :: x
         r = x**3
     END FUNCTION cube

test/test_spblas.f90

@@ -16,19 +16,20 @@
 !
 ! In the MKL Cookbook (cookbook_index.htm) many different example problems are
 ! solved... could use that also as a reference.
-include "mkl_spblas.f90" ! TODO: remove this!
+!! @cond
+include "mkl_spblas.f90"
+!! @endcond
 PROGRAM TEST_SPBLAS
-    USE, INTRINSIC :: ISO_C_BINDING, ONLY: C_FLOAT, C_INT, C_LONG, C_DOUBLE
+    USE, INTRINSIC :: ISO_C_BINDING, ONLY: C_FLOAT, C_LONG, C_INT, C_DOUBLE
     USE MKL_SPBLAS
 
     IMPLICIT NONE
 
-    INTEGER(KIND=C_INT), PARAMETER :: rows = 4
-    INTEGER(KIND=C_INT), PARAMETER :: cols = 6
+    INTEGER(KIND=C_LONG), PARAMETER :: rows = 4
+    INTEGER(KIND=C_LONG), PARAMETER :: cols = 6
 
-    INTEGER(KIND=C_INT), PARAMETER :: nnz = 8
+    INTEGER(KIND=C_LONG), PARAMETER :: nnz = 8
 
-    !INTEGER(KIND=C_INT) :: ia(rows+1), ja(nnz)   ! include->segfault,w/o include->type err 
     INTEGER(KIND=C_LONG) :: ia(rows+1), ja(nnz) ! works with include 'mkl_spblas.f90'
     INTEGER :: stat
     REAL(KIND=C_DOUBLE) :: values(nnz), x(6), y(4), y_coo(4), alpha, beta
@@ -38,8 +39,8 @@ PROGRAM TEST_SPBLAS
 
     TYPE(SPARSE_MATRIX_T) :: A_coo
 
-    INTEGER(KIND=C_INT), ALLOCATABLE :: row_indx(:)     
-    INTEGER(KIND=C_INT), ALLOCATABLE :: col_indx(:) 
+    INTEGER(KIND=C_LONG), ALLOCATABLE :: row_indx(:)     
+    INTEGER(KIND=C_LONG), ALLOCATABLE :: col_indx(:) 
 
     ! Matrix example taken from: 
     ! https://en.wikipedia.org/wiki/Sparse_matrix#Compressed_sparse_row_(CSR,_CRS_or_Yale_format)
@@ -62,11 +63,11 @@ PROGRAM TEST_SPBLAS
     descr%type = SPARSE_MATRIX_TYPE_GENERAL
 
     !! create coo
-    !row_indx = [1, 1, 2, 2, 3, 3, 3, 4] 
-    !col_indx = [1, 2, 2, 4, 3, 4, 5, 6]
-    !stat = mkl_sparse_d_create_coo(&
-        !A_coo, SPARSE_INDEX_BASE_ONE, rows, cols, nnz, row_indx, col_indx,&
-        !values) 
+    row_indx = [1, 1, 2, 2, 3, 3, 3, 4] 
+    col_indx = [1, 2, 2, 4, 3, 4, 5, 6]
+    stat = mkl_sparse_d_create_coo(&
+        A_coo, SPARSE_INDEX_BASE_ONE, rows, cols, nnz, row_indx, col_indx,&
+        values) 
 
     ! spmv: 
     x = [1,1,1,1,1,1]
@@ -79,8 +80,8 @@ PROGRAM TEST_SPBLAS
     print *, "expected = ", [30., 70., 180., 80.]
 
     !! spmv coo
-    !stat = mkl_sparse_d_mv(&
-        !SPARSE_OPERATION_NON_TRANSPOSE, alpha, A_coo, descr, x, beta, y_coo)
-    !print *, "result coo  = ", y_coo
+    stat = mkl_sparse_d_mv(&
+        SPARSE_OPERATION_NON_TRANSPOSE, alpha, A_coo, descr, x, beta, y_coo)
+    print *, "result coo  = ", y_coo
 
 END PROGRAM TEST_SPBLAS 

test/test_square_with_test_drive.f90

@@ -1,7 +1,7 @@
 ! Example module that includes mo_square and performs a dummy unit test
 MODULE test_square_with_test_drive
 
-    use mo_square
+    USE mo_square
     USE testdrive, ONLY: new_unittest, unittest_type, error_type, check
     IMPLICIT NONE 
     PRIVATE