Merge pull request #21 from jfdev001/mkl-config

Mkl config and doxygen

Author: jfdev001

CMakeLists.txt

@@ -4,12 +4,12 @@ option(BUILD_SHARED_LIBS "Build shared libraries" ON)
 option(BUILD_TESTING "Build tests" OFF)
 
 option(ENABLE_SPBLAS "Build with SPBLAS" ON)
+option(ENABLE_FIND_INTEL_MKL "Find intel MKL config" OFF)
 
 option(ENABLE_FFTPACK "Build with fftpack" OFF)
 option(ENABLE_PFUNIT "Build with pFUnit" OFF)
 option(ENABLE_TEST_DRIVE "Build with test-drive" OFF)
 
-
 project(
     HelloSPBLAS 
     VERSION 0.1.0 
@@ -19,24 +19,62 @@ project(
 
 # Set paths to Intel oneAPI MKL
 if(${ENABLE_SPBLAS})
-    set(MKLROOT $ENV{MKLROOT} CACHE PATH "Installation directory of Intel MKL")
-    if (NOT MKLROOT)
-        message(FATAL_ERROR "MKLROOT environment variable is not set.")
+    if (${ENABLE_FIND_INTEL_MKL})
+        find_package(MKL CONFIG)
+        get_target_property(MKLINCLUDE MKL::MKL INTERFACE_INCLUDE_DIRECTORIES)
+    endif()
+   
+    # manually set MKL vars  
+    if (NOT MKL_FOUND)
+        message(STATUS "Did not find MKL, trying to use env vars/user input")
+        set(MKLROOT $ENV{MKLROOT} CACHE PATH "Installation directory of Intel MKL")
+        if (NOT MKLROOT)
+            message(FATAL_ERROR "MKLROOT environment variable is not set.")
+        endif()
+        set(MKLLIB ${MKLROOT}/lib CACHE PATH "Path to Intel MKL Libraries")
+        set(MKLINCLUDE ${MKLROOT}/include/ CACHE PATH "Path to Intel MKL include files")
+    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()
-    set(MKLLIB ${MKLROOT}/lib CACHE PATH "Path to Intel MKL Libraries")
-    set(MKLINCLUDE ${MKLROOT}/include CACHE PATH "Path to Intel MKL include files")
 endif()
 
 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${PROJECT_SOURCE_DIR}/cmake")
 include("${PROJECT_SOURCE_DIR}/cmake/helper.cmake")
 
-# build externals with specified version corresponding to git tag 
+# build dependenciesals with specified version corresponding to git tag 
 include(FetchContent)
-message(STATUS "Build extern")
+message(STATUS "Build dependencies")
 set(fftpack_GIT_TAG main)
 set(pFUnit_GIT_TAG cf37fb694f7c015d3718c1b4f7f3e9a56613067a) # fixes fetch content
 set(test-drive_GIT_TAG main)
-add_subdirectory(extern)
+add_subdirectory(dependencies)
 
 message(STATUS "Build src")
 include(GNUInstallDirs)

README.md

@@ -8,6 +8,11 @@ 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 
@@ -29,9 +34,7 @@ You can build the documentation separately with
 cmake --build build --target doxygen_docs 
 ```
 
-Note that `doc/Doxygen.in` was generated using `doxygen -g doc/Doxygen.in`
-(see [doxygen tutorial](https://www.doxygen.nl/manual/starting.html)) and
-see [Documenting Fotran with Doxygen](https://en.wikibooks.org/wiki/Fortran/Documenting_Fortran) for more details.
+See [Documenting Fotran with Doxygen](https://en.wikibooks.org/wiki/Fortran/Documenting_Fortran) for some more details.
 
 You can also check to see if a downstream project can find/fetch this package.
 

cmake/helper.cmake

@@ -6,35 +6,45 @@
 # modified from fftpack
 
 function(link_spblas targ)
-    # Add include directories
-    target_include_directories(
-        ${targ}
-        PRIVATE ${MKLINCLUDE}
-    )
+    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>)
+    else()
+        # Add include directories
+        target_include_directories(
+            ${targ}
+            PUBLIC ${MKLINCLUDE}
+        )
 
-    # Specify the MKL libraries for linking
-    target_link_libraries(
-        ${targ}
-        PRIVATE
-            # must be static 
-            ${MKLLIB}/libmkl_blas95_ilp64.a
-            
-            # must shared 
-            ${MKLLIB}/libmkl_intel_ilp64.so
-            ${MKLLIB}/libmkl_sequential.so # or libmkl_intel_thread.so
-            ${MKLLIB}/libmkl_core.so
+        # Specify the MKL libraries for linking
+        target_link_libraries(
+            ${targ}
+            PRIVATE
+                # must be static 
+                ${MKLLIB}/libmkl_blas95_ilp64.a
+                
+                # must shared 
+                ${MKLLIB}/libmkl_intel_ilp64.so
+                ${MKLLIB}/libmkl_sequential.so # or libmkl_intel_thread.so
+                ${MKLLIB}/libmkl_core.so
 
-            # standard shared libs 
-            pthread
-            m
-            dl
-    )
+                # standard shared libs 
+                pthread
+                m
+                dl
+        )
 
-    target_compile_options(
-        ${targ}
-        PRIVATE
-            -i8 # required, otherwise segfaults
-    )
+        target_compile_options(
+            ${targ}
+            PRIVATE
+                -i8 # required, otherwise segfaults
+        )
+    endif()
 endfunction()
 
 # Use to include and export headers

cmake/template.pc

@@ -1,5 +1,5 @@
 prefix = @CMAKE_INSTALL_PREFIX@
-libdir = ${prefix}/@CMAKE_INSTALL_FULL_LIBDIR@
+libdir = ${prefix}/@CMAKE_INSTALL_LIBDIR@
 includedir = ${prefix}/@CMAKE_INSTALL_INCLUDEDIR@
 
 Name: @PROJECT_NAME@

config/intel_ubuntu_spblas

@@ -1,5 +1,13 @@
 #!/usr/bin/bash
+# @brief intel_ubunt_spblas [builddocs] 
+#   where buildodcs is any nonempty string to trigger doc build
+builddocs=$1
 [[ -d build-spblas ]] && rm -rf build-spblas 
-cmake -S . -B build-spblas -DCMAKE_Fortran_COMPILER=ifx -DBUILD_TESTING=ON
+cmake -S . -B build-spblas\
+    -DCMAKE_Fortran_COMPILER=ifx\
+    -DBUILD_TESTING=ON\
+    -DENABLE_SPBLAS=ON\
+    -DENABLE_FIND_INTEL_MKL=ON
 cmake --build build-spblas
 ./build-spblas/test/test_spblas 
+[[ -n $builddocs ]] && cmake --build build-spblas --target doxygen_docs 

config/intel_ubuntu_test_drive

@@ -1,12 +1,13 @@
 #!/usr/bin/bash
 # @brief Baseline configuration assuming standard oneapi installation via apt.
+builddocs=$1
 (
 curdir=$(pwd)
 [[ $curdir == *"config"* ]] && echo "must be in root project dir" && exit 1 
 #[[ -d build ]] && rm -rf build
 cmake -S . -B build\
     -DBUILD_TESTING=ON\
-    -DENABLE_SPBLAS=ON\
+    -DENABLE_SPBLAS=OFF\
     -DENABLE_PFUNIT=OFF\
     -DENABLE_TEST_DRIVE=ON\
     -DCMAKE_Fortran_COMPILER=ifx\
@@ -15,8 +16,8 @@ cmake --build build
 cd build
 # name from test/CMakeLists.txt build_tests(FIRST_ARG ...)
 ctest -R test_drive_square_tests
-./build/test/test_spblas
+# test/test_spblas
 # build docs
-#cmake --build . --target doxygen_docs 
+[[ -n $builddocs ]] && cmake --build . --target doxygen_docs 
 )
 

extern/CMakeLists.txt renamed to dependencies/CMakeLists.txt

@@ -0,0 +1,7 @@
+message(STATUS "Downloading pFUnit")
+FetchContent_Declare(
+  PFUNIT
+  GIT_REPOSITORY "https://github.com/Goddard-Fortran-Ecosystem/pFUnit"
+  GIT_TAG ${pFUnit_GIT_TAG}
+)  
+FetchContent_MakeAvailable(PFUNIT)

extern/fftpack/CMakeLists.txt renamed to dependencies/fftpack/CMakeLists.txt

@@ -0,0 +1,14 @@
+message(STATUS "Downloading test-drive")
+FetchContent_Declare(
+    test-drive
+    GIT_REPOSITORY "https://github.com/fortran-lang/test-drive"
+    GIT_TAG ${test-drive_GIT_TAG}
+)
+FetchContent_MakeAvailable(test-drive)
+
+set(test-drive_LIBRARY test-drive)
+set(test-drive_LIBRARY ${test-drive_LIBRARY} PARENT_SCOPE)
+
+set(test-drive_INCLUDE_DIR ${test-drive_BINARY_DIR}/include)
+set(test-drive_INCLUDE_DIR ${test-drive_INCLUDE_DIR} PARENT_SCOPE)
+

dependencies/pFUnit/CMakeLists.txt

@@ -1,11 +1,26 @@
-set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
-set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+set(DOXYGEN_OPTIMIZE_FOR_FORTRAN YES)
+set(DOXYGEN_WARNINGS YES)  # ignored if EXTRACT_ALL YES 
+
+## https://stackoverflow.com/questions/8887810/how-to-get-doxygen-to-produce-call-caller-graphs-for-c-functions
+set(DOXYGEN_HAVE_DOT YES)
+set(DOXYGEN_EXTRACT_ALL YES)
+set(DOXYGEN_EXTRACT_PRIVATE YES)
+set(DOXYGEN_CALL_GRAPH YES)
+set(DOXYGEN_CALLER_GRAPH YES)
+set(DOXYGEN_GENERATE_TREEVIEW YES)
+set(DOXYGEN_RECURSIVE YES)
+
+## https://stackoverflow.com/questions/52312850/no-modules-item-in-doxygen-for-fortran
+#set(DOXYGEN_EXTENSION_MAPPING "f90=Fortran f95=Fortran f03=Fortran f08=Fortran")
+set(DOXYGEN_SOURCE_BROWSER YES)
+# Text version of caller/call graph
+set(DOXYGEN_REFERENCED_BY_RELATION NO) 
+set(DOXYGEN_REFERENCES_RELATION NO)
+
+set(DOXYGEN_ENABLE_PREPROCESSING NO) # https://stackoverflow.com/questions/26043007/make-doxygen-document-the-ifdef-parts-too
 
 doxygen_add_docs(doxygen_docs
     ${PROJECT_SOURCE_DIR}/src
     ${CMAKE_CURRENT_SOURCE_DIR}/mainpage.md
-    CONFIG ${DOXYGEN_IN}
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating API documentation with Doxygen" 
 )