Header and C++ Source Files
This example shows how to create a MATLAB® interface to a C++ library declared in the header file
matrixOperations.hpp and defined in the C++ source file
matrixOperations.cpp by calling
MATLAB provides the source files in this folder:
For this example, the folder is:
ans = "C:\Program Files\MATLAB\R2023a\extern\examples\cpp_interface"
Create Workflow Script
Navigate to a writeable folder (for example,
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.
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.
The library is defined by the
matrixOperations.hpp header file and
matrixOperations.cpp source file. Select
Headers and source
files as the Library type.
To set the Library start path, browse to the folder
fullfile(matlabroot,"extern","examples","cpp_interface") and click
To select the header file, use the browse button to open the
The header file depends on the
cppshrhelp.hpp header file. Navigate
to the folder in Library start path and click Select
To select the supporting source file, use the browse button to open the
In this example, the C++ compiler is set to
The default Name of interface library is
matrixOperations. This name is used with
call functionality from MATLAB. For example, to create a library object
Mat, from the
command prompt, type:
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
Select the Treat .h files as C header files parameter.
Specify optional definition configurations
Building the interface to this library does not require optional definition configurations.
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 might need more information in order to be included.
Generate Definition File
Click Generate definition file. The script displays its progress
and creates the library definition file
definematrixOperations.m in the
specified output folder.
C++ compiler set to 'MinGW64 Compiler (C++)'. Definition file definematrixOperations.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 definematrixOperations.m. To build the interface, call build(definematrixOperations).
MATLAB Interface to matrixOperations Library Class clib.matrixOperations.Mat Constructors: clib.matrixOperations.Mat(clib.matrixOperations.Mat) clib.matrixOperations.Mat() Methods: uint64 getLength() No Properties defined Functions clib.matrixOperations.updateMatByX(clib.matrixOperations.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
outputFolderPathvariable to the value in the Output folder parameter. Set the
libraryNameForInterfacevariable 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 Missing Constructs
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
getMat— C++ method for class
copyMat— C++ method for class
addMat— C++ package function
updateMatBySize— C++ package 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.
<SHAPE>arguments with these values.
Argument C++ Definition
int  src
The length of the matrix is defined by the input argument
int const *
The length of the output argument is defined by the input argument
int * dest
The length of
destis defined by the input argument
Mat const * mat
The function takes a single
int * arr
The length of
arris defined by the input argument
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
summaryfunction shows that the interface now includes
MATLAB Interface to matrixOperations Library Class clib.matrixOperations.Mat Constructors: clib.matrixOperations.Mat(clib.matrixOperations.Mat) clib.matrixOperations.Mat() Methods: setMat(clib.array.matrixOperations.Int) clib.array.matrixOperations.Int getMat(uint64) uint64 getLength() copyMat(clib.array.matrixOperations.Int) No Properties defined Functions int32 clib.matrixOperations.addMat(clib.matrixOperations.Mat) clib.matrixOperations.updateMatByX(clib.matrixOperations.Mat,int32) clib.matrixOperations.updateMatBySize(clib.matrixOperations.Mat,clib.array.matrixOperations.Int)
Step 3: BUILD
To build the
matrixOperations interface to the library, run the
BUILD section of the script.
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
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
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
matrixOperationsfolder, which contains the interface file
Put the compiled library file
matrixOperations.dllin the same folder.
Identify the namespace (calling syntax) as