Generate C++ Interface - Generate definition file for C++ interface library in the Live Editor - MATLAB (original) (raw)

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

Since R2023a

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:

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.

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:

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 theGenerate 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:

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 isMyLib, then the task deletesdefineMyLib.m.

Specify optional C++ library settings

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

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

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.

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

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

More About

expand all

The file type of a compiled library file is dependent on platform:

A header file contains functionality you want to expose in the MATLAB interface. If a header file depends on another header, but that header file does not need to be exposed to MATLAB, then add the path to the dependent files using the Include paths parameter.

Valid header file extensions are .h, .hpp, and.hxx. If you select the Treat .h files as C header files check box, then the .h header files must contain C++ compatible C code.

Header files and source files can have #include statements for header files that might be in a different folder than the header or source file. If there are no separate folders for include files, then select the Library does not require include paths check box.

A supporting source file is a .cpp, .cxx, or.c file containing function definitions for your library.

A source file is a .cpp or .cxx file that contains functionality you want to expose in the MATLAB interface, similar to a header file. These files are different from supporting source files, which just expose function definitions for building the library.

Version History

Introduced in R2023a