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
• 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_DIR

корень установки MATLAB.

MATLAB_FIND_DEBUG

выводит отладочную информацию

MATLAB_ADDITIONAL_VERSIONS

дополнительные версии MATLAB для автоматического извлечения установленных версий.

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

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

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

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 (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 в набор тестов cmake/ctest. Эта команда требует компонента MAIN_PROGRAM и, следовательно, недоступна для установки MCR.

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

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

NAME

имя целевого объекта.

SRC

список файлов исходного кода.

LINK_TO

список дополнительных зависимостей для линковки. Целевой объект по умолчанию ссылается на libmex и libmx.

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().

Файл документации не обрабатывается и должен быть в следующем формате:

% This is the documentation
function ret = mex_target_output_name(input1)