Main Content

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

clibgen.buildInterface

在没有定义文件的情况下创建 C++ 库的接口

说明

clibgen.buildInterface(InterfaceGenerationFiles,Libraries=LibraryFiles) 创建用于 HeaderFilesLibraries 定义的 C++ 库的 MATLAB® 接口。

注意

库中任何 MATLAB 无法自动定义的类构造函数、方法、数据成员和函数都会被丢弃。要包含缺失的功能,请使用两步编译工作流,即分别使用 clibgen.generateLibraryDefinitionbuild 函数。

接口文件的名称是 libNameInterface,具有特定于平台的文件扩展名。默认情况下,libNameHeaderFiles 中指定的文件名。

您需要 MATLAB 支持的 C++ 编译器。您必须使用与编译该 C++ 库时所用的相同编译器来编译接口。

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

示例

clibgen.buildInterface(InterfaceGenerationFiles) 创建一个该库的接口,该接口完全由 HeaderFiles 定义。您可以使用任何 MATLAB 支持的 C++ 编译器来编译该接口。

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

clibgen.buildInterface(___,Name=Value) 使用一个或多个名称-值参数生成接口。可将此选项与上述语法中的任何输入参数组合一起使用。有关使用这些参数的详细信息,请参阅 clibgen.generateLibraryDefinition

示例

全部折叠

school.hpp 头文件复制到可写文件夹中。

copyfile(fullfile(matlabroot,'extern','examples','cpp_interface','school.hpp'),'.','f')

编译接口 schoolInterface.dll。输出中的路径名称反映您选择的文件夹。

clibgen.buildInterface("school.hpp")
Building interface file 'schoolInterface.dll' for clib package 'school'.
Interface file 'schoolInterface.dll' built in folder 'C:\Users\MATLAB\school'.

To use the library, add the interface file folder to the MATLAB path.
addpath('C:\Users\MATLAB\school')
1 constructs need further definition to be included in the interface. 
Use clibgen.generateLibraryDefinition to provide definitions.

点击 addpath 链接以将该接口添加到路径中。

加载库并显示 Person 类的帮助。

help clib.school.Person
Person -  clib.school.Person    Representation of C++ class Person.

显示库的帮助。

help clib.school

将此功能与只包含头文件的 HPP 文件summary(defineschool) 命令的输出进行比较。该接口不包括:

Functions
  string clib.school.getName(clib.school.Person)

输入参数

全部折叠

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

示例: "sample.hpp"

数据类型: char | string | cell

共享库文件名,指定为字符串数组、字符向量或字符向量元胞数组。与 Libraries 参数结合使用。除非库完全由 InterfaceGenerationFilesSupportingSourceFiles 参数指定的文件定义,否则此值是必需的。有关详细信息,请参阅 clibgen.generateLibraryDefinition 函数中的 Libraries 参数。

例如,在 Windows® 上运行此语句会使用 C:\myLib\ 中的 myLib.lib 创建 sampleInterface.dll,并将其写入当前文件夹中的子文件夹 sample 中。

clibgen.buildInterface("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

名称-值参数

将可选的参数对组指定为 Name1=Value1,...,NameN=ValueN,其中 Name 是参数名称,Value 是对应的值。名称-值参数必须出现在其他参数之后,但参数对组的顺序无关紧要。

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

示例: clibgen.buildInterface("myHeader.hpp",Libraries="myHeader.lib",OutputFolder="C:\work");

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

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

数据类型: char | string | cell

生成的定义文件的文件夹名称,指定为字符串标量或字符向量。例如,此语句在 Windows 上的 C:\work\myHeader 中创建 myHeaderInterface.dll

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

数据类型: char | string | cell

生成的接口包名称,指定为字符串标量或字符向量。对于从单个头文件创建的接口,默认值为头文件的名称。对于使用多个头文件的情况,您必须将包名称指定为一个有效的 MATLAB 名称。例如,以下语句在当前文件夹的 mylib 子文件夹中创建一个 mylibInterface 库文件。

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

数据类型: char | string | cell

显示生成消息的选项,指定为数值或逻辑值 1 (true) 或 0 (false)。当指定为 true 时,clibgen.buildInterface 会在编译接口时在命令行窗口中显示生成消息。例如,以下语句在 h1 子文件夹中创建一个 h1Interface 库文件,并在命令行窗口中显示消息。

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

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

数据类型: logical

对象指针的形状设定符,指定为数值或逻辑值 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

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

数据类型: string

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

数据类型: string

指定如何返回非对象 C++ 数组的选项,指定为数值或逻辑值 1 (true) 或 0 (false)。如果 ReturnCArraystrue,则该函数将 C++ 数组转换为 MATLAB clib 数组类型 (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 头文件和源文件。

如果 CLinkagefalse,则函数会将 .h 头文件视为 C++ 文件。从具有 C 依赖项的 C++ 文件创建接口时,使用默认值(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

局限性

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

替代功能

两步编译过程

使用 clibgen.generateLibraryDefinitionbuild 函数而不是 clibgen.buildInterface 来定义接口中缺失的功能。

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

版本历史记录

在 R2019a 中推出