clibgen.generateLibraryDefinition

Create definition file for C++ library

Syntax

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,Libraries=LibraryFiles)

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,SupportingSourceFiles=SourceFiles)

clibgen.generateLibraryDefinition(InterfaceGenerationFiles)

clibgen.generateLibraryDefinition(___,Name=Value)

Description

The clibgen.generateLibraryDefinition function creates a definition file with a .m file extension used to generate a MATLAB^® interface to a C++ library. Use this function to:

Select C/C++ files that define the interface. For guidance on which syntax to use, see "Files in Your Library" in Tips.
Select configurations used by the generate step.
Optionally specify configurations to use to define arguments.
Optionally specify compiler build configuration arguments.

After creating the definition file, you optionally can modify the contents to include functionality that the function cannot automatically define. For information about using a library definition file, see Define MATLAB Interface for C++ Library.

You need a C++ compiler that MATLAB supports. You must build the interface library using the same compiler that was used to build the C++ library. If your library is completely defined by source files (does not use a compiled library file), then you can choose any supported C++ compiler to build the interface library. For information about your C++ compilers, type:

mex -setup cpp

Call the build function on the definition file to create the MATLAB interface file.

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,Libraries=LibraryFiles) creates a definition file defined by InterfaceGenerationFiles and LibraryFiles.

The name of the definition file is definelibName.m (since R2022b). By default, libName is the name of the first file specified in InterfaceGenerationFiles. For example, if you specify a header file named mylibrary.hpp, then the function creates a definition file named definemylibrary.m. If you specify more than one interface generation file, then you must use the InterfaceName name-value argument to specify libName.

example

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

clibgen.generateLibraryDefinition(InterfaceGenerationFiles) for a library completely defined by InterfaceGenerationFiles. If your library includes a compiled library file, then you must specify a Libraries argument.

example

clibgen.generateLibraryDefinition(___,Name=Value) creates the file using one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes.

Use the Configuration options to specify the output folder for the definition file or the interface namespace.
Use the C++ Library Settings to specify compiler build and link options.
Use the Definition Configurations to define all specific argument types in the library.

Examples

collapse all

Create Definition File for Compiled Library

The files for this example are in a MATLAB examples folder. Generate the library definition file definematrixOperations.m from the matrixOperations.hpp header file on Windows^®. For a Linux^® example, see Header and C++ Compiled Library Files on Linux.

Create an InterfaceGenerationFiles argument hFile with the full path to the header file.

hFile = fullfile(matlabroot,"extern","examples","cpp_interface","matrixOperations.hpp");

The header file includes another header file. Create an IncludePath argument iPath with the full path to the folder containing the included header file.

iPath = fullfile(matlabroot,"extern","examples","cpp_interface");

Create a Libraries argument libFile with the full path to the compiled library file.

libFile = fullfile(matlabroot,"extern","examples","cpp_interface", ...
    "win64","mingw64","matrixOperations.lib");

Create the definematrixOperations.m library definition file.

clibgen.generateLibraryDefinition(hFile,IncludePath=iPath,Libraries=libFile)

C++ compiler set to 'MinGW64 Compiler (C++)'.
Definition file definematrixOperations.m contains definitions for 10 constructs supported by MATLAB.
- 5 constructs are fully defined.
- 5 constructs partially defined and commented out. 

To include the 5 undefined constructs in the interface, 
uncomment and complete the definitions in definematrixOperations.m.
To build the interface, call build(definematrixOperations).

Create Definition File for Library Defined by Header and CPP Files

The files for this example are in a MATLAB examples folder. Generate a library definition file named definematrixOps.m from the matrixOperations.hpp and matrixOperations.cpp files.

Create an InterfaceGenerationFiles argument hFile with the full path to the header file matrixOperations.hpp.

hFile = fullfile(matlabroot,"extern","examples","cpp_interface","matrixOperations.hpp");

The header file includes another header file. Create an IncludePath argument iPath with the full path to the folder containing the included header file.

iPath = fullfile(matlabroot,"extern","examples","cpp_interface");

Create a SupportingSourceFiles argument cFile with the full path to the C++ source file matrixOperations.cpp.

cFile = fullfile(matlabroot,"extern","examples","cpp_interface","matrixOperations.cpp");

Create the definematrixOps.m library definition file by setting the InterfaceName argument to "matrixOps".

clibgen.generateLibraryDefinition(hFile, ...
    SupportingSourceFiles=cFile, ...
    IncludePath=iPath, ...
    InterfaceName="matrixOps")

C++ compiler set to 'MinGW64 Compiler (C++)'.
Definition file definematrixOps.m contains definitions for 10 constructs supported by MATLAB.
- 5 constructs are fully defined.
- 5 constructs partially defined and commented out. 

To include the 5 undefined constructs in the interface, 
uncomment and complete the definitions in definematrixOps.m.
To build the interface, call build(definematrixOps).

Create Definition File for Header-Only Library

Generate the library definition file defineschool.m from the school.hpp header file.

clibgen.generateLibraryDefinition(fullfile(matlabroot,"extern","examples", ...
    "cpp_interface","school.hpp"))

C++ compiler set to 'MinGW64 Compiler (C++)'.
Definition file defineschool.m contains definitions for 21 constructs supported by MATLAB.
- 20 constructs are fully defined.
- 1 construct partially defined and commented out.

To include the 1 undefined construct in the interface, 
uncomment and complete the definitions in defineschool.m.
To build the interface, call build(defineschool).

Input Arguments

collapse all

`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 "Files in Your Library" in Tips.

Files for specifying InterfaceGenerationFiles and SupportingSourceFiles arguments are:

Header files, with file extensions .h, .hpp, or .hxx. A header file without an extension is also supported. If you set the CLinkage argument to true, then code in .h header files must be C++ compatible C code.
If you specify more than one interface generation file, then you must use the InterfaceName argument.
Source code files, with file extensions .c, .cpp, or .cxx. For information about using C source files, see CLinkage.

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 to specify the Libraries argument.

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 filename, then the function looks for a library with the same name, in the same folder as the header file. The library must have a platform-specific filename extension. If the library has a different name or is not in the same folder, then use the Libraries argument.

The function 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"

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

File Selection

collapse all

`Libraries` — Compiled library filenames
empty (default) | string array | character vector | cell array of character vectors

Compiled library filenames, specified as a string array, character vector, or cell array of character vectors. This value is required except if the library is completely defined by the files specified by the InterfaceGenerationFiles argument and the SupportingSourceFiles name-value argument.

A library is one of these:

On Windows platforms:
- For compiled libraries, specify a .lib import library file.
  If the .lib file is not available and the library is compiled with a supported Microsoft^® Visual Studio^® compiler, then you can specify a .dll dynamic-link library file (since R2021a). For example:
  clibgen.generateLibraryDefinition("A.hpp",Libraries="A.dll")
- For static libraries, specify a .lib file. For example:
  clibgen.generateLibraryDefinition("A.hpp",Libraries="A.lib")
  If the library is compiled with a supported MinGW-w64 compiler, then you can specify a .a static library file (since R2022a). For example:
  clibgen.generateLibraryDefinition("A.hpp",Libraries="A.a")
On Linux platforms, specify a .so shared object file or a .a static library file.
On macOS platforms, specify a .dylib dynamic shared library file or a .a static library file.

For example, this statement creates definesample.m using sample.hpp in the current folder and myLib.lib in the C:\myLib folder and writes the definition file in the current folder.

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

Since R2020b

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

`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

`RootPaths` — Starting pathname
empty (default) | scalar dictionary

Since R2024a

Starting pathname for publishers who plan to share library definition files, specified as a scalar dictionary, where key is a variable name chosen by the publisher and value is a relative pathname. The dictionary entries are specified as string scalars or character vectors. For example, on your computer, the starting pathname to the library files is c:\user1\libname. Another publisher has the same library version located in folder c:\user2\libname. Choose a key variable name and pass that name to the other publisher, who uses it to identify their local folder in the clibgen.generateLibraryDefinition function.

Identify the local path to files specified in these arguments, and put the path in a RootPaths dictionary argument:

InterfaceGenerationFiles
Libraries
IncludePath
SupportingSourceFiles
OutputFolder

Then replace the local path in any of these argument names with the RootPaths key by using the < and > tags. This enables another publisher to specify their own local path in the RootPaths key-value argument which MATLAB uses to identify the path in these arguments. For example, these statements create a library definition file named definemyLib.m. The dictionary key is rootpath, and the library files are located on your computer in C:\user1\libname.

startpaths = dictionary;
startpaths("rootpath") = "C:\user1\libname\";
clibgen.generateLibraryDefinition( ...
    ["<rootpath>\src\header1.hpp" "<rootpath>\include\header2.hpp"], ...
    IncludePath="<rootpath>\include", ...
    Libraries="<rootpath>\lib\libname.lib", ...
    OutputFolder="<rootpath>\MATLAB", ...
    RootPaths=startpaths, ...
    InterfaceName="myLib");

If another publisher has the same version of the library in the same file structure, but under a root folder named C:\user2\libname, then you can give the publisher your definemyLib.m and myLibData.xml files with these instructions for building the interface.

libdef = definemyLib;
%myPath = location of files that define library in local folder
libdef.RootPaths("rootpath") = myPath;
libdef.build

Configuration

collapse all

`InterfaceName` — Generated interface namespace
header filename (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 definemylib.m in the current folder.

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

Use the InterfaceName to call the library from MATLAB. For example, to call function myfunc in library interface libname, type:

clib.libname.myfunc

For more information, see Call Functions in C++ Compiled Library.

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. Verify that the folder is on your MATLAB path before calling the build function. This statement creates definemyHeader.m in C:\work.

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

Data Types: char | string | cell

`OverwriteExistingDefinitionFiles` — Option to overwrite library definition files
`false` or `0` (default) | `true` or `1`

Since R2021b

Option to overwrite library definition files, specified as a numeric or logical 1 (true) or 0 (false). A definition file is of the form definelibName.m or definelibname.m. Set OverwriteExistingDefinitionFiles to true to overwrite the existing files. Use this option to regenerate the definition file.

Caution

When you use this option, the function deletes the files, including edits you might have made to the files.

Data Types: logical

`Verbose` — Option to display generation messages
`false` or `0` (default) | `true` or `1`

Option to display generation messages, specified as a numeric or logical 1 (true) or 0 (false). If Verbose is true, then the function displays generation messages to the command window while creating the definition file and for the build command. This statement creates defineh1.m and displays messages to the command window.

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

For more information, see Messages About Unsupported Types.

Data Types: logical

C++ Library Settings

collapse all

`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

`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

`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

Definition Configurations

collapse all

`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

`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

Limitations

Saving LibraryDefinition object definelibName into a MAT-file is not supported.
Avoid non-ASCII characters in folder and filenames, as some locale settings do not support those characters. For information about locale, see Set Locale and Display Language.

Tips

To recreate a library definition file, call clibgen.generateLibraryDefinition with name-value argument OverwriteExistingDefinitionFiles set to true. When you use this option, the function deletes the files, including edits you might have made to the files.
For troubleshooting information, see Troubleshooting C++ Library Definition Issues.

Your library might contain combinations of C/C++ header files, source files, and compiled library files. This table shows how to set the arguments to clibgen.generateLibraryDefinition depending on what types of files define your library.

Files in Your Library	`InterfaceGenerationFiles` Argument	Name-Value Argument(s)
Single CPP header file and import library file on Windows. `A.hpp` `A.lib` import library file in folder `C:\Documents\MATLAB\` Example: Header and C++ Compiled Library Files on Windows	`"A.hpp"`	`Libraries="C:\Documents\MATLAB\A.lib"`
CPP header file and compiled object file on Linux. `A.hpp` `A.so` in folder `~/MATLAB/` Example: Header and C++ Compiled Library Files on Linux	`"A.hpp"`	`Libraries="~/MATLAB/A.so"`
CPP header file and dynamic compiled library file on macOS. `A.hpp` `A.dylib` in folder `$home/Documents/MATLAB`	`"A.hpp"`	`Libraries="$home/Documents/MATLAB/A.dylib"`
Completely defined by CPP header and source files. No library files. Header file `A.hpp` Source file `A.cpp` Example: Header and C++ Source Files	`"A.hpp"`	`SupportingSourceFiles="A.cpp"`
Multiple CPP header files, a source file, and a compiled library file. Create interface named `A`. Header files `A.hpp` and `B.hpp` Source file `A.cpp` Compiled library file `B.lib` in `C:\Documents\MATLAB\`	`["A.hpp","B.hpp"]`	`InterfaceName="A"`^a `Libraries="C:\Documents\MATLAB\B.lib"` `SupportingSourceFiles="A.cpp"`
CPP header-only library. The library is completely defined in a header file and does not have a compiled library file. `A.hpp` Example: Header-Only HPP File	`"A.hpp"`	Not applicable
Completely defined in a CPP source file and does not have a compiled library file. `A.cpp`	`"A.cpp"`	Not applicable
Completely defined by C header and source files. No library files. `A.h` `A.c`	`"A.h"`	`SupportingSourceFiles="A.c"` `CLinkage=true`
Single C header file and import library file on Windows. `A.h` `A.lib` in `C:\Documents\MATLAB\`	`"A.h"`	`Libraries="C:\Documents\MATLAB\A.lib"` `CLinkage=true`
The CPP source file depends on C header and source files. Source file `myCPP.cpp` Header and source files `A.h` and `A.c` in `C:\Documents\MATLAB\`	`"myCPP.cpp"`	`SupportingSourceFiles="C:\Documents\MATLAB\A.c"`
The C library depends on a CPP source file. Header and source files `A.h` and `A.c` in `C:\Documents\MATLAB\` Source file `myCPP.cpp`	`["C:\Documents\MATLAB\A.h", "myCPP.cpp"]`	`InterfaceName="myCPP"` `SupportingSourceFiles="C:\Documents\MATLAB\A.c"` `CLinkage=true`
Library defined by CPP and C header files with corresponding library files in `C:\Documents\MATLAB\`. `myCPP.hpp` `myCPP.lib` `myC.h` `myC.lib`	`["myCPP.hpp","myC.h"]`	`InterfaceName="myCPP"` `Libraries=["C:\Documents\MATLAB\myCPP.lib","C:\Documents\MATLAB\myC.lib"]` `CLinkage=true`
The C header file depends on a CPP header file. `A.h` `B.hpp` in `C:\Documents\MATLAB\`	`"A.h"`	`IncludePath="C:\Documents\MATLAB\"`
^a Because you have multiple header files, you must set the `InterfaceName` name-value argument. For example, if you set `InterfaceName` to `"A"`, then when you call library function `functionname` from MATLAB, the syntax is `clib.A.functionname`.

Alternative Functionality

Live Task

Call the clibPublishInterfaceWorkflow function to use the Generate C++ Interface live task.

Version History

Introduced in R2019a

expand all

R2024a: Specify file paths relative to absolute path

You can share a MATLAB interface to a C++ library, for example by uploading the library definition files to GitHub^®. If another publisher has the same C++ library version and file structure as you, then they can download the definition files and build the interface.

The files used to generate the interface, such as the InterfaceGenerationFiles argument to the clibgen.generateLibraryDefinition function, contain file specifications based on the folder structure of your computer. Starting in R2024a, you can specify file paths relative to an absolute path using the RootPaths name-value argument. Then another publisher can build the interface by specifying the RootPaths argument based on the folder structure on their computer. The other publisher must have the same C++ library version and file structure as you have.

For an example, see Define Pathnames to Share Library Definition Files.

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.

R2022b: Library definition file has `.m` file extension

The clibgen.generateLibraryDefinition function creates a library definition file with a .m file extension. The function no longer creates a file with the .mlx file extension. You can continue to modify and build existing library definition files with the .mlx file extension.

R2022a: Create interface for libraries with C files built with C compilers

To create interfaces for libraries with C files built with C compilers, use the CLinkage name-value argument.

R2022a: Specify compiler and linker flags used to build an interface

To specify compiler and linker flags to build an interface, use the AdditionalCompilerFlags and AdditionalLinkerFlags name-value arguments.

R2022a: Support for `.a` static libraries

You can specify static libraries with .a file extensions. For more information, see Libraries.

R2021b: Overwrite existing library definition files

To regenerate a library definition file, overwrite the existing files using the OverwriteExistingDefinitionFiles name-value argument.

R2021a: Create interface from header and source CPP files

You can pass a .cpp or .hpp file in the SupportingSourceFiles name-value argument.

R2021a: Support for `.dll` compiled libraries

You can specify libraries with .dll file extensions for Microsoft Visual Studio compilers. For more information, see Libraries.

R2020b: Create interface from CPP source files

You can build a MATLAB interface to a C++ library or algorithm from source files that contain complete implementations for the library. For more information, see SupportingSourceFiles.

R2020a: Control lifetime management of objects

If a library creates an object, then the library is responsible for releasing the memory. Likewise, if MATLAB creates the object, then MATLAB is responsible for releasing the memory. To overwrite this default behavior, use the ReleaseOnCall and DeleteFcn name-value arguments.

R2019b: Specify shape for object pointer types for all functions in library

To specify the shape for object pointer types as scalar for all functions in a library, use the TreatObjectPointerAsScalar name-value argument.

R2019b: Specify shape for `const char *` pointer types for all functions in library

To specify the shape for const char * pointer types as scalar for all functions, use TreatConstCharPointerAsCString.

R2019b: Include or exclude macro definitions

To include or exclude macro definitions, use the DefinedMacros and UndefinedMacros name-value arguments.

clibgen.generateLibraryDefinition

Syntax

Description

Examples

Create Definition File for Compiled Library

Create Definition File for Library Defined by Header and CPP Files

Create Definition File for Header-Only Library

Input Arguments

InterfaceGenerationFiles — Files to generate the interface string array | character vector | cell array of character vectors

Name-Value Arguments

Libraries — Compiled library filenames empty (default) | string array | character vector | cell array of character vectors

SupportingSourceFiles — C/C++ source files string array | character vector | cell array of character vectors

IncludePath — Folders for included header files empty (default) | string array | character vector | cell array of character vectors

RootPaths — Starting pathname empty (default) | scalar dictionary

InterfaceName — Generated interface namespace header filename (default) | string scalar | character vector

OutputFolder — Folder name for the generated definition file current folder (default) | string scalar | character vector

OverwriteExistingDefinitionFiles — Option to overwrite library definition files false or 0 (default) | true or 1

Verbose — Option to display generation messages false or 0 (default) | true or 1

CLinkage — Option to specify how to parse .h header files false or 0 (default) | true or 1

DefinedMacros — List of macro definitions empty (default) | scalar string | row vector of scalar strings

UndefinedMacros — List of macro cancellations empty (default) | scalar string | row vector of scalar strings

AdditionalCompilerFlags — Compiler flags string array | character vector | cell array of character vectors

AdditionalLinkerFlags — Linker flags string array | character vector | cell array of character vectors

TreatObjectPointerAsScalar — Shape specifier for object pointers false or 0 (default) | true or 1

TreatConstCharPointerAsCString — Shape and MATLAB type specifier for const character pointers false or 0 (default) | true or 1

ReturnCArrays — Option specifying how to return non-object C++ arrays true or 1 (default) | false or 0

GenerateDocumentationFromHeaderFiles — Option to generate documentation from C++ files true or 1 (default) | false or 0

Limitations

Tips

Alternative Functionality

Live Task

Version History

R2024a: Specify file paths relative to absolute path

R2024a: PackageName name-value argument renamed to InterfaceName

R2022b: Library definition file has .m file extension

R2022a: Create interface for libraries with C files built with C compilers

R2022a: Specify compiler and linker flags used to build an interface

R2022a: Support for .a static libraries

R2021b: Overwrite existing library definition files

R2021a: Create interface from header and source CPP files

R2021a: Support for .dll compiled libraries

R2020b: Create interface from CPP source files

R2020a: Control lifetime management of objects

R2019b: Specify shape for object pointer types for all functions in library

R2019b: Specify shape for const char * pointer types for all functions in library

R2019b: Include or exclude macro definitions

See Also

Topics

`InterfaceGenerationFiles` — Files to generate the interface
string array | character vector | cell array of character vectors

`Libraries` — Compiled library filenames
empty (default) | string array | character vector | cell array of character vectors

`SupportingSourceFiles` — C/C++ source files
string array | character vector | cell array of character vectors

`IncludePath` — Folders for included header files
empty (default) | string array | character vector | cell array of character vectors

`RootPaths` — Starting pathname
empty (default) | scalar dictionary

`InterfaceName` — Generated interface namespace
header filename (default) | string scalar | character vector

`OutputFolder` — Folder name for the generated definition file
current folder (default) | string scalar | character vector

`OverwriteExistingDefinitionFiles` — Option to overwrite library definition files
`false` or `0` (default) | `true` or `1`

`Verbose` — Option to display generation messages
`false` or `0` (default) | `true` or `1`

`CLinkage` — Option to specify how to parse .h header files
`false` or `0` (default) | `true` or `1`

`DefinedMacros` — List of macro definitions
empty (default) | scalar string | row vector of scalar strings

`UndefinedMacros` — List of macro cancellations
empty (default) | scalar string | row vector of scalar strings

`AdditionalCompilerFlags` — Compiler flags
string array | character vector | cell array of character vectors

`AdditionalLinkerFlags` — Linker flags
string array | character vector | cell array of character vectors

`TreatObjectPointerAsScalar` — Shape specifier for object pointers
`false` or `0` (default) | `true` or `1`

`TreatConstCharPointerAsCString` — Shape and MATLAB type specifier for `const` character pointers
`false` or `0` (default) | `true` or `1`

`ReturnCArrays` — Option specifying how to return non-object C++ arrays
`true` or `1` (default) | `false` or `0`

`GenerateDocumentationFromHeaderFiles` — Option to generate documentation from C++ files
`true` or `1` (default) | `false` or `0`

R2024a: `PackageName` name-value argument renamed to `InterfaceName`

R2022b: Library definition file has `.m` file extension

R2022a: Support for `.a` static libraries

R2021a: Support for `.dll` compiled libraries

R2019b: Specify shape for `const char *` pointer types for all functions in library