clibgen.buildInterface

Create interface to C++ library without definition file

collapse all in page

Syntax

clibgen.buildInterface(CppFiles)
clibgen.buildInterface(CppFiles,'Libraries',SharedLibrary)
clibgen.buildInterface(CppFiles,Name,Value)

Description

example

clibgen.buildInterface(CppFiles) generates a MATLAB® interface to the C++ library defined by HeaderFiles. The name of the interface library file is libNameInterface, with a platform-specific file extension. By default, libName is the name the file specified in HeaderFiles. If you use more than one header file, then you must specify a PackageName argument. If you use a shared library file, then you must specify a Libraries argument.

You need a MATLAB-supported C++ compiler. You must build the interface library using the same compiler that was used to build the C++ library. If your library is header-only (does not use a shared library file), then you can choose any supported C++ compiler to build the interface library.

Class constructors, methods, and functions that MATLAB cannot automatically define are not included in the interface. To include missing functionality, use the clibgen.generateLibraryDefinition function.

clibgen.buildInterface(CppFiles,'Libraries',SharedLibrary) creates the interface for a library with one or more shared library files.

clibgen.buildInterface(CppFiles,Name,Value) generates the interface using one or more name-value pair arguments.

Examples

collapse all

Copy the school.hpp header file to writable folder H:\Documents\MATLAB\publisher.

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

Build the interface schoolInterface.dll.

clibgen.buildInterface('school.hpp')
Building interface file 'schoolInterface.dll'.
Interface file 'schoolInterface.dll' built in folder 'H:\Documents\MATLAB\publisher\school'.
To use the library, add the interface file folder to the MATLAB path.
1 constructs need further definition to be included in the interface. 
Use clibgen.generateLibraryDefinition to provide definitions.

Click the interface file folder link to add the interface to the path.

Type clib.school, period, then press Tab to display the classes in the library.

Display help for the library.

help clib.school
Classes contained in clib.school:
Person                         - clib.school.Person    Representation of C++ class Person
Teacher                        - clib.school.Teacher    Representation of C++ class Teacher
Student                        - clib.school.Student    Representation of C++ class Student

Compare this functionality with the output of the summary(defineschool) command in Publish Interface to Header-Only C++ Library. This interface does not include:

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

Input Arguments

collapse all

One or more C++ files for generating the interface, specified as a string array, character vector, or cell array of character vectors. Interface generation files are either header files or source code .cpp files. Supported header file extensions are .h, .hpp, and .hxx. Code in .h header files must be C++ compatible C code. A header file without an extension is also supported. Supported source file extensions are .cpp and .cxx. If not in the current folder or on your MATLAB path, then the name includes the full or relative path to the file. The file must contain C++ code.

These files must contain declarations of all the functions exported by the library. You should be able to compile them in a C++ development environment and use the functionality in C++ applications. If the library is completely defined by the header files (header-only library), then you do not need a library file.

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

If you provide a single header file name, then MATLAB looks for a library with the same name, in the same folder as the header file. The library must have a platform-specific file name extension. If the library has a different name and/or is not in the same folder, then use the Libraries argument.

MATLAB writes the interface files in a subfolder in the current folder, unless you specify the OutputFolder argument. The name of the subfolder is the name of the first header file without a file extension. For example, the following statement creates the interface library file in the subfolder myHeader in the current folder.

clibgen.buildInterface('myHeader.hpp')

Example: "sample.hpp"

Example: "sample.cxx"

Data Types: char | string | cell

One or more full path names to libraries, specified as a string array, character vector, or cell array of character vectors. Use with the 'Libraries' argument. This value is required except for header-only libraries, which is a library defined completely by its header files. A shared library is one of the following:

  • On Microsoft® platforms, use a .dll dynamic-link library file.

  • On Linux® platforms, use a .so shared object file.

  • On macOS platforms, use a .dylib dynamic shared library file.

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

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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

One or more folders for included header files, specified as a string array, character vector, or cell array of character vectors. IncludePath is the full path name 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

Folder name used to generate the interface library, 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

Generated interface package name, 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, you must specify the package name as a valid MATLAB name. For example, this statement creates a myPackageInterface library file in the subfolder myPackage in the current folder.

clibgen.buildInterface({'h1.hpp','h2.hpp'},'PackageName','myPackage')

Data Types: char | string | cell

Option to display generation messages, specified as true or 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

Shape specifier for object pointers, specified as true or false. If TreatObjectPointerAsScalar is true, then MATLAB treats all object pointers in the library as scalars by specifying SHAPE as 1. Otherwise, the shape of the object pointer is unknown.

Data Types: logical

Shape and MATLAB type specifier for const character pointers, specified as true or false. If TreatConstCharPointerAsCString is true, then MATLAB 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

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

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

Whether to generate documentation from C++ files, specified as true or false. If GenerateDocumentationFromHeaderFiles is true, then MATLAB generates documentation from comments in C++ source files for display using the MATLAB doc command. If false, then MATLAB 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

Whether to return non-object C arrays, specified as true or false. If ReturnCArrays is true, then MATLAB returns C arrays (clib.array.*) for non-object C arrays. If false, then MATLAB returns numeric MATLAB arrays for non-object C arrays.

Data Types: logical

Whether to generate documentation from C++ files, specified as true or false. If GenerateDocumentationFromHeaderFiles is true, then MATLAB generates documentation from comments in C++ source files for display using the MATLAB doc command. If false, then MATLAB 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

One or more C++ source files, specified as a string array, character vector, or cell array of character vectors. Supported file extensions are .cpp and .cxx. If not in the current folder or on your MATLAB path, then the name includes the full or relative path to the file. A supporting source file must contain C++ code.

Example: "sample.cpp"

Data Types: char | string | cell

Limitations

See Also

Introduced in R2019a

MATLAB Documentation

Support