Main Content

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

clibgen.buildInterface

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

说明

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

注意

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

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

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

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

示例

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

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

clibgen.buildInterface(HeaderFiles,___,Name,Value) 使用一个或多个名称-值对组参数生成接口。可以将此选项与前面语法中的任何输入参数组合一起使用。

示例

全部折叠

school.hpp 头文件复制到可写文件夹 H:\Documents\MATLAB\publisher 中。

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 construct(s) need(s) further definition to be included in the interface. 
Use clibgen.generateLibraryDefinition to provide definitions.

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

显示库的帮助。

help clib.school
Classes contained in clib.school:
Person                         - clib.school.Person    Representation of C++ class Person
Teacher                        - clib.school.Teacher    Representation of C++ class Teacher
Student                        - clib.school.Student    Representation of C++ class Student

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

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

输入参数

全部折叠

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

有关详细信息,请参阅 clibgen.generateLibraryDefinition 函数中的 InterfaceGenerationFiles 参数。

示例: "sample.hpp"

数据类型: char | string | cell

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

有关详细信息,请参阅 clibgen.generateLibraryDefinition 函数中的 LibraryFiles 参数。

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

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

数据类型: char | string | cell

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

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

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

示例: "sample.cpp"

数据类型: char | string | cell

名称-值参数

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

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

用于所包含的头文件的一个或多个文件夹,指定为字符串数组、字符向量或字符向量元胞数组。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

用于显示生成消息的选项,指定为 truefalse。当指定为 true 时,clibgen.buildInterface 会在编译接口时在命令行窗口中显示生成消息。例如,以下语句在 h1 子文件夹中创建一个 h1Interface 库文件,并在命令行窗口中显示消息。

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

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

数据类型: logical

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

在 R2019b 中引入。

数据类型: 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。如果 ReturnCArraystrue,则对于非对象 C 数组,MATLAB 返回 C 数组 (clib.array.*)。如果为 false,则对于非对象 C 数组,MATLAB 返回 MATLAB 数值数组。

数据类型: logical

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

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

数据类型: logical

局限性

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

替代功能

两步编译过程

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

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

版本历史记录

在 R2019a 中推出