Publish Interface to Shared C++ Library on Linux

This example creates a MATLAB^® interface to a C++ library matrixOperations for 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.

Verify Supported C++ Compiler

To build the interface, use the same compiler that was used to build the C++ library.

mex -setup cpp

Create Publisher Folder

Create a folder for the MATLAB interface file.

user = "myname"; % Replace "myname" with your user name
pubPath = "/mathworks/home/"+user+"/MATLAB/publisher/matrixexample/";
if ~isfolder(pubPath)
    mkdir(pubPath)
end
cd(pubPath)

Identify C++ Library Files

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

productPath = fullfile(matlabroot,'extern','examples','cpp_interface');
libPath = fullfile(productPath,'glnxa64');
% 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 = 'libmwmatrixOperations.so';

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.

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

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 
'/mathworks/home/myname/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 Linux Interface to C++ Shared Library.

Documentation