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 и вызовет ошибку, если вместо обычной установки Matlab будет обнаружен MCR.
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. Эти библиотеки находятся безусловно.

Примечание

Версия, заданная директиве find_package(), представляет собой версию Matlab, которую не следует путать с именем релиза Matlab (например, R2014). matlab_get_version_from_release_name() и matlab_get_release_name_from_version() обеспечивают отображение между именем релиза и версией.

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

Windows: Установленные версии Matlab/MCR извлекаются из реестра Windows
OS X: Установленные версии 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 для автоматического получения установленных версий.

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

Новое в версии 3.22.

Этот модуль определяет следующие IMPORTED цели:

Matlab::mex: Библиотека mex, всегда доступна.
Matlab::mx: Библиотека mx Matlab (массивы), всегда доступна.
Matlab::eng: Библиотека Matlab Engine. Доступна только если запрашивается компонент ENG_LIBRARY.
Matlab::mat: Библиотека матриц Matlab. Доступна только если запрашивается компонент MAT_LIBRARY.
Matlab::MatlabEngine: Библиотека Matlab C++ Engine, всегда доступна для R2018a и новее.
Matlab::MatlabDataArray: Библиотека массивов данных Matlab C++, всегда доступна для R2018a и новее.

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

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

Matlab_FOUND: TRUE если установка Matlab найдена, FALSE в противном случае. Все переменные ниже определены, если Matlab найден.
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 Engine. Доступна только если запрашивается компонент ENG_LIBRARY.
Matlab_MAT_LIBRARY: библиотека матриц Matlab. Доступна только если запрашивается компонент MAT_LIBRARY.
Matlab_ENGINE_LIBRARY: Новое в версии 3.13.

библиотека Matlab C++ Engine, всегда доступна для 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_get_release_name_from_version(): возвращает имя релиза из версии Matlab

Предоставленные функции

matlab_add_mex(): добавляет целевой файл для компиляции MEX-файла.
matlab_add_unit_test(): добавляет файл Matlab unit test в качестве теста в проект.
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 (17.58) по имени релиза (R2017k).

matlab_get_release_name_from_version: Возвращает имя релиза (R2017k) по версии Matlab (17.58).

matlab_extract_all_installed_versions_from_registry: Эта функция анализирует реестр и находит установленные версии Matlab. Найденные версии возвращаются в matlab_versions. Установите win64 на TRUE, если нужно искать 64-битную версию Matlab. Возвращаемый список содержит все версии по HKLM\\SOFTWARE\\Mathworks\\MATLAB и HKLM\\SOFTWARE\\Mathworks\\MATLAB 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
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 unit-тест к набору тестов cmake/ctest. Эта команда требует компонента MAIN_PROGRAM и поэтому недоступна для установки MCR.

Unit-тест использует фреймворк 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: имя unit-теста в 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 unit-тест может зависнуть.
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

Добавляет целевой 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)

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