Publish Interface to C++ Library Using Source Files

This example creates a MATLAB^® interface to a C++ library declared in the header file matrixOperations.hpp and defined in the C++ source file matrixOperations.cpp. MATLAB provides these source files for you to use in this example. The files are in this folder:

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

This example creates the shared library file. For an example that uses the shared library file prebuilt by MATLAB, see Publish Interface to Shared C++ Library on Windows.

Verify Selected C++ Compiler

You can use any C++ compiler supported by MathWorks. To verify that you have a C++ compiler, type:

mex -setup cpp

This example uses the Microsoft Visual C++ 2017 compiler.

Generate Definition File

Identify the names and paths to the C++ library artifacts.

productPath = fullfile(matlabroot,'extern','examples','cpp_interface');
hppFile = 'matrixOperations.hpp';
cppFile = 'matrixOperations.cpp';

Call clibgen.generateLibraryDefinition.

clibgen.generateLibraryDefinition(fullfile(productPath,hppFile),...
    "SupportingSourceFiles",fullfile(productPath,cppFile),...
    "IncludePath",productPath,...
    "ReturnCArrays",false) % treat output as MATLAB arrays

Using Microsoft Visual C++ 2017 compiler.
Generated definition file definematrixOperations.mlx and data file 'matrixOperationsData.xml' 
contain definitions for 10 constructs supported by MATLAB.
5 construct(s) require(s) additional definition. To include these construct(s) in the interface, 
edit the definitions in definematrixOperations.mlx.
Build using build(definematrixOperations).

Define Missing Constructs

To define the missing constructs, click the link in the generateLibraryDefinition output message to edit the definitions in definematrixOperations.mlx. For information about editing this file and examples for specifying arguments, see Define Missing Information for MATLAB Signatures.

Search the definition file for the setMat method and uncomment the statements defining it. To define the src argument, in this defineArgument statement, replace <SHAPE> with "len".
```
defineArgument(setMatDefinition, "src", "clib.array.matrixOperations.Int", "input", "len");
```
In the method getMat, define the RetVal output by replacing <SHAPE> with "len".
```
defineOutput(getMatDefinition, "RetVal", "int32", "len");
```

In the method copyMat, define the dest argument by replacing <SHAPE> with "len".

defineArgument(copyMatDefinition, "dest", "clib.array.matrixOperations.Int", "input", "len");

In the function addMat, define the mat argument in function addMat by replacing <SHAPE> with 1.
```
defineArgument(addMatDefinition, "mat", "clib.matrixOperations.Mat", "input", 1);
```

In the function updateMatBySize, define the arr argument by replacing <SHAPE> with "len".

defineArgument(updateMatBySizeDefinition, "arr", "clib.array.matrixOperations.Int", "input", "len");

Save and close the definition file.

Validate Library

definematrixOperations;

View Functionality

summary(definematrixOperations)

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)
    int32 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)

Build Interface and Add to MATLAB Path

build(definematrixOperations)

Building interface file 'matrixOperationsInterface.dll'.
Interface file 'matrixOperationsInterface.dll' built in folder 'C:\Users\matrixOperations'.
To use the library, add the interface file folder to the MATLAB path.

Click the interface file folder link to add the interface to the path. Alternatively, type:

addpath('matrixOperations')

View Help

At the MATLAB command prompt, display help for the interface. Type this command to load the package.

doc clib.matrixOperations.Mat

To display the members of the package, type:

doc clib.matrixOperations

To display signatures for the package function, click the links for addMat, updateMatByX, and updateMatBySize.

To display information about class clib.matrixOperations.Mat, click the link for Mat.

Call Library Functions

Test the functions in the interface. For example, type:

matObj = clib.matrixOperations.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 = 1×5 int32 row vector    
   1   2   3   4   5