Main Content

clibgen.generateLibraryDefinition

Create definition file for C++ library

Description

The clibgen.generateLibraryDefinition function creates a MATLAB® Live Code definition file 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 shared library file), then you can choose any supported C++ compiler to build the interface library.

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

example

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

The name of the definition file is definelibName.mlx. 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.mlx. If you specify more than one interface generation file, then you must use the PackageName name-value argument to specify libName.

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

example

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

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

The files for this example are in a MATLAB examples folder. Generate the library definition file definematrixOperations.mlx from the matrixOperations.hpp header file on Windows®. For a Linux® example, see Header File and Shared Object File 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 shared library file.

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

Create the definematrixOperations.mlx library definition file.

clibgen.generateLibraryDefinition(hFile,IncludePath=iPath,Libraries=libFile)
Using MinGW64 Compiler (C++) compiler.
Generated definition file definematrixOperations.mlx and data file 'matrixOperationsData.xml' 
contain definitions for 10 constructs supported by MATLAB.
5 construct(s) require(s) additional definition. To include these construct(s) in the interface, 
edit the definitions in definematrixOperations.mlx.
Build using build(definematrixOperations).

The files for this example are in a MATLAB examples folder. Generate a library definition file named definematrixOps.mlx 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.mlx library definition file by setting the PackageName argument to "matrixOps".

clibgen.generateLibraryDefinition(hFile, ...
    SupportingSourceFiles=cFile, ...
    IncludePath=iPath, ...
    PackageName="matrixOps")
Using MinGW64 Compiler (C++) compiler.
Generated definition file definematrixOps.mlx and data file 'matrixOpsData.xml' 
contain definitions for 10 constructs supported by MATLAB.
5 construct(s) require(s) additional definition. To include these construct(s) in the interface, 
edit the definitions in definematrixOps.mlx.
Build using build(definematrixOps).

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

clibgen.generateLibraryDefinition(fullfile(matlabroot,"extern","examples","cpp_interface","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

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. 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 PackageName 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 file name, 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 file name 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", ...
PackageName="mylib", ...
OutputFolder="C:\work", ...
DefinedMacros=["mymacro1","mymacro2=0"], ...
UndefinedMacros="mymacro3", ...
OverwriteExistingDefinitionFiles=true);

File Selection

collapse all

Shared library file names, 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 shared 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. 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. 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.mlx using sample.hpp in the current folder and myLib.lib in the C:\myLib folder and writes the MLX file in the current folder.

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

Data Types: char | string | cell

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 shared library files are not required.

Example: "sample.cpp"

Data Types: char | string | cell

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

Configuration

collapse all

Generated interface package name, specified as a string scalar or a character vector. For more information, see Call Functions in C++ Shared Library.

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 definemylib.mlx in the current folder.

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

Data Types: char | string | cell

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.mlx in C:\work.

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

Data Types: char | string | cell

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.mlx 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

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

C++ Library Settings

collapse all

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

Definition Configurations

collapse all

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

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

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

Data Types: logical

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

Build Configurations

collapse all

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.

  • A combination of CPP and C files.

If CLinkage is false, then the function treats .h header files as CPP files. Use the default (CLinkage is false) when creating an interface from CPP files with C dependencies. In this case, the C file is specified by one of these arguments:

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

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

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

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

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

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 shared 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 File and Import Library File on Windows

    "A.hpp"

    Libraries="C:\Documents\MATLAB\A.lib"

    CPP header file and shared object file on Linux.

    • A.hpp

    • A.so in folder ~/MATLAB/

    Example: Header File and Shared Object File on Linux

    "A.hpp"

    Libraries="~/MATLAB/A.so"

    CPP header file and dynamic shared 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 CPP Source Files

    "A.hpp"

    SupportingSourceFiles="A.cpp"

    Multiple CPP header files, a source file, and a shared library file. Create interface named A.

    • Header files A.hpp and B.hpp

    • Source file A.cpp

    • Shared library file B.lib in C:\Documents\MATLAB\

    ["A.hpp","B.hpp"]

    PackageName="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 shared 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 shared 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"]

    PackageName="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"]

    PackageName="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 PackageName name-value argument. For example, if you set PackageName to "A", then when you call library function functionname from MATLAB, the syntax is clib.A.functionname.

Version History

Introduced in R2019a

expand all