Publish Interface to Shared C++ Library on Windows

This example creates a MATLAB^® interface to a C++ library matrixOperations for Windows^®. For a Linux^® example, see Publish Interface to Shared C++ Library on Linux. The process includes:

Generate a definition file (definematrixlib.mlx).
Modify the definition file to complete any definitions that MATLAB is not able to automatically convert.
Build the library interface.

For more information, see Build MATLAB Interface to C++ Library.

MATLAB provides a C++ library and header files for you to use in this example. The files are in this folder and its subfolders:

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

Generate Definition File

The first step for generating the interface is preparing the necessary folders and files and calling clibgen.generateLibraryDefinition to generate the definition file.

Verify Selected C++ Compiler

This example uses the MinGW64 compiler. Verify that you have this compiler selected.

mex -setup cpp

Alternatively, you can select the Visual Studio^® compiler. Set the value for libPath as specified in the Identify C++ Library Files step.

Create Publisher Folder

Create a folder for the MATLAB interface file. This is an optional step.

pubPath = [pwd + "\matrixexample"];
if ~isfolder(pubPath)
    mkdir(pubPath)
end
cd(pubPath)

Identify C++ Library Files

Identify the names and paths to C++ library artifacts. The shared library is built with a specific compiler. There are two versions of the library. One is built with the MinGW64 compiler and the other with the Microsoft Visual Studio 2017 compiler. Set the value of libPath based on your selected compiler.

productPath = fullfile(matlabroot,"extern","examples","cpp_interface");

% Link to library built with MinGW-w64 compiler
libPath = fullfile(productPath,"win64","mingw64");
% To link to library built with the Visual Studio compiler, use this path instead:
% libPath = fullfile(productPath,"win64","microsoft");

% Header file name
hppFile = "matrixOperations.hpp";
% Full path to folder containing all header files
hppPath = productPath;
% Full path to folder containing include files
iPath = hppPath;
% Library file name
libFile = "matrixOperations.lib";

Name the Interface

By default, MATLAB creates an interface called matrixOperations. For this example, change the name to matrixlib.

libname = "matrixlib";

Call clibgen.generateLibraryDefinition

To create the interface, you must specify:

Header file name matrixOperations.hpp and its location.
Path to the folder containing the include files, using the 'IncludePath' argument.
Name and location of the library file matrixOperations.lib, using the 'Libraries' argument.

Optionally, you can:

Rename the library, using the 'PackageName' argument.
Display generation messages, using the 'Verbose' argument.

clibgen.generateLibraryDefinition(fullfile(hppPath,hppFile),...
"IncludePath", iPath,... 
"Libraries", fullfile(libPath,libFile),... 
"PackageName", libname,...
"ReturnCArrays",false,... % treat output as MATLAB arrays
"Verbose",true)

Warning: Some C++ language constructs in the files for generating interface file 
are not supported and not imported.

Using MinGW64 Compiler (C++) compiler.
Generated definition file definematrixlib.mlx and data file 'matrixlibData.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 definematrixlib.mlx.
Build using build(definematrixlib).

Validate the library.

definematrixlib;

View Functionality

Although some constructs require additional definition, you can view the available functionality. If this functionality is sufficient for your needs, then you can continue with the Build Library Interface step. Otherwise, continue with the step Define Missing Constructs.

summary(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)

Define Missing Constructs

To define the missing constructs, click the link in the generateLibraryDefinition output message to edit the definitions in definematrixlib.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.matrixlib.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.matrixlib.Int", "input", "len");

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

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

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

Save and close the definition file.

Build Library Interface

Create the MATLAB interface file matrixlibInterface.dll.

build(definematrixlib)

Building interface file 'matrixlibInterface.dll'.
Interface file 'matrixlibInterface.dll' built in folder 
'C:\Documents\matrixexample\matrixlib'.
To use the library, add the interface file folder to the MATLAB path.

Be sure to click the link in the message to add the interface file to the path.

Test the Interface

To test the interface, see Call Functions in Windows Interface to C++ Shared Library.

Documentation