--- title: "Linkage" canonical: "https://documentation.chaos.com/space/APPSDK/132645333/Linkage" format: markdown --- Here we will discuss how to properly link and load the App SDK and V-Ray dynamic libraries. > ℹ️ Where we refer to *.dll files for Windows, just treat this as lib*.so or lib*.dylib for Linux and macOS. There are four DLL files or groups that need to be loaded at various stages: - The binding library - The main SDK library - VRaySDKLibrary.dll - The rendering core - vray.dll (with a few third party dependency DLLs in the same directory) - The V-Ray render plugin libraries in the `plugins/` subdirectory In most cases this is done with just one line of code, but the API allows for custom file layouts through additional settings. ## **C++** --- There is no binding DLL because the binding is header only. There are two ways to link the main SDK library described in the following subsections: ### Link VRaySDKLibrary at compile-time In this case you need to use the VRaySDKLibrary.lib import library when building on Windows and the -lVRaySDKLibrary linker switch on Linux/macOS. The VRaySDKLibrary dynamic library will have to be on the system paths for loading dynamic libraries before you run the application: PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS. You don't need to define additional preprocessor macros. ### Link VRaySDKLibrary at runtime To avoid having to modify the system search paths you may load the library dynamically at runtime. **Exactly one** of your source files has to define the **VRAY_RUNTIME_LOAD_PRIMARY** macro before including `vraysdk.hpp`. The rest of the sources have to define **VRAY_RUNTIME_LOAD_SECONDARY** before including the header. The VRAY_RUNTIME_LOAD_PRIMARY source file should create a VRayInit instance that lasts for the lifetime of the application. It takes an optional path to VRaySDKLibrary.dll, including the filename. The runtime loading version of VRayInit also provides a getSDKLibraryErrorString() method for diagnosing failures. ## **.Net** --- The .Net binding is implemented in two assemblies: `VRaySDK.Net.dll` and `VRaySDK.Net.Plugins.dll` that your application has to reference. The second assembly can be omitted if you don't need the concrete Plugin classes, but usually it is needed. ## **Python** --- The Python binding is implemented in `vray.pyd` on Windows or `vray.so` on Linux and macOS. It should either be installed in your site-packages directory or you would have to add its location to the PYTHONPATH environment variable. ## **Node.js** --- The Node.js binding is implemented in the `VRay.node` binary file, but should be loaded through the `vray.js` script which adds a few helpers to it. ## **VRaySDKLibrary runtime loading: .Net, Python, Node.js** You can use a static method to add a search path for VRaySDKLibrary.dll if it is not in the system PATH. You have to do this **before** calling any other App SDK methods. **.Net** Use `Globals.SetSDKLibraryPath(search_path)`. **Python** and **Node.js** When you import or require the vray module, it will try to load VRaySDKLibrary.dll. It may fail.** **You can call `vray.setSDKLibraryPath(search_path)` to specify a search path and force VRaySDKLibrary.dll (re)loading. The function returns 'true' on success. You can get extended info by calling `vray.getSDKLibraryErrorString()`. ## **V-Ray engine** --- The directory containing vray.dll and the other DLLs from the original App SDK `bin` directory needs to be on the system library search path (PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH). The `VRAY_PATH` environment variable can be set to an alternative location. **IMPORTANT**: The `VRAY_PATH` variable may be set on the user system from another V-Ray install (such as V-Ray Standalone). Don't rely on it being empty! It can cause crashes due to loading mismatched DLLs. You should also make sure PATH/LD_LIBRARY_PATH/DYLD_LIBRARY_PATH does not contain other V-Ray paths on the system or that your path is at the front. This is how the render plugins are loaded: 1. A string containing semicolon separated paths is constructed from the optional `RendererOptions::pluginLibraryPath` parameter - this is usually empty, but allows for overriding the defaults. 2. The value of the `VRAY_PATH` environment variable is appended with "/plugins" and this is appended to the list. If the variable is not set, the path of VRaySDKLibrary is appended instead (again appended with "/plugins"). 3. The path list is passed to the V-Ray plugin manager to load the plugin classes from `vray_*.dll` or `libvray_*.so`. ## **Custom V-Ray plugins** --- If you have third party V-Ray render plugins (textures, geometry or anything) you should either copy them in the same `plugins` directory or add their directory to the `RendererOptions::pluginLibraryPath` parameter as described above. The file names should match the template `vray_*.dll` or `libvray_*.so`. ## **GPU engine** --- The `RendererOptions::pluginLibraryPath` parameter could be optionally set to a path, which contains the rt_cuda.dll/so and rt_opencl.dll/so libraries if they are not at their default location next to vray.dll and VRaySDKLibrary.dll. ## **C/C++ Runtime** --- You should make sure that the respective runtime or a compatible one is available where you deploy the SDK. Currently the App SDK is built using: - The Visual Studio 2017 runtime on Windows (vcruntime140.dll, msvcp140.dll) - glibc 2.17 on Linux - macOS SDK 10.9 (macOS x64) - macOS SDK 11.1 (macOS universal, with support for macOS 10.14 and higher) ## **Normal usage example**
Python ```python # The directory containing the vray shared object - vray.pyd/so - should be present in the PYTHONPATH environment variable import vray renderer = vray.VRayRenderer() ```
C++ ```c++ // link against VRaySDKLibrary.lib or with -lVRaySDKLibrary and have VRaySDKLibrary accessible through the OS library path #include "vraysdk.hpp" void main() { VRay::VRayInit init(NULL, true); VRay::VRayRenderer renderer; } ```
C#.NET ```csharp // VRaySDK.Net.dll has a reference in the current .csproj using VRay; class Program { static void Main(string[] args) { VRayRenderer renderer = new VRayRenderer(); } } ```
Node.js ```javascript // vray.js is in node_modules with the rest of the files from the App SDK package var vray = require('vray'); var renderer = vray.VRayRenderer(); ```
--- ## **Advanced usage example** ---
Python ```python # The directory containing the vray shared object - vray.pyd/so - should be present in the PYTHONPATH environment variable import vray # These paths are optional. Only pass them if it is necessary for your project # You have to call this before any other API methods vray.setSDKLibraryPath("/some/path") # vray.dll should be here or on the OS path renderer = vray.VRayRenderer(pluginLibraryPath="/some/other/path") ```
C++ ```c++ // main.cpp #define VRAY_RUNTIME_LOAD_PRIMARY #include "vraysdk.hpp" void main() { // These paths are optional. Only pass them if it is necessary for your project // You have to call this before any other API methods VRay::VRayInit init("C:/some/path/VRaySDKLibrary.dll", true); // vray.dll should be here or on the OS path VRay::RendererOptions options; options.pluginLibraryPath = "C:/some/other/path"; VRay::VRayRenderer renderer(options); } ------------------------ // other.cpp #define VRAY_RUNTIME_LOAD_SECONDARY #include "vraysdk.hpp" ```
C#.NET ```csharp // VRaySDK.Net.dll has a reference in the current .csproj using VRay; class Program { static void Main(string[] args) { // These paths are optional. Only pass them if it is necessary for your project // You have to call this before any other API methods Globals.SetSDKLibraryPath("C:/some/path"); // vray.dll should be here or on the OS path RendererOptions options = new RendererOptions(); options.PluginLibraryPath = "C:/some/other/path"; VRayRenderer renderer = new VRayRenderer(options); } } ```
Node.js ```javascript // vray.js is in node_modules with the rest of the files from the App SDK package var vray = require('vray'); // These paths are optional. Only pass them if it is necessary for your project // You have to call this before any other API methods vray.setSDKLibraryPath("/some/path"); // vray.dll should be here or on the OS path var renderer = vray.VRayRenderer({ "pluginLibraryPath": "/some/other/path" }); ```
## **Removing unnecessary DLLs** --- You may want to clean up the binary folder to reduce the size of your application's installation. You can remove some of the files there if you know for a fact that you will never use the features that require them: - Some of the `plugins/vray_*.dll` files are large and potentially unused: MtlMDL (together with libvraymdl and libvrayfreeimage in the parent directory), mtlvrmat, ptexbaker, phxshader (together with field3dio_vray and openvdbio_vray), BRDFScanned, GeomBifrost, SphericalHarmonics, TexXSI, vrsceneloader (this is a plugin for embedding scenes, don't mistake it with the normal scene loading functionality). - You can remove `rt_cuda.dll` and/or `rt_opencl.dll` if you're not going to support GPU rendering. The `vray_gpu_device_select` application is for GPU selection too. - The `bin/osl*` and `bin/libosl*` files are only needed by OSL materials.