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 и вызовет ошибку, если вместо обычной установки Matlab будет найдена MCR.
• MEX_COMPILER — MEX-компилятор.
• MCC_COMPILER — MCC-компилятор, включённый в дополнение Matlab Compiler.
• SIMULINK — среда Simulink.

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

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

Matlab::mx

Библиотека mx Matlab (массивы), всегда доступная для установок 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

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 Engine. Доступна только если запрошен компонент ENG_LIBRARY.

Matlab_MAT_LIBRARY

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

Matlab_ENGINE_LIBRARY

Новая в версии 3.13.

библиотека Matlab C++ Engine, всегда доступна для 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

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

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)