Publish Platform-Independent MATLAB Interface

R2026b

This example shows how to create a MATLAB^® interface to a C++ library for Windows^®, Linux^®, and macOS. For more information, see How to Publish a MATLAB Interface to a C/C++ Library.

For this example, the library is defined by header file matrixOperations.hpp and an import library file matrixOperations. MATLAB provides these files in this folder:

fullfile(matlabroot,"extern","examples","cpp_interface")

To create an interface named matrixlib for this library, follow these steps in a workflow script: generate a clibgen.api.InterfaceDefinition object, define any missing constructs, build the interface, and then test the interface. You can then share your published interface with other users.

Step 1: GENERATE

Call clibPublishInterfaceWorkflow to generate the interface definition object.

Select files

The library is defined by the matrixOperations.hpp header file and the Windows matrixOperations.lib library file. The Library type is Headers and compiled library files, which is the default setting.

To set the Library start path, browse to the folder fullfile(matlabroot,"extern","examples","cpp_interface") and click Select Folder.

To select the header file, click Browse to open the file matrixOperations.hpp.

The header file depends on the cppshrhelp.hpp header file. Navigate to the folder in Library start path and click Select Folder.

To select the compiled library file, browse to the win64\mingw64 folder and open the matrixOperations.lib file.

Select configuration

In this example, the C++ compiler is set to MinGW64 Compiler (C++).

Change Name of interface library to matrixlib. This name is used with clib to call functionality from MATLAB. For example, to create a library object Mat, from the command prompt, enter:

clib.matrixlib.Mat

Verify that Output folder is a writable folder.

Before R2026b: Select the Overwrite existing definition files check box so that you can recreate the definition file while developing the interface.

Specify optional C++ library settings

Building the interface to this library does not require optional C++ library settings.

Specify optional definition configurations

Building the interface to this library does not require optional definition configurations.

Display results

By default, when you generate a clibgen.api.InterfaceDefinition object, the function displays available constructs (classes and functions in the library). While developing the interface, also select the Show unavailable constructs check box so that you can see what constructs are not included because they are unsupported.

Generate Definition

Click Generate definition. The script displays its progress and creates the clibgen.api.InterfaceDefinition object in the specified output folder.

Step 2: DEFINE

When you created the clibgen.api.InterfaceDefinition object, MATLAB reported that five constructs are partially defined. To completely define the functionality, refer to the steps Inspect Incomplete Class and Inspect Incomplete Functions in the Publish MATLAB Interface Programmatically example.

Step 3: BUILD

Run the BUILD section of the script.

Step 4: TEST

Set up and copy run-time libraries

Run the Set up and copy run-time libraries section. This library does not have additional run-time dependencies, so you do not need to modify the commands.

Enable out-of-process execution mode

If the definition file needs to change, run this command to set up the ability to call the interface library out of process so that you do not have to restart MATLAB. For more information, see Load C/C++ Library In-Process or Out-of-Process.

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

Call help on interface library

To display help for the interface library, run the Call help on interface library section.

Write code to call and test interface library

Use the code section in Write code to call and test interface library to write these tests:

matObj = clib.matrixlib.Mat;   % Create a Mat object
intArr = [1,2,3,4,5];
matObj.setMat(intArr);     % Set the values to intArr
retMat = matObj.getMat(5);  % Display the values
int32(retMat)

ans = 

  read-only clib.array.matrixlib.Int with properties:

    Dimensions: 5
     Resizable: 0

Share Interface

To share the interface with another MATLAB user, create a toolbox installation (.mltbx) file. Using the instructions in Distribute MATLAB Interface to C/C++ Library:

Set the toolbox folder to your matrixlib folder, which contains the interface file matrixlibInterface.dll.
Put the compiled library file matrixOperations.dll in the same folder.
Identify the namespace (calling syntax) as clib.matrixlib.