FindMatlab¶

查找 Matlab 或 Matlab Compiler Runtime (MCR) 并向 CMake 提供 Matlab 工具、库和编译器。

此软件包的主要目的是查找与 Matlab 或 MCR 关联的库，以便能够构建 Matlab 扩展（mex 文件）。它还可以用于

在 Matlab 可用时在 Matlab 中运行特定命令
用于声明 Matlab 单元测试
从 Matlab 检索各种信息（mex 扩展、版本和发行版查询等）

3.12 版本新增：添加了 Matlab Compiler Runtime (MCR) 支持。

该模块支持以下组件

ENG_LIBRARY 和 MAT_LIBRARY：分别是 Matlab 的 ENG 和 MAT 库
MAIN_PROGRAM Matlab 二进制程序。请注意，此组件在 MCR 版本中不可用，如果找到 MCR 而不是常规 Matlab 安装，则会产生错误。
MEX_COMPILER MEX 编译器。
MCC_COMPILER MCC 编译器，随 Matlab Compiler 附加组件提供。
SIMULINK Simulink 环境。

3.7 版本新增：添加了 MAT_LIBRARY 组件。

3.13 版本新增：添加了 ENGINE_LIBRARY、DATAARRAY_LIBRARY 和 MCC_COMPILER 组件。

3.14 版本更改：移除了 MX_LIBRARY、ENGINE_LIBRARY 和 DATAARRAY_LIBRARY 组件。这些库是无条件找到的。

3.30 版本新增：增加了对 find_package() 指定版本范围的支持，并增加了对 find_package()、matlab_extract_all_installed_versions_from_registry() 和 matlab_get_all_valid_matlab_roots_from_registry() 指定 REGISTRY_VIEW 的支持。默认行为不变，使用注册表视图 TARGET。

注意

给 find_package() 指令的版本是 Matlab **版本**，不应与 Matlab *发行版* 名称（例如 R2023b）混淆。matlab_get_version_from_release_name() 和 matlab_get_release_name_from_version() 提供了发行版名称与版本之间的映射。

可以指定变量 Matlab_ROOT_DIR 以提供所需 Matlab 版本的路径。否则，行为取决于平台

Windows：已安装的 Matlab/MCR 版本从 Windows 注册表中检索。REGISTRY_VIEW 参数可选择指定以手动控制是否应搜索 32 位或 64 位版本。
macOS：已安装的 Matlab/MCR 版本由 $HOME/Applications 和 /Applications 下的 MATLAB 默认安装路径给出。如果未找到此类应用程序，则回退到可能从 PATH 访问的应用程序。
Unix：所需的 Matlab 应该可以通过 PATH 访问。这不适用于 MCR 安装，并且在此平台上应指定 Matlab_ROOT_DIR。

当设置 MATLAB_FIND_DEBUG 时，会提供额外信息。当自动找到 Matlab/MCR 安装且未给出 MATLAB_VERSION 时，版本直接从 Matlab（在 Windows 上这可能会弹出 Matlab 窗口）或从 MCR 安装查询。

Matlab 发行版名称和版本之间的映射通过定义对（名称、版本）来执行。在调用 find_package() 之前，可以提供变量 MATLAB_ADDITIONAL_VERSIONS 以处理其他版本。

可以使用 matlab_add_unit_test() 将 Matlab 脚本添加到测试集中。默认情况下，Matlab 单元测试框架（>= 2013a）将用于运行此脚本，但也可以使用返回退出代码的常规 .m 文件（0 表示成功）。

模块输入变量¶

用户或项目可以设置以下变量来配置模块行为

Matlab_ROOT: 在 3.25 版本中新增。

Matlab_ROOT_DIR 的默认值，Matlab 安装的根目录。
Matlab_ROOT_DIR: Matlab 安装的根目录。
MATLAB_FIND_DEBUG: 输出调试信息
MATLAB_ADDITIONAL_VERSIONS: 用于自动检索已安装版本的 Matlab 的其他版本。

导入的目标¶

3.22 版本新增。

此模块定义以下 IMPORTED 目标

Matlab::mex: mex 库，始终可用于 MATLAB 安装。如果 MCR 提供，则可用于 MCR 安装。
Matlab::mx: Matlab 的 mx 库（数组），始终可用于 MATLAB 安装。如果 MCR 提供，则可用于 MCR 安装。
Matlab::eng: Matlab 引擎库。仅当请求 ENG_LIBRARY 组件时可用。
Matlab::mat: Matlab 矩阵库。仅当请求 MAT_LIBRARY 组件时可用。
Matlab::MatlabEngine: Matlab C++ 引擎库，始终可用于 MATLAB R2018a 及更高版本。如果 MCR 提供，则可用于 MCR 安装。
Matlab::MatlabDataArray: Matlab C++ 数据数组库，始终可用于 MATLAB R2018a 及更高版本。如果 MCR 提供，则可用于 MCR 安装。

模块定义的变量¶

结果变量¶

Matlab_FOUND: 如果找到 Matlab 安装，则为 TRUE，否则为 FALSE。如果找到 Matlab，则定义所有以下变量。
Matlab_VERSION: 在 3.27 版本中新增。

找到的 Matlab 的数字版本（例如 23.2.0）。不要与 Matlab 发行版名称（例如 R2023b）混淆，发行版名称可以使用 matlab_get_release_name_from_version() 获取。
Matlab_ROOT_DIR: FindMatlab 模块确定的 Matlab 安装的最终根目录。
Matlab_MAIN_PROGRAM: Matlab 二进制程序。仅当在 find_package() 指令中给出组件 MAIN_PROGRAM 时可用。
Matlab_INCLUDE_DIRS: Matlab 库头文件的路径
Matlab_MEX_LIBRARY: mex 库，始终可用于 MATLAB 安装。如果 MCR 提供，则可用于 MCR 安装。
Matlab_MX_LIBRARY: Matlab 的 mx 库（数组），始终可用于 MATLAB 安装。如果 MCR 提供，则可用于 MCR 安装。
Matlab_ENG_LIBRARY: Matlab 引擎库。仅当请求组件 ENG_LIBRARY 时可用。
Matlab_MAT_LIBRARY: Matlab 矩阵库。仅当请求组件 MAT_LIBRARY 时可用。
Matlab_ENGINE_LIBRARY: 3.13 版本新增。

Matlab C++ 引擎库，始终可用于 MATLAB R2018a 及更高版本。如果 MCR 提供，则可用于 MCR 安装。
Matlab_DATAARRAY_LIBRARY: 3.13 版本新增。

Matlab C++ 数据数组库，始终可用于 MATLAB R2018a 及更高版本。如果 MCR 提供，则可用于 MCR 安装。
Matlab_LIBRARIES: Matlab 的所有库
Matlab_MEX_COMPILER: Matlab 的 mex 编译器。目前未使用。仅当请求组件 MEX_COMPILER 时可用。
Matlab_MCC_COMPILER: 3.13 版本新增。

Matlab 的 mcc 编译器。随 Matlab Compiler 附加组件提供。仅当请求组件 MCC_COMPILER 时可用。

缓存变量¶

Matlab_MEX_EXTENSION: 当前平台（由 Matlab 给出）的 mex 文件的扩展名。
Matlab_ROOT_DIR: 找到的 Matlab 安装根目录的位置。如果用户更改此值，则会重新计算结果变量。

提供的命令¶

matlab_get_version_from_release_name(): 从 Matlab 发行版名称返回版本
matlab_get_release_name_from_version(): 从 Matlab 版本返回发行版名称
matlab_add_mex(): 添加一个编译 MEX 文件的目标。
matlab_add_unit_test(): 将 Matlab 单元测试文件作为测试添加到项目中。
matlab_extract_all_installed_versions_from_registry(): 解析注册表以获取所有 Matlab 版本。仅在 Windows 上可用。解析的注册表部分取决于主机处理器
matlab_get_all_valid_matlab_roots_from_registry(): 根据之前给出的列表返回所有可能的 Matlab 或 MCR 路径。只保留存在/可访问的路径。这主要用于搜索所有可能的 Matlab 安装。
matlab_get_mex_suffix(): 返回用于 mex 文件的后缀（取决于平台/架构）
matlab_get_version_from_matlab_run(): 返回 Matlab/MCR 的版本，给定 Matlab/MCR 安装路径的完整目录。

已知问题¶

MEX 目标中的符号冲突

默认情况下，使用命令 matlab_add_mex() 定义的 MEX 文件中的每个符号都具有隐藏可见性，入口点除外。这是 MEX 编译器的默认行为，它降低了 Matlab 附带的库与 MEX 文件链接的库之间符号冲突的风险。这在 Windows 平台上也是默认行为。

然而，在某些情况下这还不够，例如，当您的 MEX 文件链接到 Matlab 已加载的库时，即使这些库具有不同的 SONAMES。一种可能的解决方案是隐藏 MEX 目标链接到的库的符号。这可以通过 GNU GCC 编译器中的链接器选项 -Wl,--exclude-libs,ALL 实现。

使用 GPU 资源的测试

如果您的 MEX 文件使用 GPU，并且为了能够在此 MEX 文件上运行单元测试，Matlab 应正确释放 GPU 资源。一种可能的解决方案是让 Matlab 了解会话中 GPU 资源的使用情况，这可以通过在测试脚本开头（或通过夹具）执行 D = gpuDevice() 等命令来完成。

参考¶

Matlab_ROOT_DIR¶: Matlab 安装的根文件夹。如果在调用 find_package() 之前设置，模块将在该路径中查找组件。如果未设置，则将执行 Matlab 的自动搜索。如果设置，它应指向有效的 Matlab 版本。

MATLAB_FIND_DEBUG¶: 如果设置，Matlab 的查找和中间配置步骤将输出到控制台。

MATLAB_ADDITIONAL_VERSIONS¶

如果设置，则指定可能要查找的其他 Matlab 版本。该变量应为字符串列表，按发行版名称和版本对组织，如下所示

set(MATLAB_ADDITIONAL_VERSIONS
    "release_name1=corresponding_version1"
    "release_name2=corresponding_version2"
    ...
    )

示例

set(MATLAB_ADDITIONAL_VERSIONS
    "R2013b=8.2"
    "R2013a=8.1"
    "R2012b=8.0")

当安装了多个 Matlab 版本时，此列表中的条目顺序很重要。优先级根据此列表中的顺序设置。

matlab_get_version_from_release_name¶

matlab_get_version_from_release_name(release version)

输入：release 是发行版名称（例如 R2023b）
输出：version 是 Matlab 版本（例如 23.2.0）

从发行版名称返回 Matlab 版本

注意

此命令提供 Matlab 的正确版本映射，但不提供 MCR 的。

matlab_get_release_name_from_version¶

matlab_get_release_name_from_version(version release_name)

输入：version 是 Matlab 版本（例如 23.2.0）
输出：release_name 是发行版名称（R2023b）

从 Matlab 版本返回发行版名称

注意

此命令提供 Matlab 的正确版本映射，但不提供 MCR 的。

matlab_extract_all_installed_versions_from_registry¶

此函数解析 Windows 注册表并查找已安装的 Matlab 版本。找到的版本存储在给定 <versions-var> 中。

matlab_extract_all_installed_versions_from_registry(<versions-var> [REGISTRY_VIEW view])¶

3.30 版本新增。

输出：<versions-var> 是找到的所有 Matlab 版本列表
输入：REGISTRY_VIEW 用于注册表交互的可选注册表视图。参数传递（或省略）到 cmake_host_system_information()，不进行进一步检查或修改。

matlab_extract_all_installed_versions_from_registry(<win64> <versions-var>)¶

输入：win64 是一个布尔值，用于搜索 64 位版本的 Matlab。设置为 ON 以使用 64 位注册表视图，或设置为 OFF 以使用 32 位注册表视图。如果需要更精细的控制，请参阅上面的签名。
输出：<versions-var> 是找到的所有 Matlab 版本列表

返回的列表包含 HKLM\SOFTWARE\Mathworks\MATLAB、HKLM\SOFTWARE\Mathworks\MATLAB Runtime 和 HKLM\SOFTWARE\Mathworks\MATLAB Compiler Runtime 下的所有版本，或在发生错误（或未找到任何内容）时为空列表。

注意

仅提供版本。未检查注册表中引用的安装是否存在。

matlab_get_all_valid_matlab_roots_from_registry¶

使用 Matlab 或 Matlab Runtime (MCR) 的有效版本填充 Matlab 根。返回的 matlab_roots 以三元组 (type,version_number,matlab_root_path) 组织，其中 type 表示 MATLAB 或 MCR。

matlab_get_all_valid_matlab_roots_from_registry(matlab_versions matlab_roots [REGISTRY_VIEW view])

输入：每个 Matlab 或 MCR 安装的 matlab_versions
输出：每个 Matlab 或 MCR 安装的 matlab_roots 位置
输入：REGISTRY_VIEW 用于注册表交互的可选注册表视图。参数传递（或省略）到 cmake_host_system_information()，不进行进一步检查或修改。

3.30 版本新增：添加了可选的 REGISTRY_VIEW 参数，以提供与 Windows 注册表交互的更精确接口。

matlab_get_mex_suffix¶

返回 mex 文件的扩展名（后缀）。此函数不应在找到适当的 Matlab 根目录之前调用。

matlab_get_mex_suffix(matlab_root mex_suffix)

输入：matlab_root Matlab/MCR 安装的根目录，例如 Matlab_ROOT_DIR
输出：mex_suffix 将返回后缀的变量名。

matlab_get_version_from_matlab_run¶

此函数运行在参数中指定的 Matlab 程序并提取其版本。如果为 Matlab 安装提供的路径指向 MCR 安装，则从安装文件中提取版本。

matlab_get_version_from_matlab_run(matlab_binary_path matlab_list_versions)

输入：matlab_binary_path matlab 二进制可执行文件的路径
输出：matlab_list_versions 从 Matlab 提取的版本

matlab_add_unit_test¶

将 Matlab 单元测试添加到 cmake/ctest 的测试集中。此命令需要组件 MAIN_PROGRAM，因此不适用于 MCR 安装。

单元测试使用 Matlab 单元测试框架（默认，从 Matlab 2013b+ 开始可用），除非给出选项 NO_UNITTEST_FRAMEWORK。

该函数期望给出一个 Matlab 测试脚本文件。如果给出 NO_UNITTEST_FRAMEWORK，则单元测试脚本文件应包含要运行的脚本以及带有退出值的退出命令。此退出值将传递给 ctest 框架（0 成功，非 0 失败）。add_test() 接受的其他参数可以通过 TEST_ARGS 传递（例如 CONFIGURATION <config> ...）。

matlab_add_unit_test(
    NAME <name>
    UNITTEST_FILE matlab_file_containing_unittest.m
    [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
    [UNITTEST_PRECOMMAND matlab_command_to_run]
    [TIMEOUT timeout]
    [ADDITIONAL_PATH path1 [path2 ...]]
    [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
    [TEST_ARGS arg1 [arg2 ...]]
    [NO_UNITTEST_FRAMEWORK]
    )

函数参数

名称: ctest 中单元测试的名称。
UNITTEST_FILE: matlab 单元测试文件。其路径将自动添加到 Matlab 路径中。
CUSTOM_TEST_COMMAND: 要作为测试运行的 Matlab 脚本命令。如果未设置此项，则运行以下命令：runtests('matlab_file_name'), exit(max([ans(1,:).Failed]))，其中 matlab_file_name 是不带扩展名的 UNITTEST_FILE。
UNITTEST_PRECOMMAND: 在包含测试的文件运行之前要运行的 Matlab 脚本命令（例如，基于 CMake 变量的 GPU 设备初始化）。
TIMEOUT: 测试超时时间（秒）。默认为 180 秒，因为 Matlab 单元测试可能会挂起。
ADDITIONAL_PATH: 在运行单元测试之前要添加到 Matlab 路径的路径列表。
MATLAB_ADDITIONAL_STARTUP_OPTIONS: 从命令行运行 Matlab 的其他选项列表。-nosplash -nodesktop -nodisplay 始终添加。
TEST_ARGS: 提供给 add_test 命令的其他选项。这些选项添加到默认选项中（例如 "CONFIGURATIONS Release"）
NO_UNITTEST_FRAMEWORK: 设置时，表示测试不应使用 Matlab 的单元测试框架（适用于版本 >= R2013a）。
WORKING_DIRECTORY: 这将是测试的工作目录。如果指定，它也将是测试运行日志文件的输出目录。如果未指定，则临时目录 ${CMAKE_BINARY_DIR}/Matlab 将用作工作目录和日志位置。

matlab_add_mex¶

添加 Matlab MEX 目标。此命令使用当前工具链编译给定源文件以生成 MEX 文件。可以指定生成输出的最终名称，以及其他链接库和 MEX 文件的文档条目。调用的其余参数传递给 add_library() 或 add_executable() 命令。

matlab_add_mex(
    NAME <name>
    [EXECUTABLE | MODULE | SHARED]
    SRC src1 [src2 ...]
    [OUTPUT_NAME output_name]
    [DOCUMENTATION file.txt]
    [LINK_TO target1 target2 ...]
    [R2017b | R2018a]
    [EXCLUDE_FROM_ALL]
    [NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES]
    [...]
)

函数参数

名称: 目标的名称。
SRC: 源文件列表。
LINK_TO: 其他链接依赖项列表。除非传递 NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES 选项，否则目标默认链接到 libmex 和 libmx。
OUTPUT_NAME: 如果给定，则覆盖默认名称。默认名称是不带任何前缀且带有 Matlab_MEX_EXTENSION 后缀的目标名称。
DOCUMENTATION: 如果给定，文件 file.txt 将被视为 MEX 文件的文档文件。此文件将不经任何处理复制到同一文件夹中，名称与最终 mex 文件相同，扩展名为 .m。在这种情况下，在 Matlab 中键入 help <name> 会打印此文件中包含的文档。
R2017b 或 R2018a: 3.14 版新增。

可以指定要使用的 C API 版本：R2017b 指定传统的（单独复杂）C API，对应于 mex 命令的 -R2017b 标志。R2018a 指定新的交错复杂 C API，对应于 mex 命令的 -R2018a 标志。如果 Matlab 版本早于 R2018a，则忽略。默认为 R2017b。
MODULE 或 SHARED: 3.7 版本中新增。

可以指定要创建的库类型。
EXECUTABLE: 3.7 版本中新增。

可以指定创建可执行文件而不是库。如果没有明确指定类型，则类型为 SHARED。
EXCLUDE_FROM_ALL: 此选项与 EXCLUDE_FROM_ALL 具有相同的含义，并转发给 add_library() 或 add_executable() 命令。
NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES: 在 3.24 版本中添加。

此选项允许禁用 MATLAB 库的自动链接，这样只有实际需要的库才能通过 LINK_TO 选项链接。

文档文件未经过处理，应采用以下格式

% This is the documentation
function ret = mex_target_output_name(input1)

FindMatlab¶

模块输入变量¶

导入的目标¶

模块定义的变量¶

结果变量¶

缓存变量¶

提供的命令¶

已知问题¶

参考¶

目录

上一主题

下一主题

本页