Review update.

+ Add documentation to the new RPATH macro in install_helpers.
+ Remove the usage of `subdir` in `ginkgo_install_library` and the new
  `ginkgo_add_install_rpath` since this is unused.
+ Some minor improvements to other documentations.

Co-authored-by: Yuhsiang Tsai <yhmtsai@gmail.com>
Co-authored-by: Tobias Ribizel <ribizel@kit.edu>

INSTALL.md

@@ -65,8 +65,9 @@ Ginkgo adds the following additional switches to control what is being built:
 *   `-DGINKGO_VERBOSE_LEVEL=integer` sets the verbosity of Ginkgo.
     * `0` disables all output in the main libraries,
     * `1` enables a few important messages related to unexpected behavior (default).
-*   `GINKGO_INSTALL_RPATH` sets the RPATH when installing the Ginkgo libraries.
-    The default is `ON`.
+*   `GINKGO_INSTALL_RPATH` allows setting any RPATH information when installing
+    the Ginkgo libraries. If this is `OFF`, the behavior is the same as if all
+    other RPATH flags are set to `OFF` as well. The default is `ON`.
 *   `GINKGO_INSTALL_RPATH_ORIGIN` adds $ORIGIN (Linux) or @loader_path (MacOS)
     to the installation RPATH. The default is `ON`.
 *   `GINKGO_INSTALL_RPATH_DEPENDENCIES` adds the dependencies to the

cmake/create_test.cmake

@@ -110,9 +110,8 @@ function(ginkgo_create_hip_test test_name)
     set_source_files_properties(${test_name}.hip.cpp PROPERTIES HIP_SOURCE_PROPERTY_FORMAT TRUE)
 
     # NOTE: With how HIP works, passing the flags `HIPCC_OPTIONS` etc. here
-    # creates a redefinition of all flags. This creates some issues with `nvcc`
-    # (particularly the flags in `HIPCC_OPTIONS`), but `clang` is fine with the
-    # redefinitions.
+    # creates a redefinition of all flags. This creates some issues with `nvcc`,
+    # but `clang` seems fine with the redefinitions.
     if (GINKGO_HIP_PLATFORM STREQUAL "nvcc")
         hip_add_executable(${TEST_TARGET_NAME} ${test_name}.hip.cpp
             # If `FindHIP.cmake`, namely `HIP_PARSE_HIPCC_OPTIONS` macro and

cmake/install_helpers.cmake

@@ -8,31 +8,47 @@ set(GINKGO_INSTALL_PKGCONFIG_DIR "${CMAKE_INSTALL_LIBDIR}/pkgconfig")
 set(GINKGO_INSTALL_CONFIG_DIR "${CMAKE_INSTALL_LIBDIR}/cmake/Ginkgo")
 set(GINKGO_INSTALL_MODULE_DIR "${CMAKE_INSTALL_LIBDIR}/cmake/Ginkgo/Modules")
 
-function(ginkgo_add_install_rpath name subdir)
-    if (BUILD_SHARED_LIBS)
-        if (GINKGO_INSTALL_RPATH_ORIGIN)
-            if (APPLE)
-                set(ORIGIN_OR_LOADER_PATH "@loader_path")
-            else()
-                set(ORIGIN_OR_LOADER_PATH "$ORIGIN")
-            endif()
+# This function adds the correct RPATH properties to a Ginkgo target.
+#
+# The behavior depends on three options GINKGO_INSTALL_RPATH[*] variables. It
+# does the following:
+#
+# 1. GINKGO_INSTALL_RPATH : If this flag is not set, no RPATH information is
+#    added.
+# 2. GINKGO_INSTALL_RPATH_ORIGIN : Allows adding the library directory to the
+#    RPATH.
+# 3. GINKGO_INSTALL_RPATH_DEPENDENCIES : Allows adding any extra paths to the
+#    RPATH.
+#
+# @param name  the name of the target
+# @param ARGN  any external dependencies path to be added
+function(ginkgo_add_install_rpath name)
+    if (GINKGO_INSTALL_RPATH_ORIGIN)
+        if (APPLE)
+            set(ORIGIN_OR_LOADER_PATH "@loader_path")
+        else()
+            set(ORIGIN_OR_LOADER_PATH "$ORIGIN")
         endif()
-        if (GINKGO_INSTALL_RPATH_DEPENDENCIES)
-            set(RPATH_DEPENDENCIES "${ARGN}")
-            if  (GINKGO_HAVE_HWLOC AND GINKGO_USE_EXTERNAL_HWLOC)
-                get_filename_component(HWLOC_LIB_PATH ${HWLOC_LIBRARIES} DIRECTORY)
-                list(APPEND RPATH_DEPENDENCIES "${HWLOC_LIBRARIES}")
-            endif()
-        endif()
-        if (GINKGO_INSTALL_RPATH)
-            set_property(TARGET "${name}" PROPERTY INSTALL_RPATH
-                "${ORIGIN_OR_LOADER_PATH}" "${RPATH_DEPENDENCIES}")
+    endif()
+    if (GINKGO_INSTALL_RPATH_DEPENDENCIES)
+        set(RPATH_DEPENDENCIES "${ARGN}")
+        if  (GINKGO_HAVE_HWLOC AND GINKGO_USE_EXTERNAL_HWLOC)
+            get_filename_component(HWLOC_LIB_PATH ${HWLOC_LIBRARIES} DIRECTORY)
+            list(APPEND RPATH_DEPENDENCIES "${HWLOC_LIBRARIES}")
         endif()
     endif()
+    if (GINKGO_INSTALL_RPATH)
+        set_property(TARGET "${name}" PROPERTY INSTALL_RPATH
+            "${ORIGIN_OR_LOADER_PATH}" "${RPATH_DEPENDENCIES}")
+    endif()
 endfunction()
 
-function(ginkgo_install_library name subdir)
-    ginkgo_add_install_rpath("${name}" "${subdir}" "${ARGN}")
+# Handles installation settings for a Ginkgo library.
+#
+# @param name  the name of the Ginkgo library target
+# @param ARGN  this should contain any external dependency's library PATH
+function(ginkgo_install_library name)
+    ginkgo_add_install_rpath("${name}" "${ARGN}")
 
     if (WIN32 OR CYGWIN)
         # dll is considered as runtime

core/CMakeLists.txt

@@ -79,7 +79,7 @@ if (GINKGO_BUILD_HIP AND GINKGO_HIP_PLATFORM MATCHES "hcc")
 endif()
 
 ginkgo_default_includes(ginkgo)
-ginkgo_install_library(ginkgo core "${GKO_RPATH_ADDITIONS}")
+ginkgo_install_library(ginkgo "${GKO_RPATH_ADDITIONS}")
 
 if (GINKGO_CHECK_CIRCULAR_DEPS)
     ginkgo_check_headers(ginkgo)

core/device_hooks/CMakeLists.txt

@@ -5,7 +5,7 @@ if(NOT GINKGO_BUILD_CUDA)
     target_link_libraries(ginkgo_cuda PUBLIC ginkgo_device)
     ginkgo_compile_features(ginkgo_cuda)
     ginkgo_default_includes(ginkgo_cuda)
-    ginkgo_install_library(ginkgo_cuda cuda)
+    ginkgo_install_library(ginkgo_cuda)
 endif()
 
 if (NOT GINKGO_BUILD_DPCPP)
@@ -15,7 +15,7 @@ if (NOT GINKGO_BUILD_DPCPP)
     target_link_libraries(ginkgo_dpcpp PUBLIC ginkgo_device)
     ginkgo_compile_features(ginkgo_dpcpp)
     ginkgo_default_includes(ginkgo_dpcpp)
-    ginkgo_install_library(ginkgo_dpcpp dpcpp)
+    ginkgo_install_library(ginkgo_dpcpp)
 endif()
 
 if(NOT GINKGO_BUILD_HIP)
@@ -25,7 +25,7 @@ if(NOT GINKGO_BUILD_HIP)
     target_link_libraries(ginkgo_hip PUBLIC ginkgo_device)
     ginkgo_compile_features(ginkgo_hip)
     ginkgo_default_includes(ginkgo_hip)
-    ginkgo_install_library(ginkgo_hip hip)
+    ginkgo_install_library(ginkgo_hip)
 endif()
 
 if (NOT GINKGO_BUILD_OMP)
@@ -38,7 +38,7 @@ if (NOT GINKGO_BUILD_OMP)
     target_link_libraries(ginkgo_omp PRIVATE ginkgo_dpcpp)
     target_link_libraries(ginkgo_omp PUBLIC ginkgo_device)
     ginkgo_default_includes(ginkgo_omp)
-    ginkgo_install_library(ginkgo_omp omp)
+    ginkgo_install_library(ginkgo_omp)
 endif()
 
 if (NOT GINKGO_BUILD_REFERENCE)
@@ -48,5 +48,5 @@ if (NOT GINKGO_BUILD_REFERENCE)
     target_link_libraries(ginkgo_reference PUBLIC ginkgo_device)
     ginkgo_compile_features(ginkgo_reference)
     ginkgo_default_includes(ginkgo_reference)
-    ginkgo_install_library(ginkgo_reference reference)
+    ginkgo_install_library(ginkgo_reference)
 endif()

cuda/CMakeLists.txt

@@ -167,7 +167,7 @@ list(GET CUDA_RUNTIME_LIBS 0 CUDA_FIRST_LIB)
 get_filename_component(GKO_CUDA_LIBDIR "${CUDA_FIRST_LIB}" DIRECTORY)
 
 ginkgo_default_includes(ginkgo_cuda)
-ginkgo_install_library(ginkgo_cuda cuda "${GKO_CUDA_LIBDIR}")
+ginkgo_install_library(ginkgo_cuda "${GKO_CUDA_LIBDIR}")
 
 if (GINKGO_CHECK_CIRCULAR_DEPS)
     ginkgo_check_headers(ginkgo_cuda)

devices/CMakeLists.txt

@@ -17,7 +17,7 @@ function(ginkgo_add_library name)
 endfunction()
 
 ginkgo_add_library(ginkgo_device machine_topology.cpp)
-ginkgo_install_library(ginkgo_device devices)
+ginkgo_install_library(ginkgo_device)
 
 add_subdirectory(cuda)
 add_subdirectory(dpcpp)

dpcpp/CMakeLists.txt

@@ -57,7 +57,7 @@ target_compile_features(ginkgo_dpcpp PRIVATE cxx_std_17)
 target_link_libraries(ginkgo_dpcpp PUBLIC ginkgo_device)
 
 ginkgo_default_includes(ginkgo_dpcpp)
-ginkgo_install_library(ginkgo_dpcpp dpcpp)
+ginkgo_install_library(ginkgo_dpcpp)
 
 if (GINKGO_CHECK_CIRCULAR_DEPS)
     ginkgo_check_headers(ginkgo_dpcpp)

hip/CMakeLists.txt

@@ -284,7 +284,7 @@ list(APPEND GKO_HIP_RPATH "${HIPBLAS_PATH}/lib" "${HIPRAND_PATH}/lib"
 
 ginkgo_compile_features(ginkgo_hip)
 ginkgo_default_includes(ginkgo_hip)
-ginkgo_install_library(ginkgo_hip hip "${GKO_HIP_RPATH}")
+ginkgo_install_library(ginkgo_hip "${GKO_HIP_RPATH}")
 
 if (GINKGO_CHECK_CIRCULAR_DEPS)
     ginkgo_check_headers(ginkgo_hip)

omp/CMakeLists.txt

@@ -60,7 +60,7 @@ target_link_libraries(ginkgo_omp PRIVATE ginkgo_dpcpp)
 target_link_libraries(ginkgo_omp PUBLIC ginkgo_device)
 
 ginkgo_default_includes(ginkgo_omp)
-ginkgo_install_library(ginkgo_omp omp)
+ginkgo_install_library(ginkgo_omp)
 
 if (GINKGO_CHECK_CIRCULAR_DEPS)
     ginkgo_check_headers(ginkgo_omp)

reference/CMakeLists.txt

@@ -42,7 +42,7 @@ target_sources(ginkgo_reference
 target_link_libraries(ginkgo_reference PUBLIC ginkgo_device)
 ginkgo_compile_features(ginkgo_reference)
 ginkgo_default_includes(ginkgo_reference)
-ginkgo_install_library(ginkgo_reference reference)
+ginkgo_install_library(ginkgo_reference)
 target_compile_options(ginkgo_reference PRIVATE "${GINKGO_COMPILER_FLAGS}")
 
 if (GINKGO_CHECK_CIRCULAR_DEPS)