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：所需的 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

当前平台的 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 文件上运行单元测试，GPU 资源应由 Matlab 正确释放。一种可能的解决方案是使 Matlab 意识到会话中 GPU 资源的使用，这可以通过诸如 D = gpuDevice() 之类的命令在测试脚本的开头执行（或通过 fixture）。

参考

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/MCR 安装的 matlab_root 根目录，例如 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 二进制可执行文件的 matlab_binary_path 路径

• 输出：从 Matlab 提取的 matlab_list_versions 版本

matlab_add_unit_test

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

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

该函数期望给出一个 Matlab 测试脚本文件。在给出 NO_UNITTEST_FRAMEWORK 的情况下，单元测试脚本文件应包含要运行的脚本，以及带有退出值的 exit 命令。此退出值将传递给 ctest 框架（0 表示成功，非 0 表示失败）。可以通过 TEST_ARGS 传递 add_test() 接受的其他参数（例如 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 的 unittest 框架（适用于 >= 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)