clibgen.buildInterface

Create interface to C++ library without definition file

Syntax

clibgen.buildInterface(InterfaceGenerationFiles,Libraries=LibraryFiles)

clibgen.buildInterface(InterfaceGenerationFiles,SupportingSourceFiles=SourceFiles)

clibgen.buildInterface(InterfaceGenerationFiles)

clibgen.buildInterface(___,Name=Value)

Description

clibgen.buildInterface(InterfaceGenerationFiles,Libraries=LibraryFiles) creates a MATLAB^® interface to the C++ library defined by HeaderFiles and Libraries.

Note

Any class constructors, methods, data members, and functions in the library that MATLAB cannot automatically define are dropped. To include missing functionality, use the two-step build workflow, clibgen.generateLibraryDefinition and build functions.

The name of the interface file is libNameInterface, with a platform-specific file extension. By default, libName is the name of the file specified in HeaderFiles.

You need a MATLAB-supported C++ compiler. You must build the interface using the same compiler that was used to build the C++ library.

clibgen.buildInterface(InterfaceGenerationFiles,SupportingSourceFiles=SourceFiles) for a library defined by multiple header files, source files, and, if required, shared library files.

clibgen.buildInterface(InterfaceGenerationFiles) creates an interface to the library which is completely defined by HeaderFiles. You can use any MATLAB-supported C++ compiler to build the interface.

If your library includes a shared library file, then you must specify a Libraries argument.

clibgen.buildInterface(___,Name=Value) generates the interface using one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes. For more information about using these arguments, see clibgen.generateLibraryDefinition.

Examples

Create Interface for Library school

Copy the school.hpp header file a writable folder.

copyfile(fullfile(matlabroot,'extern','examples','cpp_interface','school.hpp'),'.','f')

Build the interface schoolInterface.dll. The path name in the output reflects your chosen folder.

clibgen.buildInterface("school.hpp")

Building interface file 'schoolInterface.dll' for clib interface 'school'.
Interface file 'schoolInterface.dll' built in folder 'C:\Users\MATLAB\school'.

To use the library, add the interface file folder to the MATLAB path.
addpath('C:\Users\MATLAB\school')
1 constructs need further definition to be included in the interface. 
Use clibgen.generateLibraryDefinition to provide definitions.

Click the addpath link to add the interface to the path.

Load the library and display help for the Person class.

help clib.school.Person

Person -  clib.school.Person    Representation of C++ class Person.

Display help for the library.

help clib.school

Compare this functionality with the output of the summary(defineschool) command in Header-Only HPP File. This interface does not include:

Functions
  string clib.school.getName(clib.school.Person)

Input Arguments

InterfaceGenerationFiles — Files to generate the interface

string array | character vector | cell array of character vectors

Files to generate the interface, specified as a string array, character vector, or cell array of character vectors. If not in the current folder or on your MATLAB path, then the argument includes the full or relative path to the file. For more information, see the InterfaceGenerationFiles argument in the clibgen.generateLibraryDefinition function.

Example: "sample.hpp"

Data Types: char | string | cell

Libraries — Shared library file names

empty (default) | string array | character vector | cell array of character vectors

Shared library file names, specified as a string array, character vector, or cell array of character vectors. Use with the Libraries argument. This value is required except if the library is completely defined by the files specified by InterfaceGenerationFiles and SupportingSourceFiles arguments. For more information, see the Libraries argument in the clibgen.generateLibraryDefinition function.

For example, running this statement on Windows^® creates sampleInterface.dll using myLib.lib in C:\myLib\ and writes it to the subfolder sample in the current folder.

clibgen.buildInterface("sample.hpp",Libraries="C:\myLib\myLib.lib")

Data Types: char | string | cell

SupportingSourceFiles — C/C++ source files

string array | character vector | cell array of character vectors

C/C++ source files, specified as a string array, character vector, or cell array of character vectors. Use with the SupportingSourceFiles name-value argument. Supported file extensions are .c, .cpp, and .cxx. If 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++ code.

For more information, see "Files in Your Library" in Tips.

For information about building C source files, see CLinkage.

If the library is completely defined by header and C++ source files, then compiled library files are not required.

Example: "sample.cpp"

Data Types: char | string | cell

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: clibgen.buildInterface("myHeader.hpp",Libraries="myHeader.lib",OutputFolder="C:\work");

IncludePath — Folders for included header files

empty (default) | string array | character vector | cell array of character vectors

Folders for included header files, specified as a string array, character vector, or cell array of character vectors. Each value in IncludePath must be the full pathname to folders to include during compilation of the header files.

If the main header file contains #include statements for header files in different folders, then use the IncludePath argument to specify these paths.

Data Types: char | string | cell

OutputFolder — Folder name for the generated definition file

current folder (default) | string scalar | character vector

Folder name for the generated definition file, specified as a string scalar or a character vector. For example, this statement creates myHeaderInterface.dll in C:\work\myHeader on Windows.

clibgen.buildInterface("myHeader.hpp",OutputFolder="C:\work")

Data Types: char | string | cell

InterfaceName — Generated interface namespace

header file name (default) | string scalar | character vector

Since R2024a

Generated interface namespace, specified as a string scalar or a character vector. For interfaces created from a single header file, the default value is the name of the header. For multiple header files, InterfaceName must be a valid MATLAB name.

For example, this statement creates a mylibInterface library file in the subfolder mylib in the current folder.

clibgen.buildInterface(["h1.hpp","h2.hpp"],InterfaceName="mylib")

Data Types: char | string | cell

Verbose — Option to display generation messages

false or 0 (default) | true

Option to display generation messages, specified as a numeric or logical 1 (true) or 0 (false). When true, clibgen.buildInterface displays generation messages to the command window while building the interface. For example, this statement creates an h1Interface library file in the subfolder h1 and displays messages in the command window.

clibgen.buildInterface("h1.hpp",Verbose=true)

For more information, see Messages About Unsupported Types.

Data Types: logical

TreatObjectPointerAsScalar — Shape specifier for object pointers

false or 0 (default) | true or 1

Shape specifier for object pointers, specified as a numeric or logical 1 (true) or 0 (false). If TreatObjectPointerAsScalar is true, then the function treats all object pointers in the library as scalars by specifying SHAPE as 1. Otherwise, the shape of the object pointer is unknown.

Introduced in R2019b.

Data Types: logical

TreatConstCharPointerAsCString — Shape and MATLAB type specifier for const character pointers

false or 0 (default) | true or 1

Shape and MATLAB type specifier for const character pointers, specified as a numeric or logical 1 (true) or 0 (false). If TreatConstCharPointerAsCString is true, then the function treats all const character pointers in the library as null-terminated C strings by specifying MLTYPE as string and SHAPE as nullTerminated. Otherwise, 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 *

Data Types: logical

DefinedMacros — List of macro definitions

empty (default) | scalar string | row vector of scalar strings

List of macro definitions to use while parsing header files, specified as empty, a scalar string, or a row vector of scalar strings. The macro name contains characters 1–9, a–z, A–Z, and '_' and cannot begin with a numeral.

Data Types: string

UndefinedMacros — List of macro cancellations

empty (default) | scalar string | row vector of scalar strings

List of macro cancellations to use while parsing header files, specified as empty, a scalar string, or a row vector of scalar strings. The macro name contains characters 1–9, a–z, A–Z, and '_' and cannot begin with a numeral.

Data Types: string

ReturnCArrays — Option specifying how to return non-object C++ arrays

true or 1 (default) | false or 0

Option specifying how to return non-object C++ arrays, specified as a numeric or logical 1 (true) or 0 (false). If ReturnCArrays is true, then the function converts C++ arrays to the MATLAB clib array type (clib.array.*). If false, then the function converts C++ arrays to native MATLAB arrays.

Data Types: logical

GenerateDocumentationFromHeaderFiles — Option to generate documentation from C++ files

true or 1 (default) | false or 0

Option to generate documentation from C++ files, specified as a numeric or logical 1 (true) or 0 (false). If GenerateDocumentationFromHeaderFiles is true, then the function generates documentation from comments in C++ files for display using the MATLAB doc command. If false, then the function ignores C++ comments and only generates documentation of MATLAB and C++ type mappings.

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

Data Types: logical

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 clibgen.generateLibraryDefinition arguments, see "Files in Your Library" in Tips and search for CLinkage.

Data Types: logical

AdditionalCompilerFlags — Compiler flags

string array | character vector | cell array of character vectors

Since R2022a

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

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

Example: clibgen.generateLibraryDefinition("A.hpp","AdditionalCompilerFlags","-std=c++20")

Data Types: char | string | cell

AdditionalLinkerFlags — Linker flags

string array | character vector | cell array of character vectors

Since R2022a

List of linker flags, specified as a string array, 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++ Library Interface and Review Contents.

Data Types: char | string | cell

Limitations

• Avoid non-ASCII characters in folder and file names, as some locale settings do not support those characters. For information about locale, see Set Locale and Display Language.

Alternative Functionality

Two-Step Build Process

Use the clibgen.generateLibraryDefinition and build functions instead of clibgen.buildInterface to define missing functionality in your interface.

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

Version History

Introduced in R2019a

R2024a: PackageName name-value argument renamed to InterfaceName

The name of the PackageName name-value argument is now InterfaceName. The behavior of the argument remains the same. There are no plans to remove support for existing references to the argument.