Generate C++ Interface
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 theclib.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
Library type
— File types in library
Headers and compiled library
files (default) | Header-only | Headers and source files | Custom file combination
Types of C/C++ files that define your library.
Header and compiled library files — Library is completely defined by:
One or more header files
Header files in include path folders (optional)
One or more compiled library files
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:
One or more header files
Header files in include path folders (optional)
One or more supporting source files
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)
Library start path
— Pathname
current folder (default)
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.
C++ compiler
— C++ compiler
default C++ compiler (default) | installed C++ compilers
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.
Name of interface library
— Namespace used in MATLAB
text
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
Overwrite existing definition files
— Whether to re-create definition file
off
(default) | on
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
.
Treat .h files as C header files
— How to parse header files
off
(default) | on
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.
Define macros for your library using the -D compiler flag
— Macro identifier and optional value
no default
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
Undefine macros from your library using the -U compiler flag
— Macro identifier to exclude
no default
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
Additional compiler flags
— Compiler flags
no default
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
Additional linker flags
— Linker flags
no default
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
Object pointer definition
— MATLAB shape for C++ object pointers
Leave undefined
(default) | Set to scalar
Select the MATLAB shape for C++ object pointers.
If
Leave undefined
, then you must specify theSHAPE
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.
Const character pointer definition
— Shape and MATLAB type for C++ const char *
Leave undefined
(default) | Set to null-terminated C string
Select the shape and MATLAB type for C++ const char *
arguments.
If
Leave undefined
, then you must specify the shape and the MATLAB type ofconst char *
arguments in the library definition file for each function usingconst
character pointers.If
Set to null-terminated C string
, then the task treats allconst char *
arguments in the library as null-terminated C strings by defining the shape asnullTerminated
and the MATLAB type as string.
Array return type
— MATLAB representation of non-object C++ arrays
C array
(default) | MATLAB array
Select the MATLAB representation of non-object C++ arrays.
If
C array
, then the task converts C++ arrays to theclib
array type (clib.array.*
).If
MATLAB array
, then the task converts C++ arrays to native MATLAB arrays.
More About
Compiled Library File
The file type of a compiled library file is dependent on platform:
On Windows® platforms:
For compiled libraries, specify a
.lib
import library file. If the.lib
file is not available and the library is compiled with a supported Microsoft® Visual Studio® compiler, then you can specify a.dll
dynamic-link library file.
For static libraries, specify a
.lib
file.
On Linux® platforms, specify a
.so
shared object file.On macOS platforms, specify a
.dylib
dynamic shared library file.
Header File
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.
Include Path
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.
Supporting Source File
A supporting source file is a .cpp
, .cxx
, or
.c
file containing function definitions for your library.
Source File
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
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)