clibgen.api.InterfaceConfiguration

R2026b

Specify configuration for generating MATLAB interface to C/C++ library

Since R2026b

Description

A clibgen.api.InterfaceConfiguration object specifies configuration settings for generating a MATLAB^® interface to a C/C++ library. Use this object as an input argument when creating a clibgen.api.InterfaceDefinition object.

Creation

Syntax

icfg = clibgen.api.InterfaceConfiguration

icfg = clibgen.api.InterfaceConfiguration(name)

icfg = clibgen.api.InterfaceConfiguration(name,HeaderFiles=files,IncludePath=path)

Description

icfg = clibgen.api.InterfaceConfiguration creates a default interface configuration. Set properties to specify C++ library information.

icfg = clibgen.api.InterfaceConfiguration(name) specifies an interface name for the MATLAB interface.

icfg = clibgen.api.InterfaceConfiguration(name,HeaderFiles=files,IncludePath=path) specifies the header files and the include path for those header files.

Input Arguments

name — Interface name

string scalar

Interface name, specified as a string scalar. This argument sets the InterfaceName property.

files — Header files

string vector

Header files, specified as a string vector. Header files must have a .h, .hpp, or .hxx extension. A header file without an extension is also supported. This argument sets the HeaderFiles property to files.

path — Include path

string vector

Include path for header files, specified as a string vector. This argument sets the IncludePath property to path.

Output Arguments

icfg — Interface configuration

clibgen.api.InterfaceConfiguration

Interface configuration, returned as a clibgen.api.InterfaceConfiguration object.

Properties

Required Configuration Information

InterfaceName — Interface name

"" (default) | string scalar

Interface name, specified as a string scalar. You use this interface name to call functions and other constructs in the C/C++ library from MATLAB using the clib namespace.

Example: icfg.InterfaceName = "acme"

HeaderFiles — Header files

1x0 empty string vector (default) | string vector

Header files, specified as a string vector of paths to the header files for the interface. Header files must have a .h, .hpp, or .hxx extension. You can specify absolute or relative paths to the header files.

Example: icfg.HeaderFiles = "toolbox/acme/include/basic.hpp"

IncludePath — Include path

1x0 empty string vector (default) | string vector

Include path for header files, specified as a string vector. You can specify absolute or relative paths of folders that contain the required header files. An empty string vector indicates that the library does not require an include path.

Example: icfg.IncludePath = "toolbox/acme/include"

Interface Contents and Global Settings

IncludedFunctions — Functions to include

regexpPattern(".*") (default) | pattern vector | string vector

Functions to include in the MATLAB interface, specified as a pattern vector or string vector. You can explicitly specify the name of each C/C++ function to include, or you can specify one or more patterns that match the names of the functions. By default, the configuration includes all supported functions in the interface.

Example: icfg.IncludedFunctions = ["addMat" "updateMatByX"];

IncludedClasses — Classes to include

regexpPattern(".*") (default) | pattern vector | string vector

Classes to include in the MATLAB interface, specified as a pattern vector or string vector. You can explicitly specify the name of each C/C++ class to include, or you can specify one or more patterns that match the names of the classes. By default, the configuration includes all supported classes in the interface.

Example: icfg.IncludedClasses = "Matrix";

IncludedEnumerations — Enumerations to include

regexpPattern(".*") (default) | pattern vector | string vector

Enumerations to include in the MATLAB interface, specified as a pattern vector or string vector. You can explicitly specify the name of each C/C++ enumeration to include, or you can specify one or more patterns that match the names of the enumerations. By default, the configuration includes all supported enumerations in the interface.

Example: icfg.IncludedEnumerations = "Color";

TreatConstCharPointerAsCString — Treat const character pointer as C string

false or 0 (default) | true or 1

Treat const character pointer as C string, specified as a numeric or logical 1 (true) or 0 (false). If TreatConstCharPointerAsCString is true, then the interface treats all const character pointers in the library as null-terminated C strings by specifying MLTYPE as string and SHAPE as nullTerminated. Otherwise, the MATLAB type and the shape of const character pointers are unknown. Supported pointer types are:

• const char *

• const wchar_t *

• const char16_t *

• const char32_t *

TreatObjectPointerAsScalar — Treat object pointer as scalar value

false or 0 (default) | true or 1

Treat object pointer as scalar value, specified as a numeric or logical 1 (true) or 0 (false). If TreatObjectPointerAsScalar is true, then the interface treats all object pointers in the library as scalar values by specifying SHAPE as 1. Otherwise, the shape of object pointers is unknown.

Compilation Options

AdditionalCompilerFlags — Additional compiler flags

1x0 empty string vector (default) | string vector

Additional compiler flags, specified as a string vector. Use this property to specify compiler flags in addition to those already used to build the interface. The interface passes the flags directly to the compiler without validation.

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

Example: icfg.AdditionalCompilerFlags = "-std=c++23"

DefinedMacros — Macro definitions

empty dictionary (default) | dictionary

Macro definitions for parsing header files, specified as a dictionary, where each key-value pair is defined as:

• Key — Macro name, specified as string scalar. The name can contain the characters 1–9, a–z, A–Z, and "_" and cannot begin with a numeral.

• Value — Macro value, specified as string scalar.

Example: icfg.DefinedMacros = dictionary("D1","V1","D2","V2")

UndefinedMacros — Undefined macros

"" (default) | string row vector

Macros to treat as undefined during header file parsing, specified as a string row vector. Each macro name can contain the characters 1–9, a–z, A–Z, and "_" and cannot begin with a numeral.

Example: icfg.UndefinedMacros = "D3"

InvalidNameReplacementStyle — Replacement style for invalid name

"underscore" (default) | "hex" | "delete"

Replacement style for invalid name, specified as one of these values:

• "underscore" — Replace all characters that are not alphanumerics or underscores with underscores.

• "hex" — Replace each character that is not an alphanumeric or underscore with its corresponding hexadecimal representation.

• "delete" — Delete all characters that are not alphanumerics or underscores.

This property controls how the interface replaces nonalphanumeric characters. For all replacement styles, MATLAB deletes white space characters and changes any lowercase letter following white space to uppercase.

InvalidNamePrefix — Prefix for invalid name

"x" (default) | string scalar

Prefix for invalid name, specified as a string scalar. The interface prepends the specified prefix to the invalid name when the first character is not alphabetic. A valid prefix must meet these conditions:

• Start with a letter.

• Contain only alphanumeric characters and underscores.

• Not be a MATLAB keyword.

• Not be longer than the value of namelengthmax.

By default, the interface prepends "x" to the invalid name if the name does not start with a letter after the interface handles nonalphanumeric and underscore characters according to the InvalidNameReplacementStyle property.

GenerateDocumentationFromHeaderFiles — Generate documentation from C++ files

true or 1 (default) | false or 0

Generate documentation from C++ files, specified as a numeric or logical 1 (true) or 0 (false). By default, GenerateDocumentationFromHeaderFiles generates documentation from comments in C++ files. The MATLAB doc command displays this documentation in the Command Window. If you set this property to false, then the interface ignores C++ comments and generates documentation only for MATLAB and C++ type mappings.

For more information, see Publish Help Text for MATLAB Interface to C/C++ Library.

Examples

Configure Interface

Create an interface with specific classes and functions.

icfg = clibgen.api.InterfaceConfiguration("sensorlib",HeaderFiles="sensorlib.hpp",IncludePath=pwd);
icfg.IncludedClasses = "sensor::Sensor" | "sensor::Reading";
icfg.IncludedFunctions = "sensor::processReadings" | "sensor::createSensor";
icfg.TreatObjectPointerAsScalar = true;
icfg

icfg = 

  InterfaceConfiguration with properties:

   Required Configuration Information
                     InterfaceName: "sensorlib"
                       HeaderFiles: "C:\work\sensorlib.hpp"
                       IncludePath: "C:\work"

   Interface Contents and Global Settings
                 IncludedFunctions: "sensor::processReadings" | "sensor::createSensor"
                   IncludedClasses: "sensor::Sensor" | "sensor::Reading"
              IncludedEnumerations: regexpPattern(".*")
    TreatConstCharPointerAsCString: 0
        TreatObjectPointerAsScalar: 1

   Compilation Options
           AdditionalCompilerFlags: [1×0 string]
                     DefinedMacros: dictionary with no entries
                   UndefinedMacros: [1×0 string]

Version History

Introduced in R2026b