Header-Only HPP File

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

Library Artifacts	MATLAB Interface `libname`	MATLAB Help
Header file `school.hpp`	`clib.school` (default name)	`>> doc clib.school`

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

MATLAB provides the header file for you to use in this example in this folder:

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

To create an interface named school for this library, follow these steps in a workflow script: generate a library definition file, define any missing constructs, build the interface, and then test the interface. If you need to iterate over the publishing process, you can take additional steps to restore parameters and enable out-of-process execution mode. You can then share your published interface with other users.

Create Workflow Script

Navigate to a writeable folder and call clibPublishInterfaceWorkflow. In the dialog box, specify the name of the workflow script, for example, publishmatrixlib.mlx. The workflow script has steps to help you publish the interface. Use the script to save the parameters for publishing the interface. You can use the same script on all platforms.

Note

The workflow script allows you to repeatedly generate, define, build, and test an interface during multiple MATLAB sessions. However, the script does not save edits to library definition files recreated using the Overwrite existing definition files option.

Step 1: GENERATE

First, generate the library definition file. The workflow script contains the Generate C++ Interface Live Editor task for this step. Use this task to select the files that make up the library and to set options for generating the library definition file.

Select files

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

To set the Library start path, browse to the folder fullfile(matlabroot,"extern","examples","cpp_interface") and click Select Folder.

To select the header file, click Browse to open the file school.hpp.

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

Select configuration

In this example, the C++ compiler is set to MinGW64 Compiler (C++).

By default, Name of interface library is school. This name is used with clib to call functionality from MATLAB.

Verify that Output folder is a writeable folder.

Select the Overwrite existing definition files check box so that you can recreate the definition file while developing the interface.

Specify optional C++ library settings

Building the interface to this library does not require optional C++ library settings.

Specify optional definition configurations

Building the interface to this library does not require optional definition configurations.

Display results

By default, when you generate a definition file, the function displays available constructs (classes and functions in the library). While developing the interface, also select the Show unavailable constructs check box so that you can see what constructs are not included because they are unsupported.

Generate Definition File

Click Generate definition file. The script displays its progress and creates the library definition file defineschool.m in the specified output folder.

Step 2: DEFINE

When you created the library definition file, MATLAB reported that one construct is partially defined. To completely define the functionality, edit the defineschool.m file. To edit the file, run the DEFINE section.

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 and close the definition file.

To validate the edits you made in the file, run the Confirm edits and run summary section. Fix any reported errors in the file.

The summary function displays:

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)

Step 3: BUILD

To build the school interface to the library, run the BUILD section of the script.

Building interface file 'schoolInterface.dll' for clib interface 'school'.
Interface file 'schoolInterface.dll' built in folder 'C:\Users\Documents\MATLAB\school'.

To use the library, add the interface file folder to the MATLAB path.
addpath('C:\Users\Documents\MATLAB\school')

Note

You can repeat the generate, define, and build steps. However, once you display help for or call functions in the library, you cannot update the defineschool definition file in the same MATLAB session. Either restart MATLAB or create a new definition file by changing the Name of interface library parameter in the Select configuration section.

Step 4: TEST

Set up and copy run-time libraries

Run the Set up and copy run-time libraries section. This library does not have additional run-time dependencies, so you do not need to modify the commands.

Call help on interface library

To display help for the interface library, run the Call help on interface library section.

Write code to call and test interface library

Use the code section in Write code to call and test interface library to write these tests:

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

ans = "Ms. Jones"

Share Interface

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

Set the toolbox folder to your school folder, which contains the interface file schoolInterface.dll.
Identify the namespace (calling syntax) as clib.school.