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 (definemyPkg.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 library 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.

Create Publisher Folder

Create a folder H:\Documents\MATLAB\publisher\matrixexample for the MATLAB interface file.

pubPath = 'H:\Documents\MATLAB\publisher\matrixexample';
if ~isfolder(pubPath)
    mkdir(pubPath)
end
cd(pubPath)

Verify Selected C++ 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. 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 library files step.

Identify C++ Library Files

Identify the names and paths to C++ library artifacts. The library is built with a specific compiler. This example assumes you use the MinGW-w64 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 myPkg.

myPkg = 'myPkg';

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 shared library file matrixOperations.lib, using the 'Libraries' argument.

Optionally, you can specify:

Library name, using the 'PackageName' argument.
Display generation messages, using the 'Verbose' argument.

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

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

Validate the library.

definemyPkg

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

MATLAB Interface to myPkg1 Library

Class clib.myPkg1.Mat

  Constructors:
    clib.myPkg1.Mat()
    clib.myPkg1.Mat(clib.myPkg1.Mat)

  Methods:
    uint64 getLength()

  No Properties defined

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

Define Missing Constructs

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

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

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

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

Save and close the definition file.

Build Library Interface

Create the MATLAB interface file myPkgInterface.dll.

build(definemyPkg)

Building interface file 'myPkgInterface.dll'.
Interface file 'myPkgInterface.dll' built in folder 
'H:\Documents\MATLAB\publisher\matrixexample\myPkg'.
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