Generate C++ Interface

Generate definition file for C++ interface library in the Live Editor

Since R2023a

expand all in page

Description

The Generate C++ Interface task lets you interactively configure and generate a library definition file for a C++ interface. This task accomplishes one step in the workflow to publish a MATLAB® interface to a C++ library defined by C/C++ files and compiled library files. The Generate C++ Interface task automatically generates MATLAB code for your live script. For more information about Live Editor tasks generally, see Add Interactive Tasks to a Live Script.

Using this task, you can:

  • Specify the type of files in the C++ library.

  • Select a C++ compiler.

  • Name the interface library. For example, to call library libname from MATLAB, use the clib.libname namespace.

  • Generate a definition file.

  • Display constructs in the definition file.

Open the Task

Use the Generate C++ Interface task as part of the workflow to publish a C++ interface for MATLAB. The recommended approach to access this task is to call the clibPublishInterfaceWorkflow function, which incorporates this Live Editor task into the steps of the publish workflow. This Live Editor task is useful only when combined with the steps to generate, build, and test the interface.

Parameters

expand all

Select files

Types of C/C++ files that define your library.

  • Header and compiled library files — Library is completely defined by:

  • Header-only — Library is completely defined by:

    • One or more header files

    • Header files in include path folders (optional)

  • Headers and source files — Library is completely defined by:

  • Custom file combination — Library is completely defined by a custom combination of:

    • One or more header files, or one or more source files

    • Header files in include path folders (optional)

    • One or more compiled library files (optional)

    • One or more supporting source files (optional)

Set the library start path to the root folder of the library that contains all C/C++ files related to the library. Identifying this folder helps you browse for header files, source files, and compiled library files without having to navigate to the root folder of the library for each file. If set, the library start path value is replaced with the <startpath> tag in the selected files.

Using a start path helps when you publish libraries for multiple platforms because it provides a consistent MATLAB interface to the C/C++ library on all platforms. When you open this Live Editor task on another platform, the files with the <startpath> tag are automatically copied to the new platform tab. Replace the library start path with the root folder specific to the new platform so that you do not need to reselect the files for the platform.

Select configuration

The task displays the selected C++ compiler. The selected compiler is the compiler shown by the statement:

mex -setup cpp

You need a C++ compiler that MATLAB supports to generate a MATLAB C++ interface. You must build the interface library using the same compiler that was used to build the C++ library. If your library is completely defined by source files (does not use a compiled library file), then you can choose any supported C++ compiler to build the interface library.

If the C++ compiler parameter is empty, then you must install a supported C++ compiler. For information on supported compilers, see Supported and Compatible Compilers. After installing a compiler, restart the Generate C++ Interface task.

To change the compiler, select one of the options from the C++ compiler list. This action changes your default compiler for all C++ applications in MATLAB.

An interface library name is required. The task generates an interface library name, but you can override the name with a valid MATLAB name.

Use the interface library name to call the library from MATLAB. For example, to call function myfunc in library interface libname, type:

clib.libname.myfunc

Use this option to change the selected files and adjust the optional settings while developing a definition file for your library. If on, then the task re-creates the definition file. The task deletes the existing file and any edits you might have made in the file. For example, if your library interface name is MyLib, then the task deletes defineMyLib.m.

Specify optional C++ library settings

By default, the task treats .h header files as C++ files. Set to off to create an interface from C++ files with C dependencies.

To treat .h header files as C header files, set to on. Use on to create an interface for a library defined by:

  • C header and library files.

  • C header and source files.

C header files are included with extern "C" blocks in the generated interface code, which avoids name mangling issues when linking against C source files or a C library.

Specify macro identifiers and optional values to use while parsing header files and compiling source files. The macro identifier contains characters 1–9, a–z, A–Z, and '_' and cannot begin with a numeral.

Example: -D RELEASE

Example: -D LOGLEVEL = 2

Specify macro identifiers to exclude while parsing header files and compiling source files. The macro identifier contains characters 1–9, a–z, A–Z, and '_' and cannot begin with a numeral.

Example: -U DEBUG

Append additional flags to the compiler flags during the generate and build steps of the publish workflow. The task passes the flags directly to the compiler without validation.

Example: -std=c++20

Append additional flags to the linker flags during the build step of the publish workflow. The task passes the flags directly to the linker without validation.

Example: /PDB:o.pdb

Specify optional definition configurations

Select the MATLAB shape for C++ object pointers.

  • If Leave undefined, then you must specify the SHAPE parameter in the library definition file for each function using object pointers.

  • If Set to scalar, then the task treats all object pointers in the library as scalars.

Select the shape and MATLAB type for C++ const char * arguments.

  • If Leave undefined, then you must specify the shape and the MATLAB type of const char * arguments in the library definition file for each function using const character pointers.

  • If Set to null-terminated C string, then the task treats all const char * arguments in the library as null-terminated C strings by defining the shape as nullTerminated and the MATLAB type as string.

Select the MATLAB representation of non-object C++ arrays.

  • If C array, then the task converts C++ arrays to the clib array type (clib.array.*).

  • If MATLAB array, then the task converts C++ arrays to native MATLAB arrays.

More About

expand all

Version History

Introduced in R2023a

See Also

Functions

Topics