Allow applications to specify the Vulkan library path

I don't know if vendoring the Vulkan library is appropriate, but regardless,
this allows applications to set the name to whatever they want, or specify an
absolute path, just in case the standard value baked into Pugl isn't the right
one in some situation.

9 files changed, 41 insertions, 13 deletions

diff --git a/bindings/cpp/include/pugl/vulkan.hpp b/bindings/cpp/include/pugl/vulkan.hpp
index a742085..5bb790d 100644
--- a/bindings/cpp/include/pugl/vulkan.hpp
+++ b/bindings/cpp/include/pugl/vulkan.hpp
@@ -51,7 +51,20 @@ public:
      failed loader, but the accessors will always return null.
   */
   explicit VulkanLoader(World& world) noexcept
-    : Wrapper{puglNewVulkanLoader(world.cobj())}
+    : VulkanLoader{world, nullptr}
+  {}
+
+  /**
+     Create a new dynamic loader for Vulkan functions from a specific library.
+
+     This is the same as the simpler constructor, but allows the user to
+     specify the name of the Vulkan library to load, for certain packaging
+     scenarios or unusual/unsupported system configurations.  The `libraryName`
+     is passed to the system library loading function (`dlopen` or
+     `LoadLibrary`), and supports an absolute path.
+  */
+  explicit VulkanLoader(World& world, const char* const libraryName) noexcept
+    : Wrapper{puglNewVulkanLoader(world.cobj(), libraryName)}
   {}
 
   /**
diff --git a/doc/c/view.rst b/doc/c/view.rst
index 0a26e14..31eab21 100644
--- a/doc/c/view.rst
+++ b/doc/c/view.rst
@@ -228,7 +228,7 @@ To do so, first create a :struct:`PuglVulkanLoader`:
 
 .. code-block:: c
 
-   PuglVulkanLoader* loader = puglNewVulkanLoader(world);
+   PuglVulkanLoader* loader = puglNewVulkanLoader(world, NULL);
 
 The loader manages the dynamically loaded Vulkan library,
 so it must be kept alive for as long as the application is using Vulkan.
diff --git a/examples/pugl_vulkan_demo.c b/examples/pugl_vulkan_demo.c
index e1daeb0..59e3060 100644
--- a/examples/pugl_vulkan_demo.c
+++ b/examples/pugl_vulkan_demo.c
@@ -1077,7 +1077,7 @@ main(int argc, char** argv)
   }
 
   // Create Vulkan surface for window
-  PuglVulkanLoader* loader = puglNewVulkanLoader(app.world);
+  PuglVulkanLoader* loader = puglNewVulkanLoader(app.world, NULL);
   if (puglCreateSurface(puglGetInstanceProcAddrFunc(loader),
                         app.view,
                         vk->instance,
diff --git a/include/pugl/vulkan.h b/include/pugl/vulkan.h
index 0ca7941..cc138df 100644
--- a/include/pugl/vulkan.h
+++ b/include/pugl/vulkan.h
@@ -58,11 +58,20 @@ typedef struct PuglVulkanLoaderImpl PuglVulkanLoader;
    This dynamically loads the Vulkan library and gets the load functions from
    it.
 
+   @param world The world the returned loader is a part of.
+
+   @param libraryName The name of the Vulkan library to load, or null.
+   Typically, this is left unset, which will load the standard Vulkan library
+   for the current platform.  It can be set to an alternative name, or an
+   absolute path, to support special packaging scenarios or unusual system
+   configurations.  This name is passed directly to the underlying platform
+   library loading function (`dlopen` or `LoadLibrary`).
+
    @return A new Vulkan loader, or null on failure.
 */
 PUGL_API
 PuglVulkanLoader*
-puglNewVulkanLoader(PuglWorld* world);
+puglNewVulkanLoader(PuglWorld* world, const char* libraryName);
 
 /**
    Free a loader created with puglNewVulkanLoader().
diff --git a/meson.build b/meson.build
index 6ce6c8d..6185fde 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: 0BSD OR ISC
 
 project('pugl', ['c'],
-        version: '0.5.1',
+        version: '0.5.3',
         license: 'ISC',
         meson_version: '>= 0.54.0',
         default_options: [
diff --git a/src/mac_vulkan.m b/src/mac_vulkan.m
index 2362db1..45c4839 100644
--- a/src/mac_vulkan.m
+++ b/src/mac_vulkan.m
@@ -107,7 +107,8 @@ struct PuglVulkanLoaderImpl {
 };
 
 PuglVulkanLoader*
-puglNewVulkanLoader(PuglWorld* PUGL_UNUSED(world))
+puglNewVulkanLoader(PuglWorld*        PUGL_UNUSED(world),
+                    const char* const libraryName)
 {
   PuglVulkanLoader* loader =
     (PuglVulkanLoader*)calloc(1, sizeof(PuglVulkanLoader));
@@ -115,7 +116,8 @@ puglNewVulkanLoader(PuglWorld* PUGL_UNUSED(world))
     return NULL;
   }
 
-  if (!(loader->libvulkan = dlopen("libvulkan.dylib", RTLD_LAZY))) {
+  const char* const filename = libraryName ? libraryName : "libvulkan.dylib";
+  if (!(loader->libvulkan = dlopen(filename, RTLD_LAZY))) {
     free(loader);
     return NULL;
   }
diff --git a/src/win_vulkan.c b/src/win_vulkan.c
index ddd3fbe..4a4d005 100644
--- a/src/win_vulkan.c
+++ b/src/win_vulkan.c
@@ -21,7 +21,8 @@ struct PuglVulkanLoaderImpl {
 };
 
 PuglVulkanLoader*
-puglNewVulkanLoader(PuglWorld* PUGL_UNUSED(world))
+puglNewVulkanLoader(PuglWorld*        PUGL_UNUSED(world),
+                    const char* const libraryName)
 {
   PuglVulkanLoader* loader =
     (PuglVulkanLoader*)calloc(1, sizeof(PuglVulkanLoader));
@@ -29,8 +30,9 @@ puglNewVulkanLoader(PuglWorld* PUGL_UNUSED(world))
     return NULL;
   }
 
-  const DWORD flags = LOAD_LIBRARY_SEARCH_DEFAULT_DIRS;
-  if (!(loader->libvulkan = LoadLibraryEx("vulkan-1.dll", NULL, flags))) {
+  const DWORD       flags    = LOAD_LIBRARY_SEARCH_DEFAULT_DIRS;
+  const char* const filename = libraryName ? libraryName : "vulkan-1.dll";
+  if (!(loader->libvulkan = LoadLibraryEx(filename, NULL, flags))) {
     free(loader);
     return NULL;
   }
diff --git a/src/x11_vulkan.c b/src/x11_vulkan.c
index 54b1218..834ac37 100644
--- a/src/x11_vulkan.c
+++ b/src/x11_vulkan.c
@@ -26,9 +26,11 @@ struct PuglVulkanLoaderImpl {
 };
 
 PuglVulkanLoader*
-puglNewVulkanLoader(PuglWorld* PUGL_UNUSED(world))
+puglNewVulkanLoader(PuglWorld*        PUGL_UNUSED(world),
+                    const char* const libraryName)
 {
-  void* const libvulkan = dlopen("libvulkan.so", RTLD_LAZY);
+  const char* const filename  = libraryName ? libraryName : "libvulkan.so";
+  void* const       libvulkan = dlopen(filename, RTLD_LAZY);
   if (!libvulkan) {
     return NULL;
   }
diff --git a/test/test_vulkan.c b/test/test_vulkan.c
index 1376676..3a7c612 100644
--- a/test/test_vulkan.c
+++ b/test/test_vulkan.c
@@ -157,7 +157,7 @@ main(int argc, char** argv)
   PuglWorld* const world = puglNewWorld(PUGL_PROGRAM, PUGL_WORLD_THREADS);
 
   PuglView* const         view   = puglNewView(world);
-  PuglVulkanLoader* const loader = puglNewVulkanLoader(world);
+  PuglVulkanLoader* const loader = puglNewVulkanLoader(world, NULL);
   const PuglTestOptions   opts   = puglParseTestOptions(&argc, &argv);
 
   PuglTest test = {world, view, VK_NULL_HANDLE, VK_NULL_HANDLE, opts, false};