[cmake] Allow users to link against onemath_<domain>_<backend> targets

docs/using_onemath_with_cmake.rst

@@ -6,7 +6,7 @@ Using oneMath in your project with CMake
 The CMake build tool can help you use oneMath in your own project. Instead of
 manually linking and including directories, you can use the CMake targets
 exported by the oneMath project. You can use oneMath in one of two forms, with
-the target names depending on the approach taken: 
+the target names depending on the approach taken:
 
 * you can use a previously installed copy, either from a binary distribution or
   built from source. This can be imported using CMake's ``find_package``
@@ -33,10 +33,11 @@ For example:
     find_package(oneMath REQUIRED)
     target_link_libraries(myTarget PRIVATE ONEMATH::onemath)
 
-Different targets can be used depending on the requirements of oneMath. 
-To link against the entire library, the ``ONEMATH::onemath`` target should be used.
-For specific domains, ``ONEMATH::onemath_<domain>`` should be used.
-And for specific backends, ``ONEMATH::onemath_<domain>_<backend>`` should be used.
+Different targets can be used depending on the requirements of oneMath.
+To link against the entire library with run-time dispatching, the
+``ONEMATH::onemath`` target should be used.
+For specific backends with compile-time dispatching,
+``ONEMATH::onemath_<domain>_<backend>`` should be used.
 
 When using a binary, it may be useful to know the backends that were enabled
 during the build. To check for the existence of backends, CMake's ``if(TARGET
@@ -81,10 +82,8 @@ The build parameters should be appropriately set before
 :ref:`building_the_project_with_adaptivecpp`.
 
 To link against the main library with run-time dispatching, use the target
-``onemath``. To link against particular domains, use the target
-``onemath_<domain>``. For example, ``onemath_blas`` or ``onemath_dft``. To link
-against particular backends (as required for static dispatch of oneAPI calls to
-a particular backend), use the target ``onemath_<domain>_<backend>``. For
-example, ``onemath_dft_cufft``.
+``onemath``. To link against particular backends with compile-time dispatching,
+use the target ``onemath_<domain>_<backend>``. For example,
+``onemath_dft_cufft``.
 
 .. _FetchContent: https://cmake.org/cmake/help/latest/module/FetchContent.html

examples/blas/compile_time_dispatching/level3/CMakeLists.txt

@@ -17,31 +17,31 @@
 # SPDX-License-Identifier: Apache-2.0
 #===============================================================================
 
-#Build object from all sources
-set(BLAS_CT_SOURCES "")
-if(ENABLE_MKLCPU_BACKEND AND ENABLE_CUBLAS_BACKEND)
-  list(APPEND BLAS_CT_SOURCES "gemm_usm_mklcpu_cublas")
+# The example is written for the MKLCPU and CUBLAS backends
+if(NOT (ENABLE_MKLCPU_BACKEND AND ENABLE_CUBLAS_BACKEND))
+  return()
 endif()
 
-foreach(blas_ct_source ${BLAS_CT_SOURCES})
-  add_executable(example_${domain}_${blas_ct_source} ${blas_ct_source}.cpp)
-  target_include_directories(example_${domain}_${blas_ct_source}
-      PUBLIC ${PROJECT_SOURCE_DIR}/examples/include
-      PUBLIC ${PROJECT_SOURCE_DIR}/include
-      PUBLIC ${CMAKE_BINARY_DIR}/bin
-  )
+set(EXAMPLE_TARGET example_blas_gemm_usm_mklcpu_cublas)
 
-  if(domain STREQUAL "blas" AND ENABLE_MKLCPU_BACKEND AND ENABLE_CUBLAS_BACKEND)
-    add_dependencies(example_${domain}_${blas_ct_source} onemath_${domain}_mklcpu onemath_${domain}_cublas)
-    list(APPEND ONEMATH_LIBRARIES_${domain} onemath_${domain}_mklcpu onemath_${domain}_cublas)
-  endif()
+# External applications should use find_package or FetchContent to include oneMath first.
+# See https://github.com/uxlfoundation/oneMath/blob/develop/docs/using_onemath_with_cmake.rst
 
-  target_link_libraries(example_${domain}_${blas_ct_source} PUBLIC
-      ${ONEMATH_LIBRARIES_${domain}}
-      ONEMATH::SYCL::SYCL
-  )
+# Create a CMake target with one source file
+add_executable(${EXAMPLE_TARGET} gemm_usm_mklcpu_cublas.cpp)
 
-  # Register example as ctest
-  add_test(NAME ${domain}/EXAMPLE/CT/${blas_ct_source} COMMAND example_${domain}_${blas_ct_source})
+# Linking against onemath_blas_mklcpu and onemath_blas_cublas in CMake will add the required include directories and dependencies.
+# One can also link against `onemath_blas` to link against all the blas backends built.
+# These targets should only be used for compile-time dispatching.
+target_link_libraries(${EXAMPLE_TARGET} PUBLIC
+  onemath_blas_mklcpu
+  onemath_blas_cublas
+)
 
-endforeach(blas_ct_source)
+# Include directories specific to the examples
+target_include_directories(${EXAMPLE_TARGET} PUBLIC
+  ${PROJECT_SOURCE_DIR}/examples/include
+)
+
+# Register example as ctest
+add_test(NAME blas/EXAMPLE/CT/gemm_usm_mklcpu_cublas COMMAND ${EXAMPLE_TARGET})

examples/blas/run_time_dispatching/level3/CMakeLists.txt

@@ -20,10 +20,6 @@
 # NOTE: user needs to set env var ONEAPI_DEVICE_SELECTOR to use runtime example without specifying backend in CMake
 # $ENV{ONEAPI_DEVICE_SELECTOR}
 
-
-# Build object from all example sources
-set(BLAS_RT_SOURCES "gemm_usm")
-
 # Set up for the right backend for run-time dispatching examples
 # If users build more than one backend (i.e. mklcpu and mklgpu, or mklcpu and CUDA), they may need to
 # overwrite ONEAPI_DEVICE_SELECTOR in their environment to run on the desired backend
@@ -56,32 +52,27 @@ endif()
 
 message(STATUS "ONEAPI_DEVICE_SELECTOR will be set to the following value(s): [${DEVICE_FILTERS}] for run-time dispatching examples")
 
-foreach(blas_rt_source ${BLAS_RT_SOURCES})
-  add_executable(example_${domain}_${blas_rt_source} ${blas_rt_source}.cpp)
-  target_include_directories(example_${domain}_${blas_rt_source}
-      PUBLIC ${PROJECT_SOURCE_DIR}/examples/include
-      PUBLIC ${PROJECT_SOURCE_DIR}/include
-      PUBLIC ${CMAKE_BINARY_DIR}/bin
-  )
+set(EXAMPLE_TARGET example_blas_gemm_usm)
 
-  add_dependencies(example_${domain}_${blas_rt_source} onemath)
+# External applications should use find_package or FetchContent to include oneMath first.
+# See https://github.com/uxlfoundation/oneMath/blob/develop/docs/using_onemath_with_cmake.rst
 
-  if (USE_ADD_SYCL_TO_TARGET_INTEGRATION)
-    add_sycl_to_target(TARGET example_${domain}_${blas_rt_source} SOURCES ${BLAS_RT_SOURCES})
-  endif()
+# Create a CMake target with one source file
+add_executable(${EXAMPLE_TARGET} gemm_usm.cpp)
 
-  target_link_libraries(example_${domain}_${blas_rt_source} PUBLIC
-      onemath
-      ONEMATH::SYCL::SYCL
-      ${CMAKE_DL_LIBS}
-  )
+# Linking against onemath in CMake will add the required include directories and dependencies.
+# This target should only be used for runtime dispatching.
+target_link_libraries(${EXAMPLE_TARGET} PUBLIC onemath)
 
-  # Register example as ctest
-  foreach(device_filter ${DEVICE_FILTERS})
-    add_test(NAME ${domain}/EXAMPLE/RT/${blas_rt_source}/${device_filter} COMMAND example_${domain}_${blas_rt_source})
-    set_property(TEST ${domain}/EXAMPLE/RT/${blas_rt_source}/${device_filter} PROPERTY
-      ENVIRONMENT LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/lib:$ENV{LD_LIBRARY_PATH}
-      ENVIRONMENT ONEAPI_DEVICE_SELECTOR=${device_filter})
-  endforeach(device_filter)
+# Include directories specific to the examples
+target_include_directories(${EXAMPLE_TARGET} PUBLIC
+  ${PROJECT_SOURCE_DIR}/examples/include
+)
 
-endforeach(blas_rt_source)
+# Register example as ctest for each device
+foreach(device_filter ${DEVICE_FILTERS})
+  add_test(NAME blas/EXAMPLE/RT/gemm_usm/${device_filter} COMMAND ${EXAMPLE_TARGET})
+  # Set ONEAPI_DEVICE_SELECTOR environment variable to select a device at runtime
+  set_property(TEST blas/EXAMPLE/RT/gemm_usm/${device_filter} PROPERTY
+    ENVIRONMENT ONEAPI_DEVICE_SELECTOR=${device_filter})
+endforeach(device_filter)

examples/dft/compile_time_dispatching/CMakeLists.txt

@@ -17,34 +17,35 @@
 # SPDX-License-Identifier: Apache-2.0
 #===============================================================================
 
-#Build object from all sources
-set(DFT_CT_SOURCES "")
-if (ENABLE_MKLCPU_BACKEND AND ENABLE_CUFFT_BACKEND)
-  list(APPEND DFT_CT_SOURCES "complex_fwd_usm_mklcpu_cufft")
+# The example is written for the MKLCPU and CUFFT backends
+if(NOT (ENABLE_MKLCPU_BACKEND AND ENABLE_CUFFT_BACKEND))
+  return()
 endif()
 
-include(WarningsUtils)
+set(EXAMPLE_TARGET example_dft_complex_fwd_usm_mklcpu_cufft)
 
-foreach(dft_ct_source ${DFT_CT_SOURCES})
-  set(EXAMPLE_NAME example_${domain}_${dft_ct_source})
-  add_executable(${EXAMPLE_NAME} ${dft_ct_source}.cpp)
-  target_include_directories(${EXAMPLE_NAME}
-      PUBLIC ${PROJECT_SOURCE_DIR}/examples/include
-      PUBLIC ${CMAKE_BINARY_DIR}/bin
-  )
+# External applications should use find_package or FetchContent to include oneMath first.
+# See https://github.com/uxlfoundation/oneMath/blob/develop/docs/using_onemath_with_cmake.rst
 
-  if(domain STREQUAL "dft" AND ENABLE_MKLCPU_BACKEND AND ENABLE_CUFFT_BACKEND)
-    add_dependencies(${EXAMPLE_NAME} onemath_${domain}_mklcpu onemath_${domain}_cufft)
-    list(APPEND ONEMATH_LIBRARIES_${domain} onemath_${domain}_mklcpu onemath_${domain}_cufft)
-  endif()
+# Create a CMake target with one source file
+add_executable(${EXAMPLE_TARGET} complex_fwd_usm_mklcpu_cufft.cpp)
 
-  target_link_libraries(${EXAMPLE_NAME} PUBLIC
-    ${ONEMATH_LIBRARIES_${domain}}
-    onemath_warnings
-  )
+# Linking against onemath_dft_mklcpu and onemath_dft_cufft in CMake will add the required include directories and dependencies.
+# One can also link against `onemath_dft` to link against all the dft backends built.
+# These targets should only be used for compile-time dispatching.
+target_link_libraries(${EXAMPLE_TARGET} PUBLIC
+  onemath_dft_mklcpu
+  onemath_dft_cufft
+)
 
-  # Register example as ctest
-  add_test(NAME dft/EXAMPLE/CT/${dft_ct_source} COMMAND ${EXAMPLE_NAME})
+# Include directories specific to the examples
+target_include_directories(${EXAMPLE_TARGET} PUBLIC
+  ${PROJECT_SOURCE_DIR}/examples/include
+)
 
-endforeach(dft_ct_source)
+# Enable warnings
+include(WarningsUtils)
+target_link_libraries(${EXAMPLE_TARGET} PRIVATE onemath_warnings)
 
+# Register example as ctest
+add_test(NAME dft/EXAMPLE/CT/complex_fwd_usm_mklcpu_cufft COMMAND ${EXAMPLE_TARGET})

examples/dft/run_time_dispatching/CMakeLists.txt

@@ -18,19 +18,11 @@
 #===============================================================================
 
 # NOTE: user needs to set env var ONEAPI_DEVICE_SELECTOR to use runtime example (no need to specify backend when building with CMake)
-include(WarningsUtils)
-
 
-# Build object from all example sources
-set(DFT_RT_SOURCES "")
 # Set up for the right backend for run-time dispatching examples
 # If users build more than one backend (i.e. mklcpu and mklgpu, or mklcpu and CUDA), they may need to
 # overwrite ONEAPI_DEVICE_SELECTOR in their environment to run on the desired backend
 set(DEVICE_FILTERS "")
-if(ENABLE_MKLGPU_BACKEND OR ENABLE_MKLCPU_BACKEND OR ENABLE_CUFFT_BACKEND OR ENABLE_ROCFFT_BACKEND OR ENABLE_PORTFFT_BACKEND)
-  list(APPEND DFT_RT_SOURCES "real_fwd_usm")
-endif()
-
 if(ENABLE_MKLGPU_BACKEND)
   list(APPEND DEVICE_FILTERS "level_zero:gpu")
 endif()
@@ -49,33 +41,31 @@ endif()
 
 message(STATUS "ONEAPI_DEVICE_SELECTOR will be set to the following value(s): [${DEVICE_FILTERS}] for run-time dispatching examples")
 
-foreach(dft_rt_sources ${DFT_RT_SOURCES})
-  add_executable(example_${domain}_${dft_rt_sources} ${dft_rt_sources}.cpp)
-  target_include_directories(example_${domain}_${dft_rt_sources}
-      PUBLIC ${PROJECT_SOURCE_DIR}/examples/include
-      PUBLIC ${PROJECT_SOURCE_DIR}/include
-      PUBLIC ${CMAKE_BINARY_DIR}/bin
-  )
+set(EXAMPLE_TARGET example_dft_real_fwd_usm)
+
+# External applications should use find_package or FetchContent to include oneMath first.
+# See https://github.com/uxlfoundation/oneMath/blob/develop/docs/using_onemath_with_cmake.rst
 
-  add_dependencies(example_${domain}_${dft_rt_sources} onemath)
+# Create a CMake target with one source file
+add_executable(${EXAMPLE_TARGET} real_fwd_usm.cpp)
 
-  if (USE_ADD_SYCL_TO_TARGET_INTEGRATION)
-    add_sycl_to_target(TARGET example_${domain}_${dft_rt_sources} SOURCES ${DFT_RT_SOURCES})
-  endif()
+# Linking against onemath in CMake will add the required include directories and dependencies.
+# This target should only be used for runtime dispatching.
+target_link_libraries(${EXAMPLE_TARGET} PUBLIC onemath)
 
-  target_link_libraries(example_${domain}_${dft_rt_sources}
-      PUBLIC onemath
-      PUBLIC ONEMATH::SYCL::SYCL
-      PUBLIC ${CMAKE_DL_LIBS}
-      PRIVATE onemath_warnings
-  )
+# Include directories specific to the examples
+target_include_directories(${EXAMPLE_TARGET} PUBLIC
+  ${PROJECT_SOURCE_DIR}/examples/include
+)
 
-  # Register example as ctest
-  foreach(device_filter ${DEVICE_FILTERS})
-    add_test(NAME ${domain}/EXAMPLE/RT/${dft_rt_sources}/${device_filter} COMMAND example_${domain}_${dft_rt_sources})
-    set_property(TEST ${domain}/EXAMPLE/RT/${dft_rt_sources}/${device_filter} PROPERTY
-      ENVIRONMENT LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/lib:$ENV{LD_LIBRARY_PATH}
-      ENVIRONMENT ONEAPI_DEVICE_SELECTOR=${device_filter})
-  endforeach(device_filter)
+# Enable warnings
+include(WarningsUtils)
+target_link_libraries(${EXAMPLE_TARGET} PRIVATE onemath_warnings)
 
-endforeach()
+# Register example as ctest
+foreach(device_filter ${DEVICE_FILTERS})
+  add_test(NAME dft/EXAMPLE/RT/real_fwd_usm/${device_filter} COMMAND ${EXAMPLE_TARGET})
+  # Set ONEAPI_DEVICE_SELECTOR environment variable to select a device at runtime
+  set_property(TEST dft/EXAMPLE/RT/real_fwd_usm/${device_filter} PROPERTY
+    ENVIRONMENT ONEAPI_DEVICE_SELECTOR=${device_filter})
+endforeach(device_filter)

examples/lapack/compile_time_dispatching/CMakeLists.txt

@@ -17,33 +17,31 @@
 # SPDX-License-Identifier: Apache-2.0
 #===============================================================================
 
-#Build object from all sources
-set(LAPACK_CT_SOURCES "")
-if(ENABLE_MKLCPU_BACKEND AND ENABLE_CUSOLVER_BACKEND)
-  list(APPEND LAPACK_CT_SOURCES "getrs_usm_mklcpu_cusolver")
+# The example is written for the MKLCPU and CUSOLVER backends
+if(NOT (ENABLE_MKLCPU_BACKEND AND ENABLE_CUSOLVER_BACKEND))
+  return()
 endif()
 
-if(domain STREQUAL "lapack" AND ENABLE_MKLCPU_BACKEND)
-  find_library(OPENCL_LIBRARY NAMES OpenCL)
-  message(STATUS "Found OpenCL: ${OPENCL_LIBRARY}")
-endif()
+set(EXAMPLE_TARGET example_lapack_getrs_usm_mklcpu_cusolver)
+
+# External applications should use find_package or FetchContent to include oneMath first.
+# See https://github.com/uxlfoundation/oneMath/blob/develop/docs/using_onemath_with_cmake.rst
+
+# Create a CMake target with one source file
+add_executable(${EXAMPLE_TARGET} getrs_usm_mklcpu_cusolver.cpp)
+
+# Linking against onemath_lapack_mklcpu and onemath_lapack_cusolver in CMake will add the required include directories and dependencies.
+# One can also link against `onemath_lapack` to link against all the lapack backends built.
+# These targets should only be used for compile-time dispatching.
+target_link_libraries(${EXAMPLE_TARGET} PUBLIC
+  onemath_lapack_mklcpu
+  onemath_lapack_cusolver
+)
+
+# Include directories specific to the examples
+target_include_directories(${EXAMPLE_TARGET} PUBLIC
+  ${PROJECT_SOURCE_DIR}/examples/include
+)
 
-foreach(lapack_ct_source ${LAPACK_CT_SOURCES})
-  add_executable(example_${domain}_${lapack_ct_source} ${lapack_ct_source}.cpp)
-  target_include_directories(example_${domain}_${lapack_ct_source}
-      PUBLIC ${PROJECT_SOURCE_DIR}/examples/include
-      PUBLIC ${PROJECT_SOURCE_DIR}/include
-      PUBLIC ${CMAKE_BINARY_DIR}/bin
-  )
-  if(domain STREQUAL "lapack" AND ENABLE_MKLCPU_BACKEND AND ENABLE_CUSOLVER_BACKEND)
-    add_dependencies(example_${domain}_${lapack_ct_source} onemath_${domain}_mklcpu onemath_${domain}_cusolver)
-    list(APPEND ONEMATH_LIBRARIES_${domain} onemath_${domain}_mklcpu onemath_${domain}_cusolver)
-    target_link_libraries(example_${domain}_${lapack_ct_source} PUBLIC ${OPENCL_LIBRARY})
-  endif()
-  target_link_libraries(example_${domain}_${lapack_ct_source} PUBLIC
-      ${ONEMATH_LIBRARIES_${domain}}
-      ONEMATH::SYCL::SYCL
-  )
-  # Register example as ctest
- add_test(NAME ${domain}/EXAMPLE/CT/${lapack_ct_source} COMMAND example_${domain}_${lapack_ct_source})
-endforeach(lapack_ct_source)
+# Register example as ctest
+add_test(NAME lapack/EXAMPLE/CT/getrs_usm_mklcpu_cusolver COMMAND ${EXAMPLE_TARGET})