Main Content

本页的翻译已过时。点击此处可查看最新英文版本。

clibgen.generateLibraryDefinition

为 C++ 库创建定义文件

说明

示例

clibgen.generateLibraryDefinition(InterfaceGenerationFiles,'Libraries',LibraryFiles) 创建一个 MATLAB® 实时代码定义文件,用于生成与 InterfaceGenerationFilesLibraryFiles 定义的 C++ 库的 MATLAB 接口。有关调用 clibgen.generateLibraryDefinition 的示例,请参阅提示中的“您的库中有哪些文件?”。

定义文件的名称是 definelibName.mlx。有关使用此文件的详细信息,请参阅 Define MATLAB Interface for C++ Library。默认情况下,libNameInterfaceGenerationFiles 中指定的第一个文件的文件名。如果指定多个接口生成文件,则必须使用 PackageName 名称-值对组参数。

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

示例

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

示例

clibgen.generateLibraryDefinition(InterfaceGenerationFiles) 创建一个完全由 InterfaceGenerationFiles 定义的库的定义文件。

如果您的库包含共享库文件,则必须指定 'Libraries' 参数。

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

示例

全部折叠

从 Windows® 上的 matrixOperations.hpp 头文件生成库定义文件 definematrixOperations.mlx。有关 Linux® 示例,请参阅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).

matrixOperations.hppmatrixOperations.cpp 文件生成库定义文件 definematrixOps.mlx

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

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

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

输入参数

全部折叠

用于生成接口的一个或多个 C++ 文件,指定为字符串数组、字符向量或字符向量元胞数组。如果不在当前文件夹或您的 MATLAB 路径中,则该名称包括文件的完整或相对路径。

用于指定 InterfaceGenerationFilesSupportingSourceFiles 的文件有:

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

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

  • 源代码文件,文件扩展名为 .cpp.cxx

  • 有关详细信息,请参阅提示中的“您的库中有哪些文件?”。

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

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

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

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

clibgen.generateLibraryDefinition("myHeader.hpp")

示例: "sample.hpp"

数据类型: char | string | cell

一个或多个共享库文件名,指定为字符串、字符串数组、字符向量或字符向量元胞数组。与 'Libraries' 名称-值对组参数结合使用。除非库完全由 InterfaceGenerationFiles 参数和名称-值对组参数 'SupportingSourceFiles' 指定的文件定义,否则此值是必需的。

库是以下各项之一:

  • 在 Windows 平台上:

    • 对于静态库,指定 .lib 文件。例如:

      clibgen.generateLibraryDefinition("A.hpp","Libraries","A.lib")
    • 对于共享库,指定 .lib 导入库文件。

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

      clibgen.generateLibraryDefinition("A.hpp","Libraries","A.dll")
  • 在 Linux 平台上,指定 .so 共享目标文件。

  • macOS 平台上,指定 .dylib 动态共享库文件。

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

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

数据类型: char | string | cell

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

有关详细信息,请参阅提示中的“您的库中有哪些文件?”。

如果库完全由头文件和 .cpp 源文件定义,则不要求共享库文件。

示例: "sample.cpp"

数据类型: char | string | cell

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN 所示。

示例: clibgen.generateLibraryDefinition(["hfile1.hpp","hfile2.hpp"],"Libraries","hfile1.lib",...
"IncludePath","C:\mylib\include","PackageName","mylib","OutputFolder","C:\work",...
"DefinedMacros",["mymacro1","mymacro2=0"],"UndefinedMacros","mymacro3");

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

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

数据类型: char | string | cell

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

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

数据类型: char | string | cell

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

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

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

数据类型: char | string | cell

用于显示生成消息的选项,指定为 truefalse。如果 Verbosetrue,则 MATLAB 在创建定义文件时会在命令行窗口中显示生成消息。以下语句创建 defineh1.mlx 并在命令行窗口中显示消息。

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

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

数据类型: logical

对象指针的形状设定符,指定为 truefalse。如果 TreatObjectPointerAsScalartrue,则 MATLAB 通过将 SHAPE 指定为 1,将库中的所有对象指针视为标量。否则,对象指针的形状是未知的。

数据类型: logical

const 字符指针的形状和 MATLAB 类型设定符,指定为 truefalse。如果 TreatConstCharPointerAsCStringtrue,则 MATLAB 通过将 MLTYPE 指定为 string 并将 SHAPE 指定为 nullTerminated,将库中的所有 const 字符指针视为以空值结尾的 C 字符串。否则,const 字符指针的 MATLAB 类型和形状未知。支持的指针类型有:

  • const char *

  • const wchar_t *

  • const char16_t *

  • const char32_t *

数据类型: logical

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

数据类型: string

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

数据类型: string

是否从 C++ 文件生成文档,指定为 truefalse。如果 GenerateDocumentationFromHeaderFilestrue,则 MATLAB 基于 C++ 源文件中的注释生成文档以便使用 MATLAB doc 命令显示。如果为 false,则 MATLAB 会忽略 C++ 注释,只生成 MATLAB 和 C++ 类型映射的文档。

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

数据类型: logical

是否返回非对象 C 数组,指定为 truefalse。如果 ReturnCArraystrue,则对于非对象 C 数组,MATLAB 返回 C 数组 (clib.array.*)。如果为 false,则对于非对象 C 数组,MATLAB 返回 MATLAB 数值数组。

数据类型: logical

局限性

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

  • 避免在文件夹名称和文件名中使用非 ASCII 字符,因为某些区域设置可能不支持这些字符。有关区域设置的信息,请参阅国际化的区域设置概念

提示

  • 要重新创建库定义文件,请先删除 definelibName.mlx 文件,然后调用 clibgen.generateLibraryDefinition

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

  • 您的库可能包含头文件、CPP 源文件和共享库文件的组合。下表显示如何根据定义库的文件类型将参数设置为 clibgen.generateLibraryDefinition

    您的库中有哪些文件?

    Argument
    InterfaceGenerationFiles
    名称-值对组参数
    "Libraries"
    名称-值对组参数
    "SupportingSourceFiles"

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

    • A.hpp

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

    "A.hpp"

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

     

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

    • A.hpp

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

    "A.hpp"

    "~/MATLAB/A.so"

     

    macOS 上的头文件和动态共享库文件。

    • A.hpp

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

    "A.hpp"

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

     

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

    • 头文件 A.hpp

    • 源文件 A.cpp

    "A.hpp"

     

    "A.cpp"

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

    • 头文件 A.hppB.hpp

    • 源文件 A.cpp

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

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

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

    "A.cpp"

    只包含头文件的库。该库完全在头文件中定义,没有共享库文件。

    • A.hpp

    "A.hpp"

      

    该库完全在 .CPP 文件中定义,没有共享库文件。

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

在 R2019a 中推出