clibgen.api.InterfaceDefinition

R2026b

Inspect, customize, and build MATLAB interface definition for C/C++ library

Since R2026b

Description

The clibgen.api.InterfaceDefinition object enables you to access the symbols, inspect the MATLAB^® definitions to C++ symbols, customize the interface, resolve errors, and build a MATLAB interface to a C/C++ library.

Creation

Syntax

idef = clibgen.api.InterfaceDefinition(icfg)

idef = clibgen.api.InterfaceDefinition(icfg,SourceFiles=files,Libraries=libs)

Description

idef = clibgen.api.InterfaceDefinition(icfg) creates an interface definition object using the specified interface configuration.

idef = clibgen.api.InterfaceDefinition(icfg,SourceFiles=files,Libraries=libs) specifies the source files and the dependent libraries for those header files using the constructor. Sets the SourceFiles property to files and the Libraries property to libs.

Input Arguments

icfg — Interface configuration

clibgen.api.InterfaceConfiguration object

Interface configuration containing C++ library information for the interface, specified as a clibgen.api.InterfaceConfiguration object.

files — Source files

string vector

Source files, specified as a string vector.

libs — Libraries

string vector

Libraries, specified as a string vector.

Output Arguments

idef — Interface definition

clibgen.api.InterfaceDefinition object

Interface definition, returned as a clibgen.api.InterfaceDefinition object.

Properties

InterfaceName — Name of interface

Read-only: string scalar

This property is read-only.

Name of the interface, a string scalar.

Classes — MATLAB class and structure definitions

Read-only: clibgen.api.ClassDefinition object

This property is read-only.

MATLAB class and structure definitions, represented as a clibgen.api.ClassDefinition object.

Functions — MATLAB function definitions

Read-only: clibgen.api.FunctionDefinition object

This property is read-only.

MATLAB function definitions, represented as a clibgen.api.FunctionDefinition object.

Enums — MATLAB enumeration definitions

Read-only: clibgen.api.EnumDefinition object

This property is read-only.

MATLAB enumeration definitions, represented as a clibgen.api.EnumDefinition object.

OpaqueTypes — MATLAB definitions for void* arguments

Read-only: clibgen.api.OpaqueTypeDefinition arguments

This property is read-only.

MATLAB definitions for void* arguments, represented as a clibgen.api.OpaqueTypeDefinition object.

FunctionTypes — MATLAB definitions for C function pointer and std::function types

Read-only: clibgen.api.FunctionTypeDefinition object

This property is read-only.

MATLAB definitions for C function pointer and std::function types, represented as a clibgen.api.FunctionTypeDefinition object.

IncompleteClasses — C++ classes that require additional definition

Read-only: clibgen.api.ClassDefinition object

This property is read-only.

C++ classes that require additional definition, represented as a clibgen.api.ClassDefinition object.

IncompleteFunctions — C++ functions that require additional definition

Read-only: clibgen.api.FunctionDefinition object

This property is read-only.

C++ functions that require additional definition, represented as a clibgen.api.FunctionDefinition object.

UnsupportedClasses — C++ classes not supported in MATLAB

Read-only: clibgen.api.UnsupportedClass object

This property is read-only.

C++ classes not supported in MATLAB, represented as a clibgen.api.UnsupportedClass object.

UnsupportedFunctions — C++ functions not supported in MATLAB

Read-only: clibgen.api.UnsupportedFunction object

This property is read-only.

C++ functions not supported in MATLAB, represented as a clibgen.api.UnsupportedFunction object.

UnsupportedEnums — C++ enumerations not supported in MATLAB

Read-only: clibgen.api.UnsupportedEnum object

This property is read-only.

C++ enumerations not supported in MATLAB, represented as a clibgen.api.UnsupportedEnum object.

UnsupportedMethods — C++ methods not supported in MATLAB

Read-only: clibgen.api.UnsupportedMethod object

This property is read-only.

C++ methods not supported in MATLAB, represented as a clibgen.api.UnsupportedMethod object.

UnsupportedProperties — C++ properties not supported in MATLAB

Read-only: clibgen.api.UnsupportedProperty object

This property is read-only.

C++ properties not supported in MATLAB, represented as a clibgen.api.UnsupportedProperty object.

ParserErrors — Errors while parsing library headers

Read-only: table

This property is read-only.

Errors while parsing the library headers, represented as a table.

ParserWarnings — Warnings while parsing library headers

Read-only: table

This property is read-only.

Warnings while parsing the library headers, represented as a table.

OutputFolder — Full path to folder

current folder (default) | string scalar

Full path to folder for generated interface library, specified as a string scalar.

Libraries — C++ libraries

string vector

C++ libraries to help resolve symbols while building the MATLAB interface, specified as a string vector.

SourceFiles — Supporting C/C++ source files

string vector

Supporting C/C++ source files, specified as a string vector. Supported file extensions are .c, .cpp, and .cxx. If the files are not in the current folder or on your MATLAB path, then the argument includes the full or relative path to the file. A supporting source file must contain C/C++ definitions. For information about building C source files, see CLinkage.

If you are creating a MATLAB interface for a library that is completely defined by header and C/C++ source files, you do not need compiled library files.

AdditionalLinkerFlags — Linker flags

string vector

Since R2022a

List of linker flags, specified as a string vector, character vector, or cell array of character vector, to append to the linker flags used to build the interface. The function passes the flags directly to the linker without validation.

For more information, see Build C/C++ Library Interface and Review Contents.

CLinkage — Option to specify how to parse .h header files

false or 0 (default) | true or 1

Since R2022a

Option to specify how to parse and build .h header files, specified as a numeric or logical 1 (true) or 0 (false).

If CLinkage is true, then the function treats .h header files in the InterfaceGenerationFiles argument as C header 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.

Set CLinkage to true when creating an interface for a library defined by:

• C header and library files.

• C header and source files.

If CLinkage is false, then the function treats .h header files as C++ files. Use the default (CLinkage is false) when creating an interface from C++ files with C dependencies. In this case, the C file is specified by one of these arguments:

• IncludePath for the location of C header files.

• SupportingSourceFiles for C source files.

• Libraries for C compiled library files .lib, .dll, .so, or .dylib.

For examples showing how to use C files in your interface, see "Files in Your Library" in Tips and search for CLinkage.

Buildable — Interface build status

Read-only: true | false

This property is read-only.

Interface build status, represented as true or false. An interface is buildable when there are no parser errors and there is at least one symbol in the interface to build.

DisplayOutput — Option to display output

false or 0 (default) | true or 1

Option to display output to the MATLAB Command Window, specified as a numeric or logical 1 (true) or 0 (false).

Object Functions

build	Build MATLAB interface to C++ library from clibgen.api.InterfaceDefinition object
findClass	Find class in C++ library
findEnum	Find enumeration in C++ library
findFunction	Find function in C++ library

Examples

Create Platform-Specific Interface

rootpath = fullfile(matlabroot,"extern","examples","cpp_interface");
icfg = clibgen.api.InterfaceConfiguration("matrixlib");
icfg.HeaderFiles = fullfile(rootpath,"matrixOperations.hpp");
icfg.IncludePath = rootpath;
if ispc
    libs = fullfile(rootpath,"win64","mingw64","matrixOperations.lib");
elseif (isunix && ~ismac)
    libs = fullfile(rootpath,"glnxa64","libmwmatrixOperations.so");
elseif ismac
    libs = fullfile(rootpath,"maca64","libmwmatrixOperations.dylib");    
end

idef = clibgen.api.InterfaceDefinition(icfg,Libraries=libs)

idef = 

  Buildable InterfaceDefinition with properties:

                 Classes: [1×1 clibgen.api.ClassDefinition]
               Functions: [1×3 clibgen.api.FunctionDefinition]
                   Enums: [1×0 clibgen.api.EnumDefinition]

           InterfaceName: "matrixlib"
               Libraries: "E:\matlab\extern\examples\cpp_interface\win64\mingw64\matrixOperations.lib"
             SourceFiles: [1×0 string]

       IncompleteClasses: [1×1 clibgen.api.ClassDefinition]
     IncompleteFunctions: [1×2 clibgen.api.FunctionDefinition]

      UnsupportedClasses: [1×0 clibgen.api.UnsupportedClass]
    UnsupportedFunctions: [1×0 clibgen.api.UnsupportedFunction]

  Show all properties

Version History

Introduced in R2026b