Publish MATLAB Interface Using Live Script Workflow

R2026b

This example creates a MATLAB^® interface to a C++ library named school using the Publish MATLAB interface to C++ library live script. The library is defined in a header file and does not have a compiled library file. A library defined completely by its header file is called a header-only library.

This library defines classes representing students and teachers. After you publish this library, MATLAB users call functions in the clib.school namespace to create Student and Teacher objects and to specify names and ages.

The header file for this example is in this folder:

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

Step 1: GENERATE

Call clibPublishInterfaceWorkflow to open the workflow script Publish MATLAB interface to C++ library.

Use the Generate C++ Interface Live Editor task to select the files that make up the library and to set options for generating the interface definition object.

• Select files—The library is defined by the school.hpp header file. Set Library type to Header-only.

• Set Library start path—Browse to the folder fullfile(matlabroot,"extern","examples","cpp_interface") and click Select Folder.

• Select the header file—Click Browse to open the file school.hpp.

• Include paths—The header file does not depend on other header files, so select the Library does not require include paths check box.

• Select configuration—By default, Name of interface library is school. Verify that Output folder is a writable folder.

• Generate Definition—Click Generate definition. There is one incomplete function shown in the IncompleteFunctions property.

  interfaceDefinitionFromTask = 
    Buildable InterfaceDefinition with properties:
  
                   Classes: [1×3 clibgen.api.ClassDefinition]
                 Functions: [1×1 clibgen.api.FunctionDefinition]
                     Enums: [1×0 clibgen.api.EnumDefinition]
  
             InterfaceName: "school"
                 Libraries: [1×0 string]
               SourceFiles: [1×0 string]
  
         IncompleteClasses: [1×0 clibgen.api.ClassDefinition]
       IncompleteFunctions: [1×1 clibgen.api.FunctionDefinition]
  
        UnsupportedClasses: [1×0 clibgen.api.UnsupportedClass]
      UnsupportedFunctions: [1×0 clibgen.api.UnsupportedFunction]
  
    Show all properties
  

Step 2: DEFINE

There is one incomplete function shown in the IncompleteFunctions property.

interfaceDefinitionFromTask.IncompleteFunctions

ans = 
  FunctionDefinition with properties:

            CPPName: "getName"
         MATLABName: "clib.school.getName"
         Overloaded: false
       CPPSignature: "std::string getName(Person * p)"
    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

Inspect the getName function.

fcnDef = interfaceDefinitionFromTask.findFunction("getName")

fcnDef = 
  FunctionDefinition with properties:

            CPPName: "getName"
         MATLABName: "clib.school.getName"
         Overloaded: false
       CPPSignature: "std::string getName(Person * p)"
    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

Inspect the inputs.

argDef = fcnDef.CPPInputs

argDef = 
  InputArgumentDefinition with properties:

          Name: "p"
      Position: 1
       CPPType: "Person *"
    MATLABType: "clib.school.Person"
     Direction: input
          Size: <undefined>
        Status: Incomplete

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

fcnDef.CPPSignature

ans = "std::string getName(Person * p)"

p is a scalar value which means its Size property is 1.

argDef.define(Size=1)

Verify that the interface is completely defined (buildable).

interfaceDefinitionFromTask.Buildable

ans =

  logical

   1

Step 3: BUILD

Run the BUILD section of the script.

Save Workflow Script

Save the code you used in step 2: Define, which you can modify and run from the MATLAB command line. Your 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("school"HeaderFiles = "school.hpp");

%Create Interface Definition
idef = clibgen.api.InterfaceDefinition(icfg);

fcnDef = interfaceDefinitionFromTask.findFunction("getName");
argDef = fcnDef.CPPInputs;
argDef.define(Size=1)

Step 4: TEST

• Call help on interface library.

• Write code to call and test interface library.

  t1 = clib.school.Teacher('Ms. Jones',24);
  getName(t1)

  ans = "Ms. Jones"