clibgen.generateLibraryDefinition

Create definition file for C++ library

collapse all in page

Syntax

clibgen.generateLibraryDefinition(CppFiles)
clibgen.generateLibraryDefinition(CppFiles,'Libraries',SharedLibrary)
clibgen.generateLibraryDefinition(CppFiles,___,Name,Value)

Description

example

clibgen.generateLibraryDefinition(CppFiles) creates a MATLAB® Live Code definition file used to generate a MATLAB interface to the C++ library defined by CppFiles.

The name of the definition file is definelibName.mlx. For more information about using this file, see Define MATLAB Interface for C++ Library. By default, libName is the name of the file specified in CppFiles. 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.

Use the build method to create the interface. 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.

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

clibgen.generateLibraryDefinition(CppFiles,___,Name,Value) creates the file 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 a writable folder.

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

Generate the library definition file defineschool.mlx.

clibgen.generateLibraryDefinition("school.hpp")
Using MinGW64 Compiler (C++) compiler.
Generated definition file defineschool.mlx and data file 'schoolData.xml' contain definitions for 
21 constructs supported by MATLAB.
1 construct(s) require(s) additional definition. To include these construct(s) in the interface, 
edit the definitions in defineschool.mlx.
Build using build(defineschool).

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, this statement creates the interface library file in the subfolder myHeader in the current folder.

clibgen.generateLibraryDefinition('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, this statement creates definesample.mlx using myLib.lib in C:\myLib\ and writes it in the current folder.

clibgen.generateLibraryDefinition("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.generateLibraryDefinition({"hfile1.hpp","hfile2.hpp"},"Libraries","mylib.lib","IncludePath","C:\mylib\include","PackageName","mypackage","OutputFolder","C:\work","DefinedMacros",["mymacro1","mymacro2=0"],"UndefinedMacros","mymacro3");

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 definition file, specified as a string scalar or a character vector. Verify that the folder is on your MATLAB path before calling the build function. This statement creates definemyHeader.mlx in C:\work.

clibgen.generateLibraryDefinition("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 definemyPackage.mlx in the subfolder myPackage in the current folder.

clibgen.generateLibraryDefinition({"h1.hpp","h2.hpp"},"PackageName","myPackage")

Data Types: char | string | cell

Option to display generation messages, specified as true or false. If Verbose is true, then MATLAB displays generation messages to the command window while creating the definition file. This statement creates defineh1.mlx and displays messages to the command window.

clibgen.generateLibraryDefinition("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

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

  • Saving LibraryDefinition object definelibName into a MAT-file is not supported.

  • Avoid non-ASCII characters in folder and file names, as some locale settings might not support those characters. For information about locale, see Locale Setting Concepts for Internationalization.

Tips

  • To recreate a library definition file, first delete the definelibName.mlx file, then call clibgen.generateLibraryDefinition.

See Also

| |

Topics

External Websites

Introduced in R2019a

MATLAB Documentation

Support