clibConfiguration

Set run-time configuration parameters for C++ library interface

Since R2023a

collapse all in page

Syntax

libraryconfig = clibConfiguration(libname)
libraryconfig = clibConfiguration(libname,Name=Value)

Description

libraryconfig = clibConfiguration(libname) returns the environment configuration for the MATLAB® interface to the specified C++ library as a CLibraryConfiguration object.

example

libraryconfig = clibConfiguration(libname,Name=Value) sets one or more system environment parameters for the MATLAB interface to the specified C++ library. The settings persist across different MATLAB sessions.

example

Examples

collapse all

Suppose that you built an interface libnameInterface.dll in C:\work on the MATLAB path for a C++ library libname. Assuming that the library is not loaded, display the configuration for the library.

libraryconfig = clibConfiguration("libname")
libraryconfig =

      CLibraryConfiguration for libname with properties:

        InterfaceLibraryPath: "C:\work"
                   Libraries: ""
                      Loaded: 0
               ExecutionMode: inprocess

Suppose that you built an interface mylibInterface.dll in C:\work on the MATLAB path for a C++ library mylib. By default, the library interface configuration uses in-process execution mode. Assuming that the library is not loaded, configure the library interface to use out-of-process.

libraryconfig = clibConfiguration("mylib",ExecutionMode="outofprocess")
libraryconfig =

      CLibraryConfiguration for mylib with properties:

            InterfaceLibraryPath: "C:\work"
                       Libraries: ""
                          Loaded: 0
                   ExecutionMode: outofprocess
OutOfProcessEnvironmentVariables: dictionary (string ⟼ string) with no entries

The libmat library included with MATLAB enables the ability to read and write MAT files. Suppose that you want to add the libmat functionality to your MATLAB interface to the C++ library mylib.

First, verify that the execution mode of your interface is "outofprocess".

libraryconfig = clibConfiguration("mylib");
libraryconfig.ExecutionMode
ans = 

  ExecutionMode enumeration

    outofprocess

Identify the path to the shared library libmat based on your Windows® configuration.

libmatPath = fullfile(matlabroot,"extern","lib","win64","compiler","libmat.lib");

Create a dictionary that represents the PATH system environment variable and the library path you want to add. Then confirm the environment variable configuration parameters.

pathVar = dictionary("PATH",libmatPath);

Update the system path to include the shared library by using the clibConfiguration function with the OutOfProcessEnvironmentVariables name-value argument.

libraryconfig = clibConfiguration("mylib",OutOfProcessEnvironmentVariables=pathVar);
libraryconfig.OutOfProcessEnvironmentVariables.keys
libraryconfig.OutOfProcessEnvironmentVariables.values
ans = 

    "PATH"
ans = 

    "C:\Program Files\MATLAB\R2025a\extern\lib\win64\compiler\libmat.lib"

Input Arguments

collapse all

Name of the C++ library, specified as a string scalar or character vector.

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: clibConfiguration("mylib",ExecutionMode="outofprocess",OutOfProcessEnvironmentVariables=dictionary("DYLD_LIBRARY_PATH","/usr/local/bin"))

Execution mode indicating whether to load the library in the same process as MATLAB, specified as "inprocess" or "outofprocess".

The default "inprocess" loads the library in the MATLAB process. Use this mode for performance-critical use cases. Set this mode after you develop and test the interface.

Specifying ExecutionMode as "outofprocess" is useful in these situations:

  • You are developing and testing the library interface, that requires rebuilding the interface in MATLAB.

  • If your C++ library requires a third-party library that is also shipped with MATLAB, but you need a different version of the library, then set an out-of-process execution mode before you use or distribute the interface.

You can interrupt C++ interface out-of-process execution by pressing Ctrl+C. (since R2025a)

MATLAB loads the library when you call your library using the syntax clib.libraryName followed by the library construct type. If ExecutionMode is "inprocess", then you cannot change the interface to the library and reload it into MATLAB. To enable making changes to the interface and reloading in the same session, restart MATLAB, and then call clibConfiguration(libraryName,ExecutionMode="outofprocess").

Since R2025a

System environment variable names and values for the interface to C++ library libname in out-of-process execution mode, specified as a dictionary object, where key-value pairs are defined as follows:

  • keys — The environment variable name or names, specified as a string scalar or string array.

    If keys contains an operating system path variable ("PATH", "LD_LIBRARY_PATH", or "DYLD_LIBRARY_PATH"), the function adds the specified path value to the existing path variable.

  • values — The environment variable value or values, specified as a string scalar or string array.

You can set or view environment variables in out-of-process mode only. To use this name-value argument, you must also specify the ExecutionMode name-value argument as "outofprocess".

Example: OutOfProcessEnvironmentVariables=dictionary(["var1","var2"],["val1","val2"])

Version History

Introduced in R2023a

expand all

See Also

Topics