头文件和 C++ 源文件
此示例说明如何通过调用 clibPublishInterfaceWorkflow
为在头文件 matrixOperations.hpp
中声明并在 C++ 源文件 matrixOperations.cpp
中定义的 C++ 库创建一个 MATLAB® 接口。
MATLAB 在此文件夹中提供源文件:
fullfile(matlabroot,"extern","examples","cpp_interface")
对于此示例,文件夹是:
ans = "C:\Program Files\MATLAB\R2023a\extern\examples\cpp_interface"
创建工作流脚本
导航到一个可写文件夹(例如 C:\work\publish
),并调用 clibPublishInterfaceWorkflow
。在对话框中,指定工作流脚本的名称,例如 publishmatrixlib.mlx
。该工作流脚本包含帮助您发布接口的步骤。使用该脚本保存用于发布接口的参数。您可以在所有平台上使用相同的脚本。
注意
工作流脚本允许您在多个 MATLAB 会话期间重复生成、定义、编译和测试接口。但是,该脚本不会保存对使用覆盖现有定义文件选项重新创建的库定义文件的编辑。
Step 1: GENERATE
首先,生成库定义文件。工作流脚本包含用于此步骤的生成 C++ 接口实时编辑器任务。使用此任务可以选择组成库的文件,并设置用于生成库定义文件的选项。
选择文件
该库由 matrixOperations.hpp
头文件和 Windows® matrixOperations.cpp
源文件定义。选择 Headers and source files
作为库类型。
要设置库起始路径,请浏览至文件夹 fullfile(matlabroot,"extern","examples","cpp_interface")
,然后点击选择文件夹。
要选择头文件,请使用浏览按钮打开 matrixOperations.hpp
文件。
头文件取决于 cppshrhelp.hpp
头文件。导航到库起始路径中的文件夹,然后点击选择文件夹。
要选择支持源文件,请使用浏览按钮打开 matrixOperations.cpp
文件。
选择配置
在此示例中,C++ 编译器设置为 MinGW64 Compiler (C++)
。
默认接口库的名称是 matrixOperations
。此名称与 clib
结合使用以调用 MATLAB 中的功能。例如,要创建库对象 Mat
,请在命令提示符下键入:
clib.matrixOperations.Mat
确认输出文件夹是可写文件夹。
选中覆盖现有定义文件复选框,以便您可以在开发接口时重新创建定义文件。
指定可选的 C++ 库设置
选择将 .h 文件视为 C 头文件参数。
指定可选的定义配置
编译此库的接口不需要可选的定义配置。
显示结果
默认情况下,当您生成定义文件时,函数会显示可用的构造(库中的类和函数)。在开发接口时,还要选中显示不可用的构造复选框,以便您可以查看哪些构造可能需要更多信息才能包括在内。
生成定义文件
点击生成定义文件。脚本会显示其进度,并在指定的输出文件夹中创建库定义文件 definematrixOperations.m
。
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 Interface to matrixOperations Library Class clib.matrixOperations.Mat Constructors: clib.matrixOperations.Mat(clib.matrixOperations.Mat) clib.matrixOperations.Mat() Methods: uint64 getLength() No Properties defined Functions clib.matrixOperations.updateMatByX(clib.matrixOperations.Mat,int32)
在多个会话中启用开发工具
发布接口时,您可能会迭代这些步骤,关闭并重新打开 publishmatrixlib.mlx
脚本,或重新启动 MATLAB。按照以下各节中的说明来帮助您处理这些工作流。
在各 MATLAB 会话之间保留工作区变量。在 Restore library definition 节中,将
outputFolderPath
变量设置为输出文件夹参数中的值。将libraryNameForInterface
变量设置为接口库的名称参数matrixlib
。然后运行该节。有关详细信息,请参阅Restore Library Definition。考虑运行 Enable out-of-process execution mode 节。在开发接口时使用此模式就无需在测试时重启 MATLAB。调用库中的功能后,您可以通过运行 Unload out-of-process library 节来卸载库。有关详细信息,请参阅 Load Out-of-Process C++ Library
Step 2: DEFINE
当您创建库定义文件时,MATLAB 报告有五个构造未完全定义。要完全定义所需功能,请编辑 definematrixlib.m
文件。要编辑该文件,请运行 DEFINE 节。
定义缺失构造
在库定义文件中滚动,找到这些构造的注释代码块。MATLAB 无法自动确定这些函数使用的参数的大小。
setMat
- 类Mat
的 C++ 方法getMat
- 类Mat
的 C++ 方法copyMat
- 类Mat
的 C++ 方法addMat
- C++ 包函数updateMatBySize
- C++ 包函数
根据 matrixOperations
库的文档,您可以在参数定义语句中为 <SHAPE>
提供值。有关详细信息,请参阅 Define Missing SHAPE Parameter。
对于每个构造,取消注释定义该构造的语句。
用下列值替换
<SHAPE>
参数。构造
参数名称
参数 C++ 定义
描述
用下列值替换
<SHAPE>
setMat
src
int [] src
矩阵的长度由输入参数
len
定义。"len"
getMat
RetVal
int const *
输出参数的长度由输入参数
len
定义。"len"
copyMat
dest
int * dest
长度
dest
由输入参数len
定义。"len"
addMat
mat
Mat const * mat
该函数接受单个
mat
参数。1
updateMatBySize
arr
int * arr
长度
arr
由输入参数len
定义。"len"
保存并关闭定义文件。
要验证您在文件中所做的编辑,请运行 Confirm edits and run summary 节。在文件中修复报告的任何错误。
summary
函数显示接口现在包括setMat
、getMat
、copyMat
、addMat
和updateMatBySize
。
MATLAB Interface to matrixOperations Library Class clib.matrixOperations.Mat Constructors: clib.matrixOperations.Mat(clib.matrixOperations.Mat) clib.matrixOperations.Mat() Methods: setMat(clib.array.matrixOperations.Int) clib.array.matrixOperations.Int getMat(uint64) uint64 getLength() copyMat(clib.array.matrixOperations.Int) No Properties defined Functions int32 clib.matrixOperations.addMat(clib.matrixOperations.Mat) clib.matrixOperations.updateMatByX(clib.matrixOperations.Mat,int32) clib.matrixOperations.updateMatBySize(clib.matrixOperations.Mat,clib.array.matrixOperations.Int)
Step 3: BUILD
要编译库的 matrixOperations
接口,请运行脚本的 BUILD 节。
注意
您可以重复生成、定义和编译步骤。但是,一旦显示帮助或调用库中的函数,就无法在同一 MATLAB 会话中更新 definematrixlib
定义文件。请重新启动 MATLAB,或通过更改选择配置部分中的接口库的名称参数来创建新定义文件。
Step 4: TEST
Set up and copy run-time libraries
运行 Set up and copy run-time libraries 节。此库没有其他运行时依存关系,因此您不需要修改命令。
Enable out-of-process execution mode
如果定义文件需要更改,请运行此命令来设置在进程外调用接口库的能力,这样就不必重新启动 MATLAB。有关详细信息,请参阅Load C++ Library In-Process or Out-of-Process。
Call help on interface library
要显示接口库的帮助,请运行 Call help on interface library 节。
Write code to call and test interface library
使用 Write code to call and test interface library 中的代码节来编写这些测试:
matObj = clib.matrixlib.Mat; % Create a Mat object intArr = [1,2,3,4,5]; matObj.setMat(intArr); % Set the values to intArr retMat = matObj.getMat(5) % Display the values
retMat = read-only clib.array.matrixlib.Int with properties: Dimensions: 5 Resizable: 0
共享接口
要与其他 MATLAB 用户共享该接口,请创建一个工具箱安装 (.mltbx
) 文件。使用Distribute MATLAB Interface to C++ Library中的说明:
将工具箱文件夹设置为您的
matrixOperations
文件夹,其中包含接口文件matrixOperationsInterface.dll
。将编译后的库文件
matrixOperations.dll
放在同一文件夹中。将命名空间(调用语法)标识为
clib.matrixOperations
。