FindMatlab

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

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

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

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

• ENG_LIBRARY и MAT_LIBRARY: соответственно библиотеки ENG и MAT Matlab
• MAIN_PROGRAM — программа Matlab. Обратите внимание, что этот компонент недоступен в версии MCR и вызовет ошибку, если будет найден MCR вместо обычной установки Matlab.
• MEX_COMPILER — компилятор MEX.
• MCC_COMPILER — компилятор MCC, включенный с дополнением Matlab Compiler.
• SIMULINK — среда Simulink.

Переменную Matlab_ROOT_DIR можно задать для указания пути к желаемой версии Matlab. В противном случае поведение зависит от платформы:

• Windows: Установленные версии Matlab/MCR извлекаются из реестра Windows
• macOS: Установленные версии Matlab/MCR задаются стандартными путями установки MATLAB в /Application. Если такое приложение не найдено, используется то, что может быть доступно из 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 для автоматического получения установленных версий.

Импортированные целевые объекты

Этот модуль определяет следующие IMPORTED целевые объекты:

Matlab::mex

Библиотека mex, всегда доступна.

Matlab::mx

Библиотека mx Matlab (массивы), всегда доступна.

Matlab::eng

Библиотека движка Matlab. Доступна только если запрошен компонент ENG_LIBRARY.

Matlab::mat

Библиотека матриц Matlab. Доступна только если запрошен компонент MAT_LIBRARY.

Matlab::MatlabEngine

Библиотека движка Matlab C++, всегда доступна для R2018a и более поздних версий.

Matlab::MatlabDataArray

Библиотека массивов данных Matlab C++, всегда доступна для R2018a и более поздних версий.

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

Результатные переменные

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_MX_LIBRARY

Библиотека mx Matlab (массивы), всегда доступна.

Matlab_ENG_LIBRARY

Библиотека движка Matlab. Доступна только если запрошен компонент ENG_LIBRARY.

Matlab_MAT_LIBRARY

Библиотека матриц Matlab. Доступна только если запрошен компонент MAT_LIBRARY.

Matlab_ENGINE_LIBRARY

Добавлено в версии 3.13.

Библиотека движка Matlab C++, всегда доступна для R2018a и более поздних версий.

Matlab_DATAARRAY_LIBRARY

Добавлено в версии 3.13.

Библиотека массивов данных Matlab C++, всегда доступна для R2018a и более поздних версий.

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, и для того, чтобы запустить unit-тесты на этом 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

matlab_extract_all_installed_versions_from_registry(win64 matlab_versions)

• Вход: win64 — булево значение для поиска 64-битной версии Matlab
• Выход: matlab_versions — список всех найденных версий Matlab

Эта функция парсит реестр Windows и находит установленные версии Matlab. Найденные версии возвращаются в matlab_versions. Установите win64 на TRUE, если нужно искать 64-битную версию 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)

• Вход: matlab_versions каждой из установок Matlab или MCR
• Выход: matlab_roots расположение каждой из установок Matlab или MCR

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

Добавляет unit-тест Matlab в набор тестов cmake/ctest. Эта команда требует компонента MAIN_PROGRAM и, следовательно, недоступна для установки MCR.

Unit-тест использует фреймворк Matlab unittest (по умолчанию, доступен начиная с Matlab 2013b+), если не указана опция NO_UNITTEST_FRAMEWORK.

Функция ожидает один файл скрипта Matlab-теста. В случае, если указано NO_UNITTEST_FRAMEWORK, файл сценария unit-теста должен содержать скрипт для выполнения, а также команду выхода со значением выхода. Это значение выхода будет передано фреймворку 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

имя unit-теста в ctest.

UNITTEST_FILE

файл Matlab unit-теста. Его путь будет автоматически добавлен в путь 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 unit-тест может зависать.

ADDITIONAL_PATH

список путей для добавления в путь Matlab перед запуском unit-теста.

MATLAB_ADDITIONAL_STARTUP_OPTIONS

список дополнительных опций для запуска Matlab из командной строки. -nosplash -nodesktop -nodisplay всегда добавляются.

TEST_ARGS

Дополнительные опции, предоставленные команде add_test. Эти опции добавляются к стандартным опциям (например, "CONFIGURATIONS Release")

NO_UNITTEST_FRAMEWORK

При установке указывает, что тест не должен использовать фреймворк unit-тестов Matlab (доступен для версий >= R2013a).

WORKING_DIRECTORY

Будет рабочим каталогом для теста. Если указано, также будет каталогом вывода для файла журнала выполнения теста. Если не указано, каталогом будет временный каталог ${CMAKE_BINARY_DIR}/Matlab, и он же будет местом для файла журнала.

matlab_add_mex

Добавляет целевой MEX-файл MATLAB. Эта команда компилирует указанные исходные файлы с текущей инструментальной цепочкой для создания 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)