Merge branch 'stage-1.0' into release

Author: aradi

.travis.yml

@@ -0,0 +1,46 @@
+os: linux
+dist: focal
+
+# NOTE: Focal offers broken CMake-export file for ScaLAPACK containing a
+# a non-existent path for the library. On those systems, the CMake export file
+# based auto-detection must be disabled by providing the -DSCALAPACK_LIBRARY
+# option.
+
+language: python
+python: 3.7
+
+
+env:
+  - BUILD_SHARED_LIBS=False
+  - BUILD_SHARED_LIBS=True
+
+addons:
+  apt:
+    packages:
+      - cmake
+      - gfortran
+      - libblas-dev
+      - liblapack-dev
+      - libopenmpi-dev
+      - libscalapack-openmpi-dev
+
+install:
+  - pip install fypp
+
+script:
+  - >
+    FC=gfortran
+    cmake -DBUILD_SHARED_LIBS=${BUILD_SHARED_LIBS}
+    -DSCALAPACK_LIBRARY="scalapack-openmpi"
+    -DCMAKE_INSTALL_PREFIX=${PWD}/_install 
+    -B _build .
+    && cmake --build _build -- -j
+    && cmake --install _build
+  - >
+    CMAKE_PREFIX_PATH="${PWD}/_install:${CMAKE_PREFIX_PATH}"
+    ./test/integration/cmake/runtest.sh _build_cmake
+    -DSCALAPACK_LIBRARY="scalapack-openmpi"
+  - >
+    PKG_CONFIG_PATH="${PWD}/_install/lib/pkgconfig:${PKG_CONFIG_PATH}"
+    FC=mpifort
+    ./test/integration/pkgconfig/runtest.sh _build_pkgconfig

CHANGELOG.rst

@@ -0,0 +1,25 @@
+**********
+Change Log
+**********
+
+Notable project changes in various releases.
+
+
+1.0
+===
+
+Added
+-----
+
+* Various improvements in the CMake-build system.
+
+* CMake and PKG-Config export files when ScalapackFx is installed.
+
+
+Changed
+-------
+
+* The Fypp-preprocessor is not shipped with ScalapackFx but is an external
+  requirement.
+  
+* Name convention for processes (master -> lead, slave -> follow).

CMakeLists.txt

@@ -0,0 +1,72 @@
+cmake_minimum_required(VERSION 3.16)
+
+include(CMakePackageConfigHelpers)
+
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake
+  ${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules)
+include(ScalapackFxUtils)
+
+include(${CMAKE_CURRENT_SOURCE_DIR}/config.cmake)
+
+project(ScalapackFx VERSION 1.0 LANGUAGES Fortran)
+
+setup_build_type()
+
+#
+# Prerequisites
+#
+find_package(CustomScalapack REQUIRED QUIET)
+find_package(CustomLapack REQUIRED)
+find_program(FYPP fypp)
+if(NOT FYPP)
+  message(FATAL_ERROR "Preprocessor fypp could not be found")
+endif()
+
+#
+# Build instructions
+#
+include(GNUInstallDirs)
+
+add_subdirectory(lib)
+if(NOT BUILD_EXPORTED_TARGETS_ONLY)
+  add_subdirectory(test)
+endif()
+
+#
+# Installation
+#
+add_library(ScalapackFx INTERFACE)
+target_link_libraries(ScalapackFx INTERFACE scalapackfx)
+install(TARGETS ScalapackFx EXPORT scalapackfx-targets)
+
+install(EXPORT scalapackfx-targets
+  FILE scalapackfx-targets.cmake
+  NAMESPACE ScalapackFx::
+  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/scalapackfx"
+  EXPORT_LINK_INTERFACE_LIBRARIES)
+
+configure_package_config_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/utils/export/scalapackfx-config.cmake.in
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake/scalapackfx-config.cmake
+  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/scalapackfx)
+
+write_basic_package_version_file(
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake/scalapackfx-config-version.cmake
+  VERSION ${PROJECT_VERSION}
+  COMPATIBILITY SameMajorVersion)
+
+install(
+  FILES ${CMAKE_CURRENT_BINARY_DIR}/cmake/scalapackfx-config.cmake
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake/scalapackfx-config-version.cmake
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/scalapackfx)
+
+install(
+  DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/scalapackfx)
+
+get_pkgconfig_params(PKGCONFIG_REQUIRES PKGCONFIG_LIBS PKGCONFIG_LIBS_PRIVATE PKGCONFIG_C_FLAGS)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/utils/export/scalapackfx.pc.in
+  ${CMAKE_CURRENT_BINARY_DIR}/scalapackfx.pc @ONLY)
+install(
+  FILES "${CMAKE_CURRENT_BINARY_DIR}/scalapackfx.pc"
+  DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig")

README.rst

@@ -1,20 +1,117 @@
-SCALAPACKFX - Modern Fortran Interface for SCALAPACK, PBLAS and BLACS
-=====================================================================
-
-The open source library `SCALAPACKFX
-<https://www.bitbucket.org/aradi/scalapackfx>`_ is an effort to provide modern
-Fortran (Fortran 2003) wrappers around routines of the SCALAPACK, PBLAS and
-BLACS libraries to make their use as simple as possible.
-
-A few essential routines (especially those related to diagonalization) are
-already covered. See the documentation or the `online API documentation
-<https://aradi.bitbucket.org/scalapackfx/api/annotated.html>`_ whether the
-routines you need are there. If not, you are cordially invited to extend
-SCALAPACKFX and to share it in order to let others profit from your
-work. SCALAPACKFX is licensed under the **simplified BSD license**.
-
-Information about installation and usage of the library you find in the
-documentation in the source or in the `online documentation
-<https://aradi.bitbucket.org/scalapackfx/>`_. Project status, current source
-code, bugtracker etc. can be found on the `SCALAPACKFX project home page
-<https://www.bitbucket.org/aradi/scalapackfx>`_.
+****************************************************
+ScalapackFx - Modern Fortran Interface for ScaLAPACK
+****************************************************
+
+The open source library `ScalapackFx <https://github.com/dftbplus/scalapackfx>`_
+provides convenient modern Fortran (Fortran 2003) wrappers for the routines of
+the ScaLAPACK library. Currently mostly the routines related to diagonalization
+are covered.
+
+The documentation is included inside the repository, but is also available at
+`dftbplus.github.io <https://dftbplus.github.io/>`_.
+
+
+Installation
+============
+
+Prerequisites
+-------------
+
+* CMake (version >= 3.16)
+
+* Fortran 2003 compatible Fortran compiler
+
+* MPI-library and wrappers for your compiler
+
+* ScaLAPACK and LAPACK libraries
+
+* `Fypp preprocessor <https://github.com/aradi/fypp>`_
+
+
+Building and installing the library
+-----------------------------------
+
+The library can be built and installed with the usual CMake-workflow::
+
+  FC=gfortran cmake -B _build -DCMAKE_INSTALL_PREFIX=$HOME/opt/scalapackfx
+  cmake --build _build
+  cmake --install _build
+
+You can influence the configuration via CMake-variables. A list of those
+variables can be found in `config.cmake <config.cmake>`_. You can either modify
+the values directly there or pass them as command line option at the
+configuration phase, e.g.::
+
+  FC=ifort cmake -B _build \
+    -DSCALAPACK_LIBRARY=mkl_scalapack_lp64;mkl_blacs_intelmpi_lp64 \
+    -DLAPACK_LIBRARY=mkl_intel_lp64;mkl_sequential;mkl_core
+
+When customizing the external libraries as above, each of them will be searched
+for and checked for existence. You can disable these checks by setting the
+``SCALAPACK_DETECTION`` and ``LAPACK_DETECTION`` variables to ``False`` (not
+recommended).
+
+
+Testing
+-------
+
+A few tests (and usage examples) can be found in the `test/` subdirectory. The
+compiled test examples must be invoked from this directory, e.g.::
+
+  cd test
+  mpirun -n 2 ../_build/test/test_det
+
+
+Using the library
+=================
+
+CMake build
+-----------
+
+* Make sure to add the root folder of the installed library to the
+  ``CMAKE_PREFIX_PATH`` environment variable.
+
+* Use ``find_package()`` in `CMakeLists.txt` to locate the library and link
+  ``ScalapackFx::ScalapackFx`` to every target which relies directly on the
+  library ::
+
+    cmake_minimum_required(VERSION 3.16)
+
+    project(TestScalapackFxBuild LANGUAGES Fortran)
+
+    find_package(ScalapackFx REQUIRED)
+
+    add_executable(test_build test_build.f90)
+    target_link_libraries(test_build ScalapackFx::ScalapackFx)
+
+Note: When ScalapackFx is found by CMake, it will try to resolve its own
+dependencies (ScaLAPACK and LAPACK) via the ``find_dependency()`` function. You
+can use your own finders for those dependencies as long as they export the
+targets ``Scalapack::Scalapack`` and ``LAPACK::LAPACK`` with the proper
+configuration as ScalapackFx uses those as link targets through the
+``target_link_libraries()`` function. If those targets do not exists when
+ScalapackFx is being searched for, the custom finders shipped with ScalapackFx
+will be invoked to search for the necessary libraries.
+
+
+Pkg-config build
+----------------
+
+* Make sure to add the `lib/pkgconfig` folder of the installed library to the
+  ``PKG_CONFIG_PATH`` environment variable.
+
+* Query the include and library options needed for the build with the usual
+  ``pkg-config`` commands::
+
+    mpifort $(pkg-config --cflags mpifx) test_mpifxbuild.f90 $(pkg-config --libs mpifx)
+
+  Note, that neither ``-cflags`` or ``--libs`` return any options related to
+  your MPI-framework nor is the MPI-framework specified as dependency in the
+  pkg-config file. Use the MPI-wrapper of your compiler to compile and link your
+  executable or pass the additional include and library options by hand.
+
+
+License
+=======
+
+ScalapackFx is licensed under the `BSD-2-Clause License <LICENSE>`_.

cmake/Modules/CustomLibraryFinder.cmake

@@ -0,0 +1,31 @@
+# Finds customized libraries.
+#
+# The customized list of libraries can contain library names, file names or linker options.
+# Libraries are searched for by the find_library() function, file names are checked on existence and
+# linker options (names starting with "-") are added unchanged.
+#
+# libs [in]: List of libraries to find.
+# libdirs [in]: Directories to look up for the libraries.
+# find_quietly [in]: Whether the libraries should be found quietly.
+# libs_found [out]: Contains the list of the detected libraries with their full path. If any of
+#     the libraries/files could not be found, the corresponding entry is replaced by
+#     "_libpath-NOT_FOUND".
+#
+function(find_custom_libraries libs libdirs find_quietly libs_found)
+
+  set(_libs)
+  foreach(_lib IN LISTS libs)
+    if(_lib MATCHES "^[ ]*-.*"  OR EXISTS "${_lib}")
+      list(APPEND _libs ${_lib})
+    else()
+      find_library(_libpath ${_lib} HINTS ${libdirs})
+      list(APPEND _libs ${_libpath})
+      if(NOT _libpath AND NOT find_quietly)
+        message(WARNING "Could not find library '${_lib}' (path hints '${libdirs}'")
+      endif()
+      unset(_libpath CACHE)
+    endif()
+  endforeach()
+  set(${libs_found} "${_libs}" PARENT_SCOPE)
+
+endfunction()