clibgen.generateLibraryDefinition

为 C++ 库创建定义文件

全页折叠

语法

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,Libraries=LibraryFiles)
clibgen.generateLibraryDefinition(InterfaceGenerationFiles,SupportingSourceFiles=SourceFiles)
clibgen.generateLibraryDefinition(InterfaceGenerationFiles)
clibgen.generateLibraryDefinition(___,Name=Value)

说明

clibgen.generateLibraryDefinition 函数创建一个具有 .m 文件扩展名的定义文件，用于生成 C++ 库的 MATLAB® 接口。使用此函数可以：

  • 选择定义接口的 C/C++ 文件。有关要使用哪种语法的指导，请参阅提示中的“库中的文件”。

  • 选择生成步骤使用的配置。

  • （可选）指定用于定义参量的配置。

  • （可选）指定编译器编译配置参量。

创建定义文件后，您可以选择修改内容，以包含函数无法自动定义的功能。有关使用库定义文件的信息，请参阅Define MATLAB Interface for C++ Library。

您需要 MATLAB 支持的 C++ 编译器。您必须使用与编译该 C++ 库时所用的相同编译器来编译接口库。如果您的库完全由源文件定义（不使用编译库文件），则您可以选择任何受支持的 C++ 编译器来编译接口库。有关 C++ 编译器的信息，请键入：

mex -setup cpp

对定义文件调用 build 函数，以创建 MATLAB 接口文件。

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,Libraries=LibraryFiles) 创建由 InterfaceGenerationFiles 和 LibraryFiles 定义的定义文件。

定义文件的名称是 definelibName.m (自 R2022b 起)。默认情况下，libName 是 InterfaceGenerationFiles 中指定的第一个文件的文件名。例如，如果您指定名为 mylibrary.hpp 的头文件，则函数会创建一个名为 definemylibrary.m 的定义文件。如果指定多个接口生成文件，则必须使用 InterfaceName 名称-值参量来指定 libName。

示例

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,SupportingSourceFiles=SourceFiles) 创建一个由多个头文件、源文件和（如果需要）编译库文件定义的库的接口。

clibgen.generateLibraryDefinition(InterfaceGenerationFiles) 创建一个完全由 InterfaceGenerationFiles 定义的库。如果您的库包含编译库文件，则必须指定 Libraries 参量。

示例

clibgen.generateLibraryDefinition(___,Name=Value) 使用一个或多个名称-值参量创建该文件。可将此选项与上述语法中的任何输入参量组合一起使用。

  • 使用配置选项指定定义文件的输出文件夹或接口命名空间。

  • 使用C++ 库设置指定编译器编译和链接选项。

  • 使用定义配置定义库中所有特定的参量类型。

示例

全部折叠

此示例的文件位于 MATLAB examples 文件夹中。从 Windows® 上的 matrixOperations.hpp 头文件生成库定义文件 definematrixOperations.m。有关 Linux® 示例，请参阅Linux 上的头文件和 C++ 编译的库文件。

使用头文件的完整路径创建一个 InterfaceGenerationFiles 参量 hFile。

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

该头文件包含另一个头文件。使用包含被包含头文件的文件夹的完整路径创建一个 IncludePath 参量 iPath。

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

使用编译库文件的完整路径创建一个 Libraries 参量 libFile。

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

创建 definematrixOperations.m 库定义文件。

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

此示例的文件位于 MATLAB examples 文件夹中。从 matrixOperations.hpp 和 matrixOperations.cpp 文件生成名为 definematrixOps.m 的库定义文件。

使用头文件 matrixOperations.hpp 的完整路径创建 InterfaceGenerationFiles 参量 hFile。

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

该头文件包含另一个头文件。使用包含被包含头文件的文件夹的完整路径创建一个 IncludePath 参量 iPath。

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

使用 C++ 源文件 matrixOperations.cpp 的完整路径创建 SupportingSourceFiles 参量 cFile。

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

通过将 InterfaceName 参量设置为 "matrixOps"，创建 definematrixOps.m 库定义文件。

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

从 school.hpp 头文件生成库定义文件 defineschool.m。

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

输入参数

全部折叠

生成接口的文件，指定为字符串数组、字符向量或字符向量元胞数组。如果不在当前文件夹或您的 MATLAB 路径中，则该参量包括文件的完整或相对路径。有关详细信息，请参阅提示中的“库中的文件”。

用于指定 InterfaceGenerationFiles 和 SupportingSourceFiles 参量的文件有：

  • 头文件，文件扩展名为 .h、.hpp 或 .hxx。也支持不带扩展名的头文件。如果将 CLinkage 参量设置为 true，则 .h 头文件中的代码必须为与 C++ 兼容的 C 代码。

    如果指定多个接口生成文件，则必须使用 InterfaceName 参量。

  • 源代码文件，文件扩展名为 .c、.cpp 或 .cxx。有关使用 C 源文件的信息，请参阅 CLinkage。

这些头文件必须包含由库导出的所有函数的声明。您应该能够在 C++ 开发环境中编译它们，并在 C++ 应用程序中使用该功能。如果库完全由头文件定义（只包含头文件的库），则您不需要指定 Libraries 参量。

如果主函数头文件包含不同文件夹中头文件的 #include 语句，则使用 IncludePath 参量指定这些路径。

如果您提供一个头文件名，则该函数会在头文件所在的文件夹中查找同名的库。该库必须具有特定于平台的文件扩展名。如果库具有不同名称或不在同一文件夹中，则使用 Libraries 参量。

该函数将接口文件写入当前文件夹的子文件夹中，除非您指定 OutputFolder 参量。该子文件夹的名称是第一个头文件的名称（不带文件扩展名）。例如，以下语句在当前文件夹的子文件夹 myHeader 中创建接口库文件。

clibgen.generateLibraryDefinition("myHeader.hpp")

示例: "sample.hpp"

数据类型: char | string | cell

名称-值参数

全部展开

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但对各个参量对组的顺序没有要求。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: 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);

文件选择

全部展开

编译库文件名，指定为字符串数组、字符向量或字符向量元胞数组。除非库完全由 InterfaceGenerationFiles 参量和 SupportingSourceFiles 名称-值参量指定的文件定义，否则此值是必需的。

库是以下各项之一：

  • 在 Windows 平台上：

    • 对于编译库，请指定 .lib 导入库文件。

      如果 .lib 文件不可用，并且库是使用支持的 Microsoft® Visual Studio® 编译器编译的，则可以指定 .dll 动态链接库文件 (自 R2021a 起)。例如：

      clibgen.generateLibraryDefinition("A.hpp",Libraries="A.dll")

    • 对于静态库，指定 .lib 文件。例如：

      clibgen.generateLibraryDefinition("A.hpp",Libraries="A.lib")

      如果库是用支持的 MinGW-w64 编译器编译的，则您可以指定 .a 静态库文件 (自 R2022a 起)。例如：

      clibgen.generateLibraryDefinition("A.hpp",Libraries="A.a")

  • 在 Linux 平台上，指定一个 .so 共享目标文件或一个 .a 静态库文件。

  • 在 macOS 平台上，指定一个 .dylib 动态共享库文件或一个 .a 静态库文件。

例如，以下语句使用当前文件夹中的 sample.hpp 和 C:\myLib 文件夹中的 myLib.lib 创建 definesample.m，并将该定义文件写入当前文件夹中。

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

数据类型: char | string | cell

C++ 源文件，指定为字符串数组、字符向量或字符向量元胞数组。与 SupportingSourceFiles 名称-值参量结合使用。支持的文件扩展名为 .c、.cpp 和 .cxx。如果不在当前文件夹或您的 MATLAB 路径中，则该参量包括文件的完整或相对路径。支持源文件必须包含 C/C++ 代码。

有关详细信息，请参阅提示中的“库中的文件”。

有关编译 C 源文件的信息，请参阅 CLinkage。

如果库完全由头文件和 C++ 源文件定义，则不要求编译库文件。

示例: "sample.cpp"

数据类型: char | string | cell

用于所包含的头文件的文件夹，指定为字符串数组、字符向量或字符向量元胞数组。IncludePath 中的每个值都必须为在编译头文件期间要包含的文件夹的完整路径名称。

如果主函数头文件包含不同文件夹中头文件的 #include 语句，则使用 IncludePath 参量指定这些路径。

数据类型: char | string | cell

自 R2024a 起

计划共享库定义文件的发布者的起始路径名称，指定为标量字典，其中 key 是发布者选择的变量名称，value 是相对路径名称。字典条目指定为字符串标量或字符向量。例如，在您的计算机上，库文件的起始路径名称是 c:\user1\libname。另一个发布者在文件夹 c:\user2\libname 中有相同的库版本。选择一个键变量名称，并将该名称传递给其他发布者，他们使用该名称在 clibgen.generateLibraryDefinition 函数中标识其本地文件夹。

确定在这些参量中指定的文件的本地路径，并将该路径放入 RootPaths 字典参量中：

然后，通过使用 < 和 > 标记，将上述任一参量名称中的本地路径替换为 RootPaths 键。这使得另一个发布者能够通过 RootPaths 键-值参量指定他们自己的本地路径，这是 MATLAB 标识这些参量中的方法。例如，以下语句创建一个名为 definemyLib.m 的库定义文件。字典键为 rootpath，库文件位于您计算机上的 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");

如果另一个发布者在相同的文件结构中有相同版本的库，但在名为 C:\user2\libname 的根文件夹下，则您可以向该发布者提供您的 definemyLib.m 和 myLibData.xml 文件，其中包含这些用于编译接口的说明。

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

配置

全部展开

自 R2024a 起

生成的接口命名空间，指定为字符串标量或字符向量。对于从单个头文件创建的接口，默认值为头文件的名称。对于多个头文件，InterfaceName 必须为有效的 MATLAB 名称。

例如，以下语句在当前文件夹中创建 definemylib.m。

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

使用 InterfaceName 从 MATLAB 调用库。例如，要调用库接口 libname 中的函数 myfunc，请键入：

clib.libname.myfunc

有关详细信息，请参阅Call Functions in C++ Compiled Library。

数据类型: char | string | cell

生成的定义文件的文件夹名称，指定为字符串标量或字符向量。在调用 build 函数之前，验证文件夹是否在您的 MATLAB 路径中。以下语句在 C:\work 中创建 definemyHeader.m。

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

数据类型: char | string | cell

自 R2021b 起

覆盖库定义文件的选项，指定为数值或逻辑值 1 (true) 或 0 (false)。定义文件的形式为 definelibName.m 或 definelibname.m。将 OverwriteExistingDefinitionFiles 设置为 true 以覆盖现有文件。使用此选项重新生成定义文件。

小心

使用此选项时，该函数会删除文件，包括您可能对文件所做的编辑。

数据类型: logical

显示生成消息的选项，指定为数值或逻辑值 1 (true) 或 0 (false)。如果 Verbose 为 true，则该函数会在创建定义文件时和运行 build 命令时在命令行窗口中显示生成消息。以下语句创建 defineh1.m 并在命令行窗口中显示消息。

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

有关详细信息，请参阅Messages About Unsupported Types。

数据类型: logical

C++ 库设置

全部展开

自 R2022a 起

指定如何解析和编译 .h 头文件的选项，指定为数值或逻辑值 1 (true) 或 0 (false)。

如果 CLinkage 为 true，则该函数将 InterfaceGenerationFiles 参量中的 .h 头文件视为 C 头文件。C 头文件包含在生成的接口代码中的 extern "C" 代码块中，这可以避免在链接 C 源文件或 C 库时为名称添加修饰文本。

如果库是由以下文件定义的，在为库创建接口时，将 CLinkage 设置为 true：

  • C 头文件和库文件。

  • C 头文件和源文件。

如果 CLinkage 为 false，则函数会将 .h 头文件视为 C++ 文件。从具有 C 依赖项的 C++ 文件创建接口时，使用默认值（CLinkage 为 false）。在本例中，C 文件由以下参量之一指定：

有关如何在 clibgen.generateLibraryDefinition 参量中使用 C 文件的示例，请参阅提示中的“库中的文件”并搜索 CLinkage。

数据类型: logical

解析头文件时要使用的宏定义列表，指定为空、标量字符串或由标量字符串组成的行向量。宏名称包含字符 1-9、a-z、A-Z 和 '_'，并且不能以数值开头。

数据类型: string

解析头文件时要使用的宏取消列表，指定为空、标量字符串或由标量字符串组成的行向量。宏名称包含字符 1-9、a-z、A-Z 和 '_'，并且不能以数值开头。

数据类型: string

自 R2022a 起

编译器标志的列表，指定为字符串数组、字符向量或字符向量元胞数组，追加到用于编译接口的编译器标志。该函数将标志直接传递给编译器，而不进行验证。

有关详细信息，请参阅Build C++ Library Interface and Review Contents。

示例: clibgen.generateLibraryDefinition("A.hpp","AdditionalCompilerFlags","-std=c++20")

数据类型: char | string | cell

自 R2022a 起

链接器标志的列表，指定为字符串数组、字符向量或字符向量元胞数组，追加到用于编译接口的链接器标志。函数将标志直接传递给链接器，而不进行验证。

有关详细信息，请参阅Build C++ Library Interface and Review Contents。

数据类型: char | string | cell

定义配置

全部展开

对象指针的形状设定符，指定为数值或逻辑值 1 (true) 或 0 (false)。如果 TreatObjectPointerAsScalar 是 true，则该函数通过将 SHAPE 指定为 1，将库中的所有对象指针视为标量。否则，对象指针的形状是未知的。

在 R2019b 中引入。

数据类型: logical

const 字符指针的形状和 MATLAB 类型设定符，指定为数值或逻辑值 1 (true) 或 0 (false)。如果 TreatConstCharPointerAsCString 是 true，则该函数通过将 MLTYPE 指定为 string 并将 SHAPE 指定为 nullTerminated，将库中的所有 const 字符指针视为以空值结尾的 C 字符串。否则，const 字符指针的 MATLAB 类型和形状未知。支持的指针类型有：

  • const char *

  • const wchar_t *

  • const char16_t *

  • const char32_t *

数据类型: logical

指定如何返回非对象 C++ 数组的选项，指定为数值或逻辑值 1 (true) 或 0 (false)。如果 ReturnCArrays 为 true，则该函数将 C++ 数组转换为 MATLAB clib 数组类型 (clib.array.*)。如果为 false，则该函数将 C++ 数组转换为原生 MATLAB 数组。

数据类型: logical

从 C++ 文件生成文档的选项，指定为数值或逻辑值 1 (true) 或 0 (false)。如果 GenerateDocumentationFromHeaderFiles 是 true，则该函数基于 C++ 文件中的注释生成文档以便使用 MATLAB doc 命令显示。如果为 false，则该函数会忽略 C++ 注释，只生成 MATLAB 和 C++ 类型映射的文档。

有关详细信息，请参阅Publish Help Text for MATLAB Interface to C++ Library。

数据类型: logical

限制

  • 不支持将 LibraryDefinition 对象 definelibName 保存到 MAT 文件中。

  • 避免在文件夹名称和文件名中使用非 ASCII 字符，因为某些区域设置不支持这些字符。有关区域设置的信息，请参阅设置区域设置和显示语言。

提示

  • 要重新创建库定义文件，请调用 clibgen.generateLibraryDefinition，并将名称-值参量 OverwriteExistingDefinitionFiles 设置为 true。使用此选项时，该函数会删除文件，包括您可能对文件所做的编辑。

  • 有关故障排除信息，请参阅Troubleshooting C++ Library Definition Issues。

  • 您的库可能包含 C/C++ 头文件、源文件和编译库文件的组合。下表显示如何根据定义库的文件类型将参量设置为 clibgen.generateLibraryDefinition。

    您库中的文件

    InterfaceGenerationFiles
    参量

    		名称-值参量

    Windows 上的单个 CPP 头文件和导入库文件。

    • A.hpp

    • 文件夹 C:\Documents\MATLAB\ 中的 A.lib 导入库文件

    示例：Windows 上的头文件和 C++ 编译的库文件

    "A.hpp"

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

    Linux 上的 CPP 头文件和编译的目标文件。

    • A.hpp

    • 文件夹 ~/MATLAB/ 中的 A.so

    示例：Linux 上的头文件和 C++ 编译的库文件

    "A.hpp"

    Libraries="~/MATLAB/A.so"

    macOS 上的 CPP 头文件和动态编译库文件。

    • A.hpp

    • 文件夹 $home/Documents/MATLAB 中的 A.dylib

    "A.hpp"

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

    完全由 CPP 头文件和源文件定义。没有库文件。

    • 头文件 A.hpp

    • 源文件 A.cpp

    示例：头文件和 C++ 源文件

    "A.hpp"

    SupportingSourceFiles="A.cpp"

    多个 CPP 头文件、一个源文件和一个编译库文件。创建名为 A 的接口。

    • 头文件 A.hpp 和 B.hpp

    • 源文件 A.cpp

    • C:\Documents\MATLAB\ 中的编译库文件 B.lib

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

    InterfaceName="A"a

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

    SupportingSourceFiles="A.cpp"

    只包含 CPP 头文件的库。该库完全在头文件中定义，没有编译库文件。

    • A.hpp

    示例：只包含头文件的 HPP 文件

    "A.hpp"

    不适用

    完全在 CPP 源文件中定义，并且没有编译库文件。

    • A.cpp

    "A.cpp"

    不适用

    完全由 C 头文件和源文件定义。没有库文件。

    • A.h

    • A.c

    "A.h"

    SupportingSourceFiles="A.c"

    CLinkage=true

    Windows 上的单个 C 头文件和导入库文件。

    • A.h

    • C:\Documents\MATLAB\ 中的 A.lib

    "A.h"

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

    CLinkage=true

    CPP 源文件依赖 C 头文件和源文件。

    • 源文件 myCPP.cpp

    • C:\Documents\MATLAB\ 中的头文件和源文件 A.h 和 A.c

    		"myCPP.cpp"

    SupportingSourceFiles="C:\Documents\MATLAB\A.c"

    C 库依赖 CPP 源文件。

    • C:\Documents\MATLAB\ 中的头文件和源文件 A.h 和 A.c

    • 源文件 myCPP.cpp

    ["C:\Documents\MATLAB\A.h", "myCPP.cpp"]

    		InterfaceName="myCPP"

    SupportingSourceFiles="C:\Documents\MATLAB\A.c"

    CLinkage=true

    由 CPP 和 C 头文件定义的库，对应的库文件位于 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

    C 头文件依赖 CPP 头文件。

    • A.h

    • C:\Documents\MATLAB\ 中的 B.hpp

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

替代功能

实时任务

调用 clibPublishInterfaceWorkflow 函数以使用生成 C++ 接口实时任务。

版本历史记录

在 R2019a 中推出

全部展开

另请参阅

| | | |

主题