Executable folder utilities (#77)

* Add BUILD_UTILITY_LIBRARIES option

* Add whereami dependence

* Add exe relative utilities

* Update samples to use exe relative utilities

* Improve diagnostic on missing file

* Add missing default argument for error param

* Add docs on file utilities

* Add EOL

* Fix typo

Co-authored-by: Ronan Keryell <ronan.keryell@amd.com>

* Simplify byte size calculation

Co-authored-by: Ronan Keryell <ronan.keryell@amd.com>

* Fix typo

Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>

* Fix formatting

* Remove implicit narrowing conversions

* No unnamed type on libSDK surface

* warning: enumeration value x not handled in switch

---------

Co-authored-by: Ronan Keryell <ronan.keryell@amd.com>
Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>

CMakeLists.txt

@@ -23,7 +23,8 @@ project(OpenCL-SDK
 )
 
 include(CMakeDependentOption)
-option(OPENCL_SDK_BUILD_SAMPLES "Build sample code" ON)
+option(OPENCL_SDK_BUILD_UTILITY_LIBRARIES "Build utility libraries" ON)
+cmake_dependent_option(OPENCL_SDK_BUILD_SAMPLES "Build sample code" ON OPENCL_SDK_BUILD_UTILITY_LIBRARIES OFF)
 cmake_dependent_option(OPENCL_SDK_BUILD_OPENGL_SAMPLES "Build OpenCL-OpenGL interop sample code" ON OPENCL_SDK_BUILD_SAMPLES OFF)
 cmake_dependent_option(OPENCL_SDK_TEST_SAMPLES "Add CTest to samples (where applicable)" ON OPENCL_SDK_BUILD_SAMPLES OFF)
 
@@ -47,8 +48,9 @@ list(APPEND CMAKE_MODULE_PATH
   ${PROJECT_SOURCE_DIR}/cmake/Modules
 )
 include(Dependencies)
-
-add_subdirectory(lib)
+if(OPENCL_SDK_BUILD_UTILITY_LIBRARIES)
+  add_subdirectory(lib)
+endif()
 if(OPENCL_SDK_BUILD_SAMPLES)
   add_subdirectory(samples)
 endif()

cmake/Dependencies.cmake

@@ -1,3 +1,10 @@
+if(OPENCL_SDK_BUILD_UTILITY_LIBRARIES)
+  foreach(DEP IN ITEMS whereami)
+    list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/Dependencies/${DEP}")
+    include(${DEP})
+  endforeach()
+endif()
+
 if(OPENCL_SDK_BUILD_SAMPLES)
   foreach(DEP IN ITEMS cargs TCLAP Stb)
     list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/Dependencies/${DEP}")

cmake/Dependencies/whereami/whereami.cmake

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.11)
+include(FetchContent)
+FetchContent_Declare(
+  whereami-external
+  GIT_REPOSITORY https://github.com/gpakosz/whereami.git
+  GIT_TAG        ba364cd54fd431c76c045393b6522b4bff547f50 # master @ 2023.04.20.
+)
+FetchContent_MakeAvailable(whereami-external)
+add_library(whereami IMPORTED INTERFACE)
+target_include_directories(whereami
+  INTERFACE "${CMAKE_CURRENT_BINARY_DIR}/_deps/whereami-external-src/src"
+)
+target_sources(whereami
+  INTERFACE "${CMAKE_CURRENT_BINARY_DIR}/_deps/whereami-external-src/src/whereami.c"
+)

lib/CMakeLists.txt

@@ -36,6 +36,8 @@ foreach(UTIL_LIB_NAME IN ITEMS Utils UtilsCpp)
       $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
   )
   target_link_libraries(${UTIL_LIB_TARGET}
+    PRIVATE
+      whereami
     PUBLIC
       ${UTIL_LIB_DEPS}
       OpenCL::OpenCL

lib/Utils.md

@@ -9,6 +9,7 @@ The OpenCL Utility Library provides both C and C++ bindings with near feature pa
 - [Context](#context-utilities)
 - [Event](#event-utilities)
 - [Error](#error-handling-utilities)
+- [File](#file-utilities)
 
 ### Platform utilities
 
@@ -119,3 +120,97 @@ public:
 };
 ```
 This type is used as the exception type thrown by utilities when an error occurs and the compiling code defines `CL_HPP_ENABLE_EXCEPTIONS`
+
+### File utilities
+
+```c
+char* cl_util_read_text_file(
+    const char* const filename,
+    size_t* const length,
+    cl_int* const error);
+```
+
+```c++
+std::string cl::util::read_text_file(
+    const char* const filename,
+    cl_int* const error = nullptr);
+```
+
+These functions read a text file into memory, where `filename` is evaluated relative to the current working directory. The C-version contains a terminating null and takes an optional pointer to `length` by which the length my be returned, potentially saving a subsequent call to `strlen`. The function hands ownership of the allocated storage to the caller.
+
+```c
+unsigned char* cl_util_read_binary_file(
+    const char* const filename,
+    size_t* const length,
+    cl_int* const error);
+```
+
+```c++
+std::vector<unsigned char> read_binary_file(
+    const char* const filename,
+    cl_int* const error = nullptr);
+```
+
+These functions read a binary file into memory, where `filename` is evaluated relative to the current working directory. The C-version takes an optional pointer to `length` by which the length my be returned. Because it's binary data, it is _not_ null-terminated, therefore highly recommended to take it's size. The returned types align with OpenCL APIs taking binaries as input. The function hands ownership of the allocated storage to the caller.
+
+```c
+cl_program cl_util_read_binaries(
+    const cl_context context,
+    const cl_device_id* const devices,
+    const cl_uint num_devices,
+    const char* const program_file_name,
+    cl_int* const error
+);
+```
+
+```c++
+Program::Binaries read_binary_files(
+    const std::vector<cl::Device>& devices,
+    const char* const program_file_name,
+    cl_int* const error = nullptr);
+```
+
+These functions read a set of binary files into memory. `program_file_name` is a pattern that will be completed for every input device using the `"(program_file_name)_(name of device).bin"` pattern. If any of the files are not found, the function fails.
+
+```c
+cl_int cl_util_write_binaries(
+    const cl_program program,
+    const char* const program_file_name);
+```
+
+```c++
+write_binaries(
+    const cl::Program::Binaries& binaries,
+    const std::vector<cl::Device>& devices,
+    const char* const program_file_name);
+```
+
+These functions will write all device binaries of a program to persistent storage. `program_file_name` is a pattern that will be completed for every input device using the `"(program_file_name)_(name of device).bin"` pattern.
+
+```c
+cl_int cl_util_executable_folder(
+    char* filename,
+    size_t* const length);
+```
+
+```c++
+std::string executable_folder(
+    cl_int* const error = nullptr);
+```
+
+These functions return the path to the folder containing the currently running executable. It is typically useful to find assets which are stored uniformly in a program's build and install tree. The C-version contains a terminating null and takes an optional pointer to `length` by which the length my be returned, potentially saving a subsequent call to `strlen`.
+
+```c
+char* cl_util_read_exe_relative_text_file(
+    const char* const rel_path,
+    size_t* const length,
+    cl_int* const error);
+```
+
+```c++
+std::string read_exe_relative_text_file(
+    const char* const filename,
+    cl_int* const error = nullptr);
+```
+
+These functions read a text file into memory, where `filename` is evaluated relative to the executable currently running. The C-version contains a terminating null and takes an optional pointer to `length` by which the length will be returned, potentially saving a subsequent call to `strlen`. The function hands ownership of the allocated storage to the caller.

lib/include/CL/SDK/InteropWindow.hpp

@@ -13,13 +13,18 @@
 #include <SFML/Window.hpp>
 #include <SFML/OpenGL.hpp>
 
+// STL includes
+#include <type_traits>
+
 namespace cl {
 namespace sdk {
     class SDKCPP_EXPORT InteropWindow : public sf::Window {
     public:
+        using Style = std::underlying_type_t<decltype(sf::Style::Default)>;
+
         explicit InteropWindow(
             sf::VideoMode mode, const sf::String& title,
-            sf::Uint32 style = sf::Style::Default,
+            Style style = sf::Style::Default,
             const sf::ContextSettings& settings = sf::ContextSettings{},
             cl_uint platform_id = 0, cl_uint device_id = 0,
             cl_bitfield device_type = CL_DEVICE_TYPE_DEFAULT);

lib/include/CL/Utils/File.h

@@ -40,3 +40,16 @@ cl_program cl_util_read_binaries(const cl_context context,
                                  const cl_uint num_devices,
                                  const char* const program_file_name,
                                  cl_int* const error);
+
+// returns the folder containing the running executable
+UTILS_EXPORT
+cl_int cl_util_executable_folder(char* filename, size_t* const length);
+
+// read all the text file contents securely in ANSI C89
+// return pointer to C-string with file contents
+// interprets filename relative to the folder containing
+// the running executable
+UTILS_EXPORT
+char* cl_util_read_exe_relative_text_file(const char* const rel_path,
+                                          size_t* const length,
+                                          cl_int* const error);

lib/include/CL/Utils/File.hpp

@@ -13,18 +13,24 @@ namespace cl {
 namespace util {
 
     std::string UTILSCPP_EXPORT read_text_file(const char* const filename,
-                                               cl_int* const error);
+                                               cl_int* const error = nullptr);
 
     std::vector<unsigned char> UTILSCPP_EXPORT
-    read_binary_file(const char* const filename, cl_int* const error);
+    read_binary_file(const char* const filename, cl_int* const error = nullptr);
 
-    Program::Binaries UTILSCPP_EXPORT
-    read_binary_files(const std::vector<cl::Device>& devices,
-                      const char* const program_file_name, cl_int* const error);
+    Program::Binaries UTILSCPP_EXPORT read_binary_files(
+        const std::vector<cl::Device>& devices,
+        const char* const program_file_name, cl_int* const error = nullptr);
 
     cl_int UTILSCPP_EXPORT
     write_binaries(const cl::Program::Binaries& binaries,
                    const std::vector<cl::Device>& devices,
                    const char* const program_file_name);
+
+    std::string UTILSCPP_EXPORT
+    executable_folder(cl_int* const error = nullptr);
+
+    std::string UTILSCPP_EXPORT read_exe_relative_text_file(
+        const char* const filename, cl_int* const error = nullptr);
 }
 }

lib/src/SDK/Image.c

@@ -40,7 +40,7 @@ cl_sdk_image cl_sdk_read_image(const char* const file_name, cl_int* const error)
 
 static char* to_lowercase(const char* const s, char* const d, const size_t n)
 {
-    for (size_t i = 0; i < n; ++i) d[i] = tolower(s[i]);
+    for (size_t i = 0; i < n; ++i) d[i] = (char)tolower(s[i]);
     return d;
 }
 

lib/src/SDK/InteropWindow.cpp

@@ -3,12 +3,12 @@
 #include <CL/SDK/InteropContext.hpp>
 
 cl::sdk::InteropWindow::InteropWindow(sf::VideoMode mode,
-                                      const sf::String& title, sf::Uint32 style,
+                                      const sf::String& title, Style style,
                                       const sf::ContextSettings& settings,
                                       cl_uint platform_id, cl_uint device_id,
                                       cl_bitfield device_type)
-    : sf::Window{ mode, title, style, settings }, plat_id{ platform_id },
-      dev_id{ device_id }, dev_type{ device_type }
+    : sf::Window{ mode, title, static_cast<sf::Uint32>(style), settings },
+      plat_id{ platform_id }, dev_id{ device_id }, dev_type{ device_type }
 {}
 
 void cl::sdk::InteropWindow::run()

lib/src/Utils/File.c

@@ -6,6 +6,9 @@
 #include <stdio.h> // fopen, ferror, fread, fclose
 #include <string.h> // memset
 
+// whereami includes
+#include <whereami.h>
+
 // read all the text file contents securely in ANSI C89
 // return pointer to C-string with file contents
 // can handle streams with no known size and no support for fseek
@@ -337,3 +340,76 @@ cl_program cl_util_read_binaries(const cl_context context,
     if (error != NULL) *error = err;
     return program;
 }
+
+UTILS_EXPORT
+cl_int cl_util_executable_folder(char *const filename, size_t *const length)
+{
+    cl_int err = CL_SUCCESS;
+    int wai_length, wai_dirname_length = 0;
+    char *wai_filename = NULL;
+
+#define IF_ERR(func, error_type, label)                                        \
+    do                                                                         \
+    {                                                                          \
+        if (func)                                                              \
+        {                                                                      \
+            err = error_type;                                                  \
+            goto label;                                                        \
+        }                                                                      \
+    } while (0)
+
+    wai_length = wai_getExecutablePath(NULL, 0, NULL);
+    IF_ERR(wai_length == -1, CL_UTIL_FILE_OPERATION_ERROR, end);
+    MEM_CHECK(wai_filename = (char *)malloc(wai_length), err, end);
+    IF_ERR(wai_getExecutablePath(wai_filename, wai_length, &wai_dirname_length)
+               == -1,
+           CL_UTIL_FILE_OPERATION_ERROR, end);
+
+    if (length != NULL)
+    {
+        *length = (int)wai_dirname_length + 1;
+    }
+
+    if (filename != NULL)
+    {
+        memmove(filename, wai_filename, wai_dirname_length);
+        filename[wai_dirname_length] = '\0';
+    }
+
+end:
+    free(wai_filename);
+
+    return err;
+}
+
+// read all the text file contents securely in ANSI C89
+// return pointer to C-string with file contents
+// interprets filename relative to the folder containing
+// the running executable
+UTILS_EXPORT
+char *cl_util_read_exe_relative_text_file(const char *const rel_path,
+                                          size_t *const length,
+                                          cl_int *const error)
+{
+    char *result = NULL;
+    size_t result_size = 0;
+    char *abs_path = NULL;
+    cl_int err = CL_SUCCESS;
+    size_t exe_folder_length;
+    OCLERROR_RET(cl_util_executable_folder(NULL, &exe_folder_length), err, end);
+    MEM_CHECK(abs_path =
+                  (char *)malloc(exe_folder_length + strlen(rel_path) + 1),
+              err, end);
+    OCLERROR_RET(cl_util_executable_folder(abs_path, NULL), err, end);
+    strcat(strcat(abs_path, "/"), rel_path);
+    OCLERROR_PAR(result = cl_util_read_text_file(abs_path, &result_size, &err),
+                 err, end);
+
+    if (length != NULL) *length = result_size;
+
+    if (error != NULL) *error = err;
+end:
+    free(abs_path);
+
+    return result;
+}