FindMatlab

Находит Matlab или Matlab Compiler Runtime (MCR) и предоставляет инструменты, библиотеки и компиляторы Matlab для CMake.

Основное назначение этого пакета — найти библиотеки, связанные с Matlab или MCR, чтобы иметь возможность создавать расширения Matlab (файлы mex). Он также может использоваться:

для выполнения определенных команд в Matlab, если Matlab доступен
для объявления тестовых модулей Matlab
для получения различной информации из Matlab (расширения mex, версии и запросы выпуска и т. д.)

Добавлена в версии 3.12: Поддержка Matlab Compiler Runtime (MCR).

Модуль поддерживает следующие компоненты:

ENG_LIBRARY и MAT_LIBRARY: соответственно библиотеки ENG и MAT Matlab
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() и добавлена поддержка указания REGISTRY_VIEW для find_package(), matlab_extract_all_installed_versions_from_registry() и matlab_get_all_valid_matlab_roots_from_registry(). По умолчанию поведение осталось без изменений, используя вид реестра 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 задаются стандартными путями установки MATLAB в $HOME/Applications и /Applications. Если приложение не найдено, происходит возврат к приложению, которое может быть доступно из PATH.
Unix: Требуемая установка Matlab должна быть доступна из PATH. Это не работает для установки MCR, и Matlab_ROOT_DIR должен быть указан на этой платформе.

Дополнительная информация предоставляется, когда MATLAB_FIND_DEBUG установлен. Если установка Matlab/MCR найдена автоматически, и MATLAB_VERSION не указана, версия запрашивается непосредственно у Matlab (в Windows это может открыть окно Matlab) или из установки MCR.

Сопоставление имён релизов и версии Matlab выполняется путём определения пар (имя, версия). Переменная MATLAB_ADDITIONAL_VERSIONS может быть предоставлена перед вызовом find_package() для обработки дополнительных версий.

Сценарии Matlab могут быть добавлены в набор тестов с помощью matlab_add_unit_test(). По умолчанию для выполнения этого скрипта будет использоваться фреймворк тестов 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: Библиотека mx Matlab (массивы), всегда доступная для установок MATLAB. Доступна для установок MCR, если она предоставляется MCR.
Matlab::eng: Библиотека Matlab engine. Доступна только если запрошен компонент ENG_LIBRARY.
Matlab::mat: Библиотека матриц Matlab. Доступна только если запрошен компонент MAT_LIBRARY.
Matlab::MatlabEngine: Библиотека Matlab C++ engine, всегда доступна для MATLAB R2018a и новее. Доступна для установок MCR, если она предоставляется MCR.
Matlab::MatlabDataArray: Библиотека массивов данных Matlab C++, всегда доступна для MATLAB R2018a и новее. Доступна для установок MCR, если она предоставляется MCR.

Переменные, определённые модулем

Переменные результата

Matlab_FOUND: TRUE если установлена платформа Matlab, FALSE в противном случае. Все переменные ниже определены, если платформа Matlab найдена.
Matlab_VERSION: Добавлена в версии 3.27.

числовая версия (например, 23.2.0) найденной платформы Matlab. Не следует путать с именем выпуска Matlab (например, R2023b), которое можно получить с помощью matlab_get_release_name_from_version().
Matlab_ROOT_DIR: конечная корневая папка установки Matlab, определённая модулем FindMatlab.
Matlab_MAIN_PROGRAM: бинарная программа Matlab. Доступна только если компонент MAIN_PROGRAM указан в директиве find_package().
Matlab_INCLUDE_DIRS: путь к заголовочным файлам библиотек Matlab
Matlab_MEX_LIBRARY: библиотека для mex, всегда доступна для установок MATLAB. Доступна для установок MCR, если предоставлена MCR.
Matlab_MX_LIBRARY: библиотека mx платформы Matlab (массивы), всегда доступна для установок 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: компилятор mex Matlab. В настоящее время не используется. Доступен только если запрошен компонент MEX_COMPILER.
Matlab_MCC_COMPILER: Добавлена в версии 3.13.

компилятор mcc Matlab. Включен с дополнением 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-файле

По умолчанию, каждый символ внутри файла MEX, определенного с помощью команды matlab_add_mex(), имеет скрытую видимость, за исключением точки входа. Это поведение по умолчанию компилятора MEX, что снижает риск столкновения символов между библиотеками, поставляемыми с Matlab, и библиотеками, к которым ссылается файл MEX. Это также поведение по умолчанию на платформах Windows.

Однако этого может быть недостаточно в некоторых случаях, например, когда ваш MEX-файл ссылается на библиотеки, которые уже загружены Matlab, даже если эти библиотеки имеют разные SONAMES. Возможным решением является скрытие символов библиотек, к которым ссылается MEX-цель. Это можно сделать в компиляторах GNU GCC с помощью опции линкера -Wl,--exclude-libs,ALL.

Тесты, использующие ресурсы GPU

в случае, если ваш MEX-файл использует GPU, и для того, чтобы иметь возможность запускать модульные тесты на этом MEX-файле, ресурсы GPU должны быть правильно освобождены Matlab. Возможным решением является информирование 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 — логическое значение для поиска 64-битной версии Matlab. Установите 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 или Matlab Runtime (MCR). Возвращаемые 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_versions каждой из установок Matlab или MCR
Выходные данные: matlab_roots расположения каждой из установок Matlab или MCR
Входные данные: 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 unittest (по умолчанию, доступен начиная с Matlab 2013b+), если не указан параметр NO_UNITTEST_FRAMEWORK.

Функция ожидает один файл сценария Matlab для теста. В случае, если указан NO_UNITTEST_FRAMEWORK, файл сценария unittest должен содержать сценарий для выполнения плюс команду завершения с выходным значением. Это выходное значение будет передано в фреймворк 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 unittest. Его путь будет автоматически добавлен в путь Matlab.
CUSTOM_TEST_COMMAND: команда Matlab-скрипта для выполнения как теста. Если это не задано, выполняется следующее: runtests('matlab_file_name'), exit(max([ans(1,:).Failed])), где matlab_file_name – UNITTEST_FILE без расширения.
UNITTEST_PRECOMMAND: команда Matlab-скрипта для выполнения перед файлом, содержащим тест (например, инициализация устройства GPU на основе переменных CMake).
TIMEOUT: таймаут теста в секундах. По умолчанию 180 секунд, так как тест Matlab может зависнуть.
ADDITIONAL_PATH: список путей для добавления в путь Matlab перед запуском unit-теста.
MATLAB_ADDITIONAL_STARTUP_OPTIONS: список дополнительных опций для запуска Matlab из командной строки. -nosplash -nodesktop -nodisplay всегда добавляются.
TEST_ARGS: Дополнительные опции, предоставленные команде add_test. Эти опции добавляются к стандартным опциям (например, "CONFIGURATIONS Release").
NO_UNITTEST_FRAMEWORK: если установлено, указывает, что тест не должен использовать фреймворк unittest 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: список дополнительных зависимостей компоновки. Цель ссылается на libmex и libmx по умолчанию, если не указан параметр NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES.
OUTPUT_NAME: если задано, переопределяет имя по умолчанию. Имя по умолчанию – имя цели без префикса и с суффиксом Matlab_MEX_EXTENSION.
DOCUMENTATION: если задано, файл file.txt будет рассматриваться как файл документации для файла MEX. Этот файл копируется в ту же папку без обработки, с тем же именем, что и окончательный файл mex, и с расширением .m. В этом случае ввод help <name> в Matlab выводит документацию, содержащуюся в этом файле.
R2017b or R2018a: Добавлена в версии 3.14.

Может быть задано для указания версии C API для использования: R2017b указывает традиционный (отдельный комплексный) C API и соответствует флагу -R2017b для команды mex. R2018a указывает новый интегрированный комплексный C API и соответствует флагу -R2018a для команды mex. Игнорируется, если версия MATLAB предшествует R2018a. По умолчанию R2017b.
MODULE or 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)

© 2000–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.31/module/FindMatlab.html