Publish Interface to Header-Only C++ Library

This example creates a MATLAB^® interface to a C++ library named school. The library is defined in the header file school.hpp and does not have a shared library file. A library defined completely by its header file is called a header-only library. If your library includes a shared library file, then see Publish Interface to Shared C++ Library on Windows or Publish Interface to Shared C++ Library on Linux.

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

Verify Selected C++ Compiler

Verify that you have selected a C++ compiler. For an up-to-date list of supported compilers, see Supported and Compatible Compilers. This example uses the MinGW64 compiler.

mex -setup cpp

Copy Example Header File

Copy the school.hpp header file to a writable folder on your path. This example assumes that the current folder is H:\Documents\MATLAB\publisher.

copyfile(fullfile(matlabroot,'extern','examples','cpp_interface','school.hpp'),'.','f')

Generate Definition File

Use the clibgen.generateLibraryDefinition function to create a library definition file defineschool.mlx.

clibgen.generateLibraryDefinition('school.hpp')

Using MinGW64 Compiler (C++) compiler.
Generated definition file defineschool.mlx and data file 'schoolData.xml' contain definitions for 
21 constructs supported by MATLAB.
1 construct(s) require(s) additional definition. To include these construct(s) in the interface, 
edit the definitions in defineschool.mlx.
Build using build(defineschool).

Define Missing Information for C++ Function getName

MATLAB reports that one construct requires additional information (definition). This means that MATLAB cannot automatically define the signature for one of the functions. To provide the missing information, click the link to open defineschool.mlx in MATLAB Live Editor.

Constructs with missing information are commented out. Scroll through the file to locate the section titled "C++ function getName with MATLAB name clib.school.getName". Uncomment the statements in the getName code section.

The input argument p is a scalar value. Replace <SHAPE> in this statement with the number 1:

defineArgument(getNameDefinition, "p", "clib.school.Person", "input", <SHAPE>);

defineArgument(getNameDefinition, "p", "clib.school.Person", "input", 1);

Save the definition file.

Validate the library.

defineschool;

For more information about including constructs in an interface, see Define Missing Information for MATLAB Signatures.

Build Interface and Add to MATLAB Path

Call the build function to create the interface file schoolInterface.dll in the H:\Documents\MATLAB\publisher\school folder.

build(defineschool)

Building interface file 'schoolInterface.dll'.
Interface file 'schoolInterface.dll' built in folder 
'H:\Documents\MATLAB\publisher\school'.
To use the library, add the interface file folder to the MATLAB path.

Click the interface file folder link to add the interface to the path. Alternatively, type:

addpath('school')

View Contents of Library

The summary method displays a summary of the C++ classes and functions defined in the school interface.

summary(defineschool)

MATLAB Interface to school Library

Class clib.school.Person

  Constructors:
    clib.school.Person()
    clib.school.Person(string,uint64)
    clib.school.Person(clib.school.Person)

  Methods:
    setName(string)
    setAge(uint64)
    string getName()
    uint64 getAge()

  No Properties defined

Class clib.school.Teacher

  Constructors:
    clib.school.Teacher()
    clib.school.Teacher(string,uint64)
    clib.school.Teacher(clib.school.Teacher)

  Methods:
    string getName()

  No Properties defined

Class clib.school.Student

  Constructors:
    clib.school.Student()
    clib.school.Student(string,uint64)
    clib.school.Student(clib.school.Student)

  Methods:
    string getName()

  No Properties defined

Functions
  string clib.school.getName(clib.school.Person)

Test Functions

To call functionality in the school interface, use the MATLAB clib package. Type the package name clib.school, ending with a period. You can press Tab to see the three classes and one function defined in the library.

Note

Once you use a library class or function, you cannot modify the library definition unless you restart MATLAB and rebuild the library.

Create a teacher.

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

Use getName to display the teacher's name.

getName(t1)

ans = "Ms. Jones"

Modify Help Text

You can provide help text for your users. For more information, see Publish Help Text for MATLAB Interface to C++ Library.

Distribute Interface

To give the interface to another MATLAB user, instruct them to add the schoolInterface.dll file to a folder named school and add the folder to the MATLAB path. The package name is clib.school.