Main Content

clibgen.buildInterface

Create interface to C++ library without definition file

Description

clibgen.buildInterface(HeaderFiles,'Libraries',Libraries) 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(HeaderFiles,'Libraries',Libraries,'SupportingSourceFiles',SupportingSourceFiles) creates an interface to a library defined by multiple header files, source files, and, if required, shared library files.

example

clibgen.buildInterface(HeaderFiles) 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(HeaderFiles,___,Name,Value) generates the interface using one or more name-value pair arguments. Use this option with any of the input argument combinations in the previous syntaxes.

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' for clib package '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 construct(s) need(s) 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.

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 Header-Only HPP File. 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. If not in the current folder or on your MATLAB path, then the name 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

One or more 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 LibraryFiles 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

One or more C++ source files, specified as a string array, character vector, or cell array of character vectors. Use with the 'SupportingSourceFiles' name-value pair argument. 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.

For more information, see "What files do you have in your library?" in Tips.

If the library is completely defined by header and .cpp source files, then shared library files are not required.

Example: "sample.cpp"

Data Types: char | string | cell

Name-Value 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. Each value in IncludePath must be 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 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

Generated interface 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 mylibInterface library file in the subfolder mylib in the current folder.

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

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.

Introduced in R2019b.

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 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++ 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

Limitations

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.

Introduced in R2019a