Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

clibgen.generateLibraryDefinition

为 C++ 库创建定义文件

说明

clibgen.generateLibraryDefinition 函数创建一个 MATLAB® 实时代码定义文件,用于生成 C++ 库的 MATLAB 接口。使用此函数可以:

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

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

  • (可选)指定用于定义参数的配置。

  • (可选)指定编译器编译配置参数。

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

您需要 MATLAB 支持的 C++ 编译器。您必须使用与编译该 C++ 库时所用的相同编译器来编译接口库。如果您的库完全由源文件定义(不使用共享库文件),则您可以选择任何受支持的 C++ 编译器来编译接口库。

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

示例

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

定义文件的名称是 definelibName.mlx。默认情况下,libNameInterfaceGenerationFiles 中指定的第一个文件的文件名。例如,如果您指定名为 mylibrary.hpp 的头文件,则函数会创建一个名为 definemylibrary.mlx 的定义文件。如果指定多个接口生成文件,则必须使用 PackageName 名称-值参数来指定 libName

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

示例

clibgen.generateLibraryDefinition(InterfaceGenerationFiles) 创建一个完全由 InterfaceGenerationFiles 定义的库。如果您的库包含共享库文件,则必须指定 Libraries 参数。

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

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

  • 使用 C++ 库设置来管理宏定义。

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

  • 使用编译配置指定编译器编译和链接选项。

示例

全部折叠

此示例的文件位于 MATLAB examples 文件夹中。从 Windows® 上的 matrixOperations.hpp 头文件生成库定义文件 definematrixOperations.mlx。有关 Linux® 示例,请参阅Linux 上的头文件和共享目标文件

使用头文件的完整路径创建一个 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.mlx 库定义文件。

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

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

使用头文件 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");

通过将 PackageName 参数设置为 "matrixOps",创建 definematrixOps.mlx 库定义文件。

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

school.hpp 头文件生成库定义文件 defineschool.mlx

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

输入参数

全部折叠

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

用于指定 InterfaceGenerationFilesSupportingSourceFiles 参数的文件有:

  • 头文件,文件扩展名为 .h.hpp.hxx。也支持不带扩展名的头文件。.h 头文件中的代码必须为与 C++ 兼容的 C 代码。

    如果指定多个接口生成文件,则必须使用 PackageName 参数。

  • 源代码文件,文件扩展名为 .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", ...
PackageName="mylib", ...
OutputFolder="C:\work", ...
DefinedMacros=["mymacro1","mymacro2=0"], ...
UndefinedMacros="mymacro3", ...
OverwriteExistingDefinitionFiles=true);

文件选择

全部折叠

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

库是以下各项之一:

  • 在 Windows 平台上:

    • 对于共享库,指定 .lib 导入库文件。

      如果 .lib 文件不可用,并且库是使用受支持的 Microsoft® Visual Studio® 编译器编译的,则可以指定 .dll 动态链接库文件。例如:

      clibgen.generateLibraryDefinition("A.hpp",Libraries="A.dll")
    • 对于静态库,指定 .lib 文件。例如:

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

      如果库是用支持的 MinGW-w64 编译器编译的,则您可以指定 .a 静态库文件。例如:

      clibgen.generateLibraryDefinition("A.hpp",Libraries="A.a")
  • 在 Linux 平台上,指定一个 .so 共享目标文件或一个 .a 静态库文件。

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

例如,以下语句使用当前文件夹中的 sample.hppC:\myLib 文件夹中的 myLib.lib 创建 definesample.mlx,并将该 MLX 文件写入当前文件夹中。

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

配置

全部折叠

生成的接口包名称,指定为字符串标量或字符向量。有关详细信息,请参阅Call Functions in C++ Compiled Library

对于从单个头文件创建的接口,默认值为头文件的名称。对于使用多个头文件的情况,您必须将包名称指定为一个有效的 MATLAB 名称。例如,以下语句在当前文件夹中创建 definemylib.mlx

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

数据类型: char | string | cell

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

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

数据类型: char | string | cell

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

小心

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

数据类型: logical

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

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

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

数据类型: logical

C++ 库设置

全部折叠

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

数据类型: string

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

数据类型: string

定义配置

全部折叠

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

在 R2019b 中引入。

数据类型: logical

const 字符指针的形状和 MATLAB 类型设定符,指定为数值或逻辑值 1 (true) 或 0 (false)。如果 TreatConstCharPointerAsCStringtrue,则该函数通过将 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)。如果 ReturnCArraystrue,则对于非对象 C 数组,该函数返回 C 数组 (clib.array.*)。如果为 false,则对于非对象 C 数组,该函数返回 MATLAB 数值数组。

数据类型: logical

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

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

数据类型: logical

编译配置

全部折叠

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

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

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

  • C 头文件和库文件。

  • C 头文件和源文件。

  • CPP 文件和 C 文件的组合。

如果 CLinkagefalse,则函数会将 .h 头文件视为 CPP 文件。从具有 C 依赖项的 CPP 文件创建接口时,使用默认值(CLinkagefalse)。在本例中,C 文件由以下参数之一指定:

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

数据类型: logical

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

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

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

数据类型: char | string | cell

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

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

数据类型: char | string | cell

局限性

  • 不支持将 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 上的头文件和导入库文件

    "A.hpp"

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

    Linux 上的 CPP 头文件和共享目标文件。

    • A.hpp

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

    示例:Linux 上的头文件和共享目标文件

    "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

    示例:头文件和 CPP 源文件

    "A.hpp"

    SupportingSourceFiles="A.cpp"

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

    • 头文件 A.hppB.hpp

    • 源文件 A.cpp

    • C:\Documents\MATLAB\ 中的共享库文件 B.lib

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

    PackageName="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.hA.c

    "myCPP.cpp"

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

    C 库依赖 CPP 源文件。

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

    • 源文件 myCPP.cpp

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

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

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

版本历史记录

在 R2019a 中推出

全部展开