Publish MATLAB Interface Programmatically

R2026b

This example shows how to programmatically create a MATLAB^® interface to a C++ library declared in the header file matrixOperations.hpp and defined in the C++ source file matrixOperations.cpp. For more information, see How to Publish a MATLAB Interface to a C/C++ Library.

Save these MATLAB commands in a workflow script, for example publishmatrix.m, which you can modify for updates and future enhancements or to integrate with a CI (continuous integration) workflow.

Create Interface Configuration

Set the library start path and create a clibgen.api.InterfaceConfiguration object.

rootpath = fullfile(matlabroot,"extern","examples","cpp_interface");
icfg = clibgen.api.InterfaceConfiguration("matrix");
icfg.HeaderFiles = fullfile(rootpath,"matrixOperations.hpp");

Create Interface Definition

Create a clibgen.api.InterfaceDefinition object.

idef = clibgen.api.InterfaceDefinition(icfg);
idef.SourceFiles = fullfile(rootpath,"matrixOperations.cpp");
idef.Libraries = fullfile(rootpath,'win64/mingw64/matrixOperations.lib');

Display the results. The IncompleteClasses and IncompleteFunctions properties indicate constructs that need definition.

idef

idef = 
  Buildable InterfaceDefinition with properties:

                 Classes: [1×1 clibgen.api.ClassDefinition]
               Functions: [1×3 clibgen.api.FunctionDefinition]
                   Enums: [1×0 clibgen.api.EnumDefinition]

           InterfaceName: "matrix"
               Libraries: "C:\Program Files\MATLAB\R2026b\matlab\extern\examples\cpp_interface\win64\mingw64\matrixOperations.lib"
             SourceFiles: "C:\Program Files\MATLAB\R2026b\matlab\extern\examples\cpp_interface\matrixOperations.cpp"

       IncompleteClasses: [1×1 clibgen.api.ClassDefinition]
     IncompleteFunctions: [1×2 clibgen.api.FunctionDefinition]

      UnsupportedClasses: [1×0 clibgen.api.UnsupportedClass]
    UnsupportedFunctions: [1×0 clibgen.api.UnsupportedFunction]

  Show all properties

Inspect Incomplete Class

Identify the incomplete class.

idef.IncompleteClasses

ans = 
  ClassDefinition with properties:

                    CPPName: "Mat"
                 MATLABName: "clib.matrix.Mat"
       HasIncompleteMembers: true
    IsConstructibleInMATLAB: true
                   Included: true

  Show all properties

Click the Show all properties link.

                   CPPName: "Mat"
                 MATLABName: "clib.matrix.Mat"
               Constructors: [1×2 clibgen.api.ConstructorDefinition]
                    Methods: [1×4 clibgen.api.MethodDefinition]
                 Properties: [1×0 clibgen.api.PropertyDefinition]
     IncompleteConstructors: [1×0 clibgen.api.ConstructorDefinition]
          IncompleteMethods: [1×3 clibgen.api.MethodDefinition]
       IncompleteProperties: [1×0 clibgen.api.PropertyDefinition]
       HasIncompleteMembers: true
    IsConstructibleInMATLAB: true
                Description: "clib.matrix.Mat    Representation of C++ class Mat."
        DetailedDescription: ""
                   Included: true

The class has three incomplete methods shown in the IncompleteMethods property.

clsDef = idef.findClass("Mat");
clsDef.IncompleteMethods

ans = 
  1×3 MethodDefinition array with properties:

    CPPName
    MATLABName
    Overloaded
    OwningClassName
    CPPSignature
    MATLABSignature
    CPPInputs
    CPPOutput
    Status
    Included

  Display as table

Click the Display as table link to identify the methods.

    CPPName     MATLABName    Overloaded      Status      Included
    _________    __________    __________    __________    ________

    "setMat"     "setMat"        false       Incomplete     false  
    "getMat"     "getMat"        false       Incomplete     false  
    "copyMat"    "copyMat"       false       Incomplete     false

Inspect `setMat` Method

Display the properties of the setMat method.

methDef = clsDef.findMethod("setMat")

methDef = 

  MethodDefinition with properties:

            CPPName: "setMat"
         MATLABName: "setMat"
         Overloaded: false
    OwningClassName: "Mat"
       CPPSignature: "void Mat::setMat(int [] src,size_t len)"
    MATLABSignature: <Define incomplete inputs to see the MATLAB signature.>
          CPPInputs: [1×2 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×0 clibgen.api.OutputArgumentDefinition]
             Status: Incomplete
           Included: false

  Show all properties

From the display, you must Define incomplete inputs to see the MATLAB signature. Inspect the inputs.

methDef.CPPInputs

ans = 

  1×2 InputArgumentDefinition array with properties:

    Name
    Position
    CPPType
    MATLABType
    Direction
    Size
    Status

  Display as table

Click the Display as table link to see that the src argument is incomplete.

    Name     Position    CPPType                MATLABType                  Status  
    _____    ________    ________    _________________________________    __________

    "src"       1        "int []"    "clib.array.matrix.Int"    Incomplete
    "len"       2        "size_t"    "uint64"                             Complete

Display the signature to see how the method uses the argument.

methDef.CPPSignature

ans = 

    "void Mat::setMat(int [] src,size_t len)"

The src argument is a pointer. MATLAB cannot automatically determine the size of src. Define src as an input array whose size is the len argument.

argDef = methDef.CPPInputs([methDef.CPPInputs.Name] == "src");
argDef.define(Size="len");

Verify that methDef is completely defined.

methDef

methDef = 

  MethodDefinition with properties:

            CPPName: "setMat"
         MATLABName: "setMat"
         Overloaded: false
    OwningClassName: "Mat"
       CPPSignature: "void Mat::setMat(int [] src,size_t len)"
    MATLABSignature: clib.matrix.Mat/setMat(src)
          CPPInputs: [1×2 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×0 clibgen.api.OutputArgumentDefinition]
             Status: Complete
           Included: true

  Show all properties

Inspect `getMat` Method

Follow the steps for inspecting the setMat method to define the missing information for the getMat method.

methDef = clsDef.findMethod("getMat"); % CPPOutput is incomplete.
methDef.CPPSignature % length of output defined by input argument len. 
argDef = methDef.CPPOutput;
argDef.define(Size="len");
methDef.Status

Inspect `copyMat` Method

Follow the steps for inspecting the setMat method to inspect the copyMat method. Define argument dest.

methDef = clsDef.findMethod("copyMat"); % CPPInputs are incomplete.
methDef.CPPInputs % argument dest needs definition.
methDef.CPPSignature % The length of dest is defined by the input argument len.
argDef = methDef.CPPInputs([methDef.CPPInputs.Name] == "dest");
argDef.define(Size="len");
methDef.Status

Inspect Incomplete Functions

Identify the incomplete functions:

idef.IncompleteFunctions

ans = 
  1×2 FunctionDefinition array with properties:

    CPPName
    MATLABName
    Overloaded
    CPPSignature
    MATLABSignature
    CPPInputs
    CPPOutput
    Status
    Included

  Display as table

Click the Display as table link to display the addMat and updateMatBySize functions:

         CPPName                       MATLABName                   Overloaded      Status      Included
    _________________    _______________________________________    __________    __________    ________

    "addMat"             "clib.matrix.addMat"               false       Incomplete     false  
    "updateMatBySize"    "clib.matrix.updateMatBySize"      false       Incomplete     false

Inspect `addMat` Function

Display the properties of the addMat function.

fcnDef = idef.findFunction("addMat")

fcnDef = 
  FunctionDefinition with properties:

            CPPName: "addMat"
         MATLABName: "clib.matrix.addMat"
         Overloaded: false
       CPPSignature: "int addMat(Mat const * mat)"
    MATLABSignature: <Define incomplete inputs to see the MATLAB signature.>
          CPPInputs: [1×1 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×1 clibgen.api.OutputArgumentDefinition]
             Status: Incomplete
           Included: false

  Show all properties

From the display, you must Define incomplete inputs to see the MATLAB signature. Inspect the inputs.

fcnDef.CPPInputs

ans = 
  InputArgumentDefinition with properties:

          Name: "mat"
      Position: 1
       CPPType: "Mat const *"
    MATLABType: "clib.matrix.Mat"
     Direction: input
          Size: <undefined>
        Status: Incomplete

Display the signature to see how the function uses the argument.

fcnDef.CPPSignature

ans = "int addMat(Mat const * mat)"

The function takes a single mat argument, so the Size value is 1.

argDef = fcnDef.CPPInputs([fcnDef.CPPInputs.Name] == "mat");
argDef.define(Size=1);
fcnDef

fcnDef = 
  FunctionDefinition with properties:

            CPPName: "addMat"
         MATLABName: "clib.matrix.addMat"
         Overloaded: false
       CPPSignature: "int addMat(Mat const * mat)"
    MATLABSignature: RetVal = clib.matrix.addMat(mat)
          CPPInputs: [1×1 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×1 clibgen.api.OutputArgumentDefinition]
             Status: Complete
           Included: true

  Show all properties

Inspect `updateMatBySize` Function

Display the properties of the updateMatBySize function.

fcnDef = idef.findFunction("updateMatBySize")

fcnDef = 
  FunctionDefinition with properties:

            CPPName: "updateMatBySize"
         MATLABName: "clib.matrix.updateMatBySize"
         Overloaded: false
       CPPSignature: "void updateMatBySize(Mat & mat,int * arr,size_t len)"
    MATLABSignature: <Define incomplete inputs to see the MATLAB signature.>
          CPPInputs: [1×3 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×0 clibgen.api.OutputArgumentDefinition]
             Status: Incomplete
           Included: false

  Show all properties

From the display, you must Define incomplete inputs to see the MATLAB signature. Inspect the inputs.

fcnDef.CPPInputs

ans = 
  1×3 InputArgumentDefinition array with properties:

    Name
    Position
    CPPType
    MATLABType
    Direction
    Size
    Status

  Display as table

Click the Display as table link.

    Name     Position    CPPType           MATLABType             Status  
    _____    ________    ________    _______________________    __________

    "mat"       1        "Mat &"     "clib.matrix.Mat"          Complete  
    "arr"       2        "int *"     "clib.array.matrix.Int"    Incomplete
    "len"       3        "size_t"    "uint64"                   Complete

Display the signature to see how the function uses the argument.

fcnDef.CPPSignature

ans = "void updateMatBySize(Mat & mat,int * arr,size_t len)"

The length of arr is defined by the input argument len.

argDef = fcnDef.CPPInputs([fcnDef.CPPInputs.Name] == "arr");
argDef.define(Size="len")
fcnDef

fcnDef = 
  FunctionDefinition with properties:

            CPPName: "updateMatBySize"
         MATLABName: "clib.matrix.updateMatBySize"
         Overloaded: false
       CPPSignature: "void updateMatBySize(Mat & mat,int * arr,size_t len)"
    MATLABSignature: clib.matrix.updateMatBySize(mat, arr)
          CPPInputs: [1×3 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×0 clibgen.api.OutputArgumentDefinition]
             Status: Complete
           Included: true

  Show all properties

Build Interface

Use the InterfaceDefinition build function.

build(idef)

Add the interface file folder to the MATLAB path.

libpath = fullfile(pwd,"matrix");
addpath(libpath)

Save Workflow Script

Your publishmatrix.m script might contain this MATLAB code:

%Publish MATLAB Interface to matrixOperations
%Create Interface Configuration
rootpath = fullfile(matlabroot,"extern","examples","cpp_interface");
icfg = clibgen.api.InterfaceConfiguration("matrix");
icfg.HeaderFiles = fullfile(rootpath,"matrixOperations.hpp");

%Create Interface Definition
idef = clibgen.api.InterfaceDefinition(icfg);
idef.SourceFiles = fullfile(rootpath,"matrixOperations.cpp");
idef.Libraries = fullfile(rootpath,'win64/mingw64/matrixOperations.lib');

%Define Methods in Class Mat
clsDef = idef.findClass("Mat");

methDef = clsDef.findMethod("setMat");
argDef = methDef.CPPInputs([methDef.CPPInputs.Name] == "src");
argDef.define(Size="len");

methDef = clsDef.findMethod("getMat");
argDef = methDef.CPPOutput;
argDef.define(Size="len");

methDef = clsDef.findMethod("copyMat");
argDef = methDef.CPPInputs([methDef.CPPInputs.Name] == "dest");
argDef.define(Size="len");

%Define Incomplete Functions
fcnDef = idef.findFunction("addMat");
argDef = fcnDef.CPPInputs([fcnDef.CPPInputs.Name] == "mat");
argDef.define(Size=1);

fcnDef = idef.findFunction("updateMatBySize");
argDef = fcnDef.CPPInputs([fcnDef.CPPInputs.Name] == "arr");
argDef.define(Size="len");

%Build Interface
build(idef)
libpath = fullfile(pwd,"matrix");
addpath(libpath)

Test Interface

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/C++ Library In-Process or Out-of-Process.

libraryconfig = clibConfiguration("matrix",ExecutionMode="outofprocess")

Write Test Code

Write code to call and test the interface library.

matObj = clib.matrix.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.matrix.Int with properties:

    Dimensions: 5
     Resizable: 0

Share Interface

To share the interface with another MATLAB user, create a package installation (.mltbx) file. Using the instructions in Distribute MATLAB Interface to C/C++ Library:

Set the package folder to your matrix folder, which contains the interface file matrixInterface.dll.
Put the compiled library file matrix.dll in the same folder.
Identify the namespace (calling syntax) as clib.matrix.

Publish MATLAB Interface Programmatically

Create Interface Configuration

Create Interface Definition

Inspect Incomplete Class

Inspect `setMat` Method

Inspect `getMat` Method

Inspect `copyMat` Method

Inspect Incomplete Functions

Inspect `addMat` Function

Inspect `updateMatBySize` Function

Build Interface

Save Workflow Script

Test Interface

Enable out-of-process execution mode

Write Test Code

Share Interface

See Also

Objects

Functions

Topics

Publish MATLAB Interface Programmatically

Create Interface Configuration

Create Interface Definition

Inspect Incomplete Class

Inspect setMat Method

Inspect getMat Method

Inspect copyMat Method

Inspect Incomplete Functions

Inspect addMat Function

Inspect updateMatBySize Function

Build Interface

Save Workflow Script

Test Interface

Enable out-of-process execution mode

Write Test Code

Share Interface

See Also

Objects

Functions

Topics

Inspect `setMat` Method

Inspect `getMat` Method

Inspect `copyMat` Method

Inspect `addMat` Function

Inspect `updateMatBySize` Function