Merge pull request #629 from kswiecicki/platform-discovery-win-sys

Change adapter discovery behavior on Windows

scripts/core/INTRO.rst

@@ -210,6 +210,30 @@ An example of an environment variable for setting up the null adapter library wi
 
  UR_LOG_NULL="level:warning;output:stdout"
 
+Adapter Discovery
+---------------------
+UR is capable of discovering adapter libraries in the following ways in the listed order:
+
+ - Search in paths to the adapters set in `UR_ADAPTERS_FORCE_LOAD` environment variable.
+
+ + All other adapter discovery methods are disabled when this environment variable is used.
+
+ - Search in directories specified in `UR_ADAPTERS_SEARCH_PATH` environment variable.
+
+ - Leave adapter discovery for the OS.
+
+ + This method is disabled on Windows.
+
+ + If on Linux, use the shared library discovery mechanism (see **ld.so**(8) for details).
+
+ - Search in directory at the UR loader location.
+
+Currently, UR looks for these adapter libraries:
+
+ - ur_adapter_level_zero
+
+For more information about the usage of mentioned environment variables see `Environment Variables`_ section.
+
 Environment Variables
 ---------------------
 
@@ -229,7 +253,7 @@ Specific environment variables can be set to control the behavior of unified run
 
 .. envvar:: UR_ADAPTERS_FORCE_LOAD
 
- Holds a comma-separated list of library names used by the loader for adapter discovery. By setting this value you can
+ Holds a comma-separated list of library paths used by the loader for adapter discovery. By setting this value you can
  force the loader to use specific adapter implementations from the libraries provided.
 
  .. note::
@@ -238,8 +262,7 @@ Specific environment variables can be set to control the behavior of unified run
 
  .. note::
 
- When this environmental variable is used the paths in environmental variable :envvar:`UR_ADAPTERS_SEARCH_PATH`
- are ignored.
+ All other adapter discovery methods are disabled when this environment variable is used.
 
 .. envvar:: UR_ADAPTERS_SEARCH_PATH
 
@@ -252,7 +275,7 @@ Specific environment variables can be set to control the behavior of unified run
 
  .. note::
 
- This environmental variable is ignored when :envvar:`UR_ADAPTERS_FORCE_LOAD` environmental variable is used.
+ This environment variable is ignored when :envvar:`UR_ADAPTERS_FORCE_LOAD` environment variable is used.
 
 .. envvar:: UR_ENABLE_VALIDATION_LAYER
 

source/loader/CMakeLists.txt

@@ -119,15 +119,15 @@ endif()
 if(WIN32)
  target_sources(ur_loader
  PRIVATE
+ ${CMAKE_CURRENT_SOURCE_DIR}/windows/adapter_search.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/windows/lib_init.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/windows/loader_init.cpp
- ${CMAKE_CURRENT_SOURCE_DIR}/windows/loader_location.cpp
  )
 else()
  target_sources(ur_loader
  PRIVATE
+ ${CMAKE_CURRENT_SOURCE_DIR}/linux/adapter_search.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/linux/lib_init.cpp
  ${CMAKE_CURRENT_SOURCE_DIR}/linux/loader_init.cpp
- ${CMAKE_CURRENT_SOURCE_DIR}/linux/loader_location.cpp
  )
 endif()

source/loader/linux/loader_location.cpp → source/loader/linux/adapter_search.cpp

@@ -30,4 +30,8 @@ std::optional<fs::path> getLoaderLibPath() {
  return std::nullopt;
 }
 
+std::optional<fs::path> getAdapterNameAsPath(std::string adapterName) {
+ return fs::path(adapterName);
+}
+
 } // namespace ur_loader

source/loader/ur_adapter_registry.hpp

@@ -13,7 +13,7 @@
 #include <array>
 
 #include "logger/ur_logger.hpp"
-#include "ur_loader_location.hpp"
+#include "ur_adapter_search.hpp"
 #include "ur_util.hpp"
 
 namespace fs = filesystem;
@@ -152,7 +152,11 @@ class AdapterRegistry {
  }
  }
 
- loadPaths.emplace_back(fs::path(adapterName));
+ auto adapterNamePathOpt = getAdapterNameAsPath(adapterName);
+ if (adapterNamePathOpt.has_value()) {
+ auto adapterNamePath = adapterNamePathOpt.value();
+ loadPaths.emplace_back(adapterNamePath);
+ }
 
  if (loaderLibPathOpt.has_value()) {
  auto loaderLibPath = loaderLibPathOpt.value();

source/loader/ur_loader_location.hpp → source/loader/ur_adapter_search.hpp

@@ -8,8 +8,10 @@
  *
  */
 
-#ifndef UR_LOADER_LOCATION_HPP
-#define UR_LOADER_LOCATION_HPP 1
+#ifndef UR_ADAPTER_SEARCH_HPP
+#define UR_ADAPTER_SEARCH_HPP 1
+
+#include <optional>
 
 #include "ur_filesystem_resolved.hpp"
 
@@ -18,7 +20,8 @@ namespace fs = filesystem;
 namespace ur_loader {
 
 std::optional<fs::path> getLoaderLibPath();
+std::optional<fs::path> getAdapterNameAsPath(std::string adapterName);
 
 } // namespace ur_loader
 
-#endif /* UR_LOADER_LOCATION_HPP */
+#endif /* UR_ADAPTER_SEARCH_HPP */

source/loader/windows/loader_location.cpp → source/loader/windows/adapter_search.cpp

@@ -34,4 +34,8 @@ std::optional<fs::path> getLoaderLibPath() {
  return std::nullopt;
 }
 
+std::optional<fs::path> getAdapterNameAsPath(std::string adapterName) {
+ return std::nullopt;
+}
+
 } // namespace ur_loader

test/loader/adapter_registry/CMakeLists.txt

@@ -12,10 +12,10 @@ function(add_adapter_reg_search_test name)
 
  if(WIN32)
  target_sources(${TEST_TARGET_NAME} PRIVATE
- ${CMAKE_SOURCE_DIR}/source/loader/windows/loader_location.cpp)
+ ${CMAKE_SOURCE_DIR}/source/loader/windows/adapter_search.cpp)
  else()
  target_sources(${TEST_TARGET_NAME} PRIVATE
- ${CMAKE_SOURCE_DIR}/source/loader/linux/loader_location.cpp)
+ ${CMAKE_SOURCE_DIR}/source/loader/linux/adapter_search.cpp)
  endif()
 
  target_link_libraries(${TEST_TARGET_NAME}

test/loader/adapter_registry/search_no_env.cpp

@@ -6,10 +6,12 @@
 #include "fixtures.hpp"
 
 TEST_F(adapterRegSearchTest, testSearchNoEnv) {
- // Check if there's any path that's just a library name.
+ // Check if there's any path that's just a library name (disabled on Windows)
+#ifndef _WIN32
  auto testLibNameExists =
  std::any_of(registry.cbegin(), registry.cend(), hasTestLibName);
  ASSERT_TRUE(testLibNameExists);
+#endif
 
  // Check for path obtained from 'UR_ADAPTERS_SEARCH_PATH'
  auto testEnvPathExists =

test/loader/adapter_registry/search_order.cpp

@@ -5,28 +5,29 @@
 
 #include "fixtures.hpp"
 
+template <typename P>
+void assertRegistryPathSequence(std::vector<fs::path> testAdapterPaths,
+ P predicate) {
+ static size_t assertIndex = 0;
+
+ auto pathIt = std::find_if(testAdapterPaths.cbegin(),
+ testAdapterPaths.cend(), predicate);
+ size_t index = std::distance(testAdapterPaths.cbegin(), pathIt);
+ ASSERT_EQ(index, assertIndex++);
+}
+
 TEST_F(adapterRegSearchTest, testSearchOrder) {
  // Adapter search order:
  // 1. Every path from UR_ADAPTERS_SEARCH_PATH.
- // 2. OS search paths.
+ // 2. OS search paths (disabled on Windows).
  // 3. Loader library directory.
-
  auto it = std::find_if(registry.cbegin(), registry.cend(), hasTestLibName);
  ASSERT_NE(it, registry.end());
 
  auto testAdapterPaths = *it;
- auto pathIt = std::find_if(testAdapterPaths.cbegin(),
- testAdapterPaths.cend(), isTestEnvPath);
- std::size_t index = std::distance(testAdapterPaths.cbegin(), pathIt);
- ASSERT_EQ(index, 0);
-
- pathIt = std::find_if(testAdapterPaths.cbegin(), testAdapterPaths.cend(),
- isTestLibName);
- index = std::distance(testAdapterPaths.cbegin(), pathIt);
- ASSERT_EQ(index, 1);
-
- pathIt = std::find_if(testAdapterPaths.cbegin(), testAdapterPaths.cend(),
- isCurPath);
- index = std::distance(testAdapterPaths.cbegin(), pathIt);
- ASSERT_EQ(index, 2);
+ assertRegistryPathSequence(testAdapterPaths, isTestEnvPath);
+#ifndef _WIN32
+ assertRegistryPathSequence(testAdapterPaths, isTestLibName);
+#endif
+ assertRegistryPathSequence(testAdapterPaths, isCurPath);
 }

test/loader/adapter_registry/search_with_env.cpp

@@ -6,10 +6,12 @@
 #include "fixtures.hpp"
 
 TEST_F(adapterRegSearchTest, testSearchWithEnv) {
- // Check if there's any path that's just a library name.
+ // Check if there's any path that's just a library name (disabled on Windows).
+#ifndef _WIN32
  auto testLibNameExists =
  std::any_of(registry.cbegin(), registry.cend(), hasTestLibName);
  ASSERT_TRUE(testLibNameExists);
+#endif
 
  // Check for path obtained from 'UR_ADAPTERS_SEARCH_PATH'
  auto testEnvPathExists =