Publish MATLAB Interface to C++ Library Using Live Script

R2026b

This example shows how to create a MATLAB® interface to a C++ library named school, using the Publish MATLAB interface to C++ library live script. The example uses a header-only library, which means that the library is defined completely in a header file and does not have a compiled library file.

The school library defines classes that represent students and teachers. After you publish this library, you can 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");

Create Workflow Live Script

To start, create a new workflow script by calling the clibPublishInterfaceWorkflow function. The function opens a new live script titled Publish MATLAB interface to C++ library. The live script contains templated steps for publishing a MATLAB interface to a C++ library.

clibPublishInterfaceWorkflow

Step 1: GENERATE

In step 1 of the workflow script, you generate the definition for the interface. 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 by browsing to the folder fullfile(matlabroot,"extern","examples","cpp_interface") and clicking Select Folder.

    • Set Header files by browsing to school.hpp and clicking Open.

    • Because the header file does not depend on other header files, 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. The IncompleteFunctions property shows one incomplete function.

    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

In step 2 of the workflow script, you complete the interface definition by supplying any missing information. In this example, the IncompleteFunctions property shows one incomplete function named getName.

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

The MATLABSignature property shows that you must define incomplete inputs to see the MATLAB signature of the getName function. Inspect the inputs.

fcnDef = interfaceDefinitionFromTask.findFunction("getName");
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)"

Because p is declared as a pointer, MATLAB cannot determine whether it points to a single object or an array. The function signature shows that only one Person object is passed, so set its Size property to 1.

argDef.Size=1;

Verify that the interface is completely defined (buildable).

interfaceDefinitionFromTask.Buildable
ans =

  logical

   1

Step 3: BUILD

In step 3 of the workflow script, you build the MATLAB interface to the C++ library using the completed interface definition. You can run this section without any changes.

The build function creates an interface library in the folder specified by the OutputFolder property of the interface definition. In this example, the resulting library is schoolInterface.dll. Add the interface file folder to the MATLAB path by clicking the linked addpath command in live script output. Adding the interface file folder to the path enables you to use the school library.

Step 4: TEST

In step 4 of the workflow script, you test the MATLAB interface to the C++ library. Step 4a sets up any run-time dependencies. Step 4b enables out-of-process execution mode, which enables you to make changes to the interface definition without having to restart MATLAB. For this example, you do not need to modify these steps before running them.

Step 4c displays help text for the interface library. For this example, you can run this step without any changes to view help for the classes in clib.school.

Step 4d provides a place to write your own test code. For this example, write code to call and test the school library.

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

Step 4e in the workflow script unloads the out-of-process library. When you are finished testing the interface, you can run this step without any changes.

See Also

Functions

Topics