Header and C++ Compiled Library Files on Windows

This example shows how to create a MATLAB^® interface to a C++ library for Windows^® by calling clibPublishInterfaceWorkflow. For this example, the library is defined by header file matrixOperations.hpp and import library file matrixOperations.lib. MATLAB provides the library files in this folder:

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

For this example, the folder is:

ans = 
    "C:\Program Files\MATLAB\R2023a\extern\examples\cpp_interface"

To create an interface named matrixlib for this library, follow these steps in a workflow script: generate a library definition file, define any missing constructs, build the interface, and then test the interface. If you need to iterate over the publishing process, you can take additional steps to restore parameters and enable out-of-process execution mode. You can then share your published interface with other users.

Create Workflow Script

Navigate to a writeable folder and call clibPublishInterfaceWorkflow. In the dialog box, specify the name of the workflow script, for example, publishmatrixlib.mlx. The workflow script has steps to help you publish the interface. Use the script to save the parameters for publishing the interface. You can use the same script on all platforms.

Note

The workflow script allows you to repeatedly generate, define, build, and test an interface during multiple MATLAB sessions. However, the script does not save edits to library definition files recreated using the Overwrite existing definition files option.

Step 1: GENERATE

First, generate the library definition file. The workflow script contains the Generate C++ Interface Live Editor task for this step. Use this task to select the files that make up the library and to set options for generating the library definition file.

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 writeable folder.

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 definition file, 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 File

Click Generate definition file. The script displays its progress and creates the library definition file definematrixlib.m in the specified output folder.

C++ compiler set to 'MinGW64 Compiler (C++)'.
Definition file definematrixlib.m contains definitions for 10 constructs supported by MATLAB.
- 5 constructs are fully defined.
- 5 constructs partially defined and commented out.

To include the 5 undefined constructs in the interface, uncomment and complete the definitions in definematrixlib.m.
To build the interface, call build(definematrixlib).

MATLAB Interface to matrixlib Library

Class clib.matrixlib.Mat

  Constructors:
    clib.matrixlib.Mat(clib.matrixlib.Mat)
    clib.matrixlib.Mat()

  Methods:
    uint64 getLength()
    
  No Properties defined

Functions
clib.matrixlib.updateMatByX(clib.matrixlib.Mat,int32)

Enable Tools for Development over Multiple Sessions

While publishing the interface, you might iterate over the steps, close and reopen the publishmatrixlib.mlx script, or restart MATLAB. Follow the instructions in these sections to help you with these workflows.

Preserve workspace variables across MATLAB sessions. In the Restore library definition section, set the outputFolderPath variable to the value in the Output folder parameter. Set the libraryNameForInterface variable to the Name of interface library parameter matrixlib. Then run the section. For more information, see Restore Library Definition.
Consider running the Enable out-of-process execution mode section. Using this mode while developing an interface eliminates the need to restart MATLAB while testing. After calling functionality in your library, you can unload the library by running the Unload out-of-process library section. For more information, see Load Out-of-Process C++ Library

Step 2: DEFINE

When you created the library definition file, MATLAB reported that five constructs are partially defined. To completely define the functionality, edit the definematrixlib.m file. To edit the file, run the DEFINE section.

Scroll through the library definition file to find blocks of commented code for these constructs. MATLAB cannot automatically determine the size of arguments used by these functions.

setMat — C++ method for class Mat
getMat — C++ method for class Mat
copyMat — C++ method for class Mat
addMat — C++ function
updateMatBySize — C++ function

Based on the documentation of the matrixOperations library, you can provide values for <SHAPE> in the argument definition statements. For more information, see Define Missing SHAPE Parameter.

For each construct, uncomment the statements defining it.

Replace <SHAPE> arguments with these values.

Construct	Argument Name	Argument C++ Definition	Description	Replace `<SHAPE>` with Value
`setMat`	`src`	`int [] src`	The length of the matrix is defined by the input argument `len`.	`"len"`
`getMat`	`RetVal`	`int const *`	The length of the output argument is defined by the input argument `len`.	`"len"`
`copyMat`	`dest`	`int * dest`	The length of `dest` is defined by the input argument `len`.	`"len"`
`addMat`	`mat`	`Mat const * mat`	The function takes a single `mat` argument.	`1`
`updateMatBySize`	`arr`	`int * arr`	The length of `arr` is defined by the input argument `len`.	`"len"`

Save and close the definition file.
To validate the edits you made in the file, run the Confirm edits and run summary section. Fix any reported errors in the file. The summary function shows that the interface now includes setMat, getMat, copyMat, addMat, and updateMatBySize.

MATLAB Interface to matrixlib Library

Class clib.matrixlib.Mat

  Constructors:
    clib.matrixlib.Mat(clib.matrixlib.Mat)
    clib.matrixlib.Mat()

  Methods:
    setMat(clib.array.matrixlib.Int)
    clib.array.matrixlib.Int getMat(uint64)
    uint64 getLength()
    copyMat(clib.array.matrixlib.Int)

  No Properties defined

Functions
int32 clib.matrixlib.addMat(clib.matrixlib.Mat)
clib.matrixlib.updateMatByX(clib.matrixlib.Mat,int32)
clib.matrixlib.updateMatBySize(clib.matrixlib.Mat,clib.array.matrixlib.Int)

Step 3: BUILD

To build the matrixlib interface to the library, run the BUILD section of the script.

Building interface file 'matrixlibInterface.dll' for clib interface 'matrixlib'.
Interface file 'matrixlibInterface.dll' built in folder 'C:\Users\Documents\MATLAB\matrixlib'.

To use the library, add the interface file folder to the MATLAB path.
addpath('C:\Users\Documents\MATLAB\matrixlib')

Note

You can repeat the generate, define, and build steps. However, once you display help for or call functions in the library, you cannot update the definematrixlib definition file in the same MATLAB session. Either restart MATLAB or create a new definition file by changing the Name of interface library parameter in the Select configuration section.

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++ Library In-Process or Out-of-Process.

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

retMat = 

  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++ 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.