Main Content

clibgen.generateLibraryDefinition

Create definition file for C++ library

Description

example

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,'Libraries',LibraryFiles) creates a MATLAB® Live Code definition file used to generate a MATLAB interface to the C++ library defined by InterfaceGenerationFiles and LibraryFiles. For examples to call clibgen.generateLibraryDefinition, see "What files do you have in your library?" in Tips.

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 first file specified in InterfaceGenerationFiles. If you specify more than one interface generation file, then you must use the PackageName name-value pair 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 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.

example

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,'Libraries',LibraryFiles,'SupportingSourceFiles',SupportingSourceFiles) creates a definition file to a library defined by multiple header files, source files, and, if required, shared library files.

example

clibgen.generateLibraryDefinition(InterfaceGenerationFiles) creates a definition file to a library completely defined by InterfaceGenerationFiles.

If your library includes a shared library file, then you must specify a 'Libraries' argument.

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

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.

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

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

Generate the library definition file definematrixOps.mlx from the matrixOperations.hpp and matrixOperations.cpp files.

headerFile = fullfile(matlabroot,"extern","examples","cpp_interface","matrixOperations.hpp");
sourceFile = fullfile(matlabroot,"extern","examples","cpp_interface","matrixOperations.cpp");
iPath = fullfile(matlabroot,"extern","examples","cpp_interface");

clibgen.generateLibraryDefinition(headerFile,...
    "SupportingSourceFiles",sourceFile,...
    "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.

headerFile = fullfile(matlabroot,"extern","examples","cpp_interface","school.hpp");
clibgen.generateLibraryDefinition(headerFile)
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. If not in the current folder or on your MATLAB path, then the name includes the full or relative path to the file.

Files for specifying InterfaceGenerationFiles and SupportingSourceFiles 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 .cpp or .cxx.

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

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"

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' name-value pair argument. This value is required except if the library is completely defined by the files specified by the InterfaceGenerationFiles argument and the name-value pair argument 'SupportingSourceFiles'.

A library is one of the following:

  • On Windows platforms:

    • For shared libraries, specify a .lib import library file.

      If the .lib file is not available and the library is complied 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")
  • On Linux platforms, specify a .so shared object file.

  • On macOS platforms, specify 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

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.generateLibraryDefinition(["hfile1.hpp","hfile2.hpp"],"Libraries","hfile1.lib",...
"IncludePath","C:\mylib\include","PackageName","mylib","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 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

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.

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

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 overwrite library definition files, specified as true or false. A definition file is of the form definelibName.mlx or definelibname.m. Set OverwriteExistingDefinitionFiles to true to automatically overwrite the existing file(s). This option is useful when creating and modifying the definition file.

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

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, call clibgen.generateLibraryDefinition with name-value argument OverwriteExistingDefinitionFiles set to true. When you use this option, MATLAB 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 header files, CPP 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.

    What files do you have in your library?

    Argument
    InterfaceGenerationFiles
    Name-Value Argument
    "Libraries"
    Name-Value Argument
    "SupportingSourceFiles"

    Single 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"

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

     

    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"

    "~/MATLAB/A.so"

     

    Header file and dynamic shared library file on macOS.

    • A.hpp

    • A.dylib in folder $home/Documents/MATLAB

    "A.hpp"

    "$home/Documents/MATLAB/A.dylib"

     

    Completely defined by header file and .cpp source file. No library files.

    • Header file A.hpp

    • Source file A.cpp

    Example: Header and CPP Source Files

    "A.hpp"

     

    "A.cpp"

    Multiple 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"]
    [a]

    "C:\Documents\MATLAB\B.lib"

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

      

    The library is completely defined in a .CPP file and does not have a shared library file.

    • A.cpp

    "A.cpp"

      

    [a] Because you have multiple header files, you must set the "PackageName" name-value argument. For example, use the name "A". Then when you call library function functionname from MATLAB, the syntax is clib.A.functionname.

Introduced in R2019a