FindMatlab¶

找到 Matlab 或 Matlab 编译器运行时 (MCR)，并为 CMake 提供 Matlab 工具、库和编译器。

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

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

3.12 版本已添加：已添加 Matlab 编译器运行时 (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：应该能够从 PATH 访问所需的 Matlab。这对于 MCR 安装不起作用，应该在这个平台上指定 Matlab_ROOT_DIR。

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

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

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

模块输入变量¶

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

Matlab_ROOT: 在 3.25 版本中添加。

对于 Matlab 安装的根目录 Matlab_ROOT_DIR 的默认值。
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_get_release_name_from_version() 中获得的 Matlab 发行版名称（例如R2023b）混淆。
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 编译器附加组件中。仅当请求组件 MCC_COMPILER 时才可用。

缓存变量¶

Matlab_MEX_EXTENSION: 当前平台 mex 文件的扩展名（由 Matlab 提供）。
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 加载的库，即使这些库有不同的 SONAME。一种可能的解决方案是隐藏 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 版本。找到的版本存储在 matlab_versions。

matlab_extract_all_installed_versions_from_registry(matlab_versions [REGISTRY_VIEW view])¶

在版本 3.30 中添加。

输出：matlab_versions 是找到的所有 Matlab 版本的列表
输入：REGISTRY_VIEW 可选的注册表视图，用于注册表交互。此参数会将（或忽略）传给 cmake_host_system_information()，而无需进行其他检查或修改。

matlab_extract_all_installed_versions_from_registry(win64 matlab_versions)¶

输入：win64 是一个用于搜索 Matlab 64 位版本的布尔值。将其设置为 ON 以使用 64 位注册表视图，或将其设置为 OFF 以使用 32 位注册表视图。如果需要更精细的控制，请参阅上方的签名。
输出：matlab_versions 是找到的所有 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]
    )

函数参数

NAME: 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]
    [...]
)

函数参数

NAME: 目标的名称。
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¶

模块输入变量¶

导入的目标¶

模块定义的变量¶

结果变量¶

缓存变量¶

提供的命令¶

已知问题¶

参考¶

目录

前一主题

下一主题

本页