Generally, when loading DLLs on a path that is not on the search path, e.g., from a subdirectory
of the application, the path should be prepended to the DLL name passed to the load function,
e.g., "dlls\\SDL2.dll". If setCustomLoaderSearchPath(".\\dlls") is called first, then the subdirectory
will become part of the DLL search path and the path may be omitted from the load function. (Be
aware that ".\\dlls" is relative to the current working directory, which may not be the application
directory, so the path should be constructed appropriately.)
Some DLLs may depend on other DLLs, perhaps even attempting to load them dynamically at run time
(e.g., SDL2_image only loads dependencies such as libpng if it is initialized at run time with
support for those dependencies). In this case, if the DLL and its dependencies are placed in a subdirectory and
loaded as e.g., "dlls\\SDL2_image.dll", then the dependencies will not be found; the
system loader will look for them on the regular DLL search path. When that happens, the solution
is to call setCustomLoaderSearchPath with the subdirectory before initializing the library.
Calling this function with null as the argument will reset the default search path.
When the function returns false, the relevant ErrorInfo is added to the global error list and can
be retrieved by looping through the array returned by the errors function.
When placing DLLs in a subdirectory of the application, it should be considered good practice to
call setCustomLoaderSearchPath to ensure all DLLs load properly. It should also be considered good
practice to reset the default search path once all DLLs are loaded.
This function is only available on Windows, so any usage of it should be preceded with
version(Windows).
Adds a path to the default search path on Windows, replacing the path set in a previous call to the same function.
Any path added via this function will be added to the default DLL search path as documented at https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setdlldirectoryw.
Generally, when loading DLLs on a path that is not on the search path, e.g., from a subdirectory of the application, the path should be prepended to the DLL name passed to the load function, e.g., "dlls\\SDL2.dll". If setCustomLoaderSearchPath(".\\dlls") is called first, then the subdirectory will become part of the DLL search path and the path may be omitted from the load function. (Be aware that ".\\dlls" is relative to the current working directory, which may not be the application directory, so the path should be constructed appropriately.)
Some DLLs may depend on other DLLs, perhaps even attempting to load them dynamically at run time (e.g., SDL2_image only loads dependencies such as libpng if it is initialized at run time with support for those dependencies). In this case, if the DLL and its dependencies are placed in a subdirectory and loaded as e.g., "dlls\\SDL2_image.dll", then the dependencies will not be found; the system loader will look for them on the regular DLL search path. When that happens, the solution is to call setCustomLoaderSearchPath with the subdirectory before initializing the library.
Calling this function with null as the argument will reset the default search path.
When the function returns false, the relevant ErrorInfo is added to the global error list and can be retrieved by looping through the array returned by the errors function.
When placing DLLs in a subdirectory of the application, it should be considered good practice to call setCustomLoaderSearchPath to ensure all DLLs load properly. It should also be considered good practice to reset the default search path once all DLLs are loaded.
This function is only available on Windows, so any usage of it should be preceded with version(Windows).