FindMatlab

Ищет установленные инсталляции MATLAB и предоставляет инструменты и библиотеки MATLAB для CMake.

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

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

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

• MX_LIBRARY и ENG_LIBRARY соответственно библиотеки MX и ENG MATLAB
• MAIN_PROGRAM — исполняемый файл MATLAB.

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

• Windows: установленные версии MATLAB извлекаются из реестра Windows
• macOS: установленные версии MATLAB задаются путями к MATLAB в /Application. Если такое приложение не найдено, используется приложение, которое может быть доступно из переменной среды PATH.
• Unix: требуемый MATLAB должен быть доступен из переменной среды PATH.

Дополнительная информация предоставляется при установке MATLAB_FIND_DEBUG. Если исполняемый файл MATLAB найден автоматически, и MATLAB_VERSION не задан, версия запрашивается непосредственно у MATLAB. В Windows это может привести к появлению окна с запущенным MATLAB.

Сопоставление имён релизов и версии 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 (массивы). Доступна только если компонент MX_LIBRARY был запрошен.

Matlab_ENG_LIBRARY

библиотека MATLAB Engine. Доступна только если компонент ENG_LIBRARY был запрошен.

Matlab_LIBRARIES

весь набор библиотек MATLAB

Matlab_MEX_COMPILER

компилятор mex MATLAB. В настоящее время не используется. Доступен только если компонент MEX_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, в соответствии с предварительно заданным списком. Сохраняются только существующие/доступные пути. Это в основном полезно для поиска всех возможных установок MATLAB.

matlab_get_mex_suffix()

возвращает суффикс, который будет использоваться для файлов mex (зависит от платформы/архитектуры)

matlab_get_version_from_matlab_run()

возвращает версию MATLAB, зная полный путь к исполняемому файлу MATLAB.

Известные проблемы

Столкновение символов в 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 или пустой список в случае ошибки (или если ничего не найдено).

Примечание

Предоставляются только версии. Проверка наличия установки, указанной в реестре, не выполняется.

matlab_get_all_valid_matlab_roots_from_registry

Заполняет корень Matlab допустимыми версиями Matlab. Возвращаемый matlab_roots организован в пары (version_number,matlab_root_path).

matlab_get_all_valid_matlab_roots_from_registry(
    matlab_versions
    matlab_roots)

matlab_versions

версии каждой из установок Matlab

matlab_roots

местоположение каждой из установок Matlab

matlab_get_mex_suffix

Возвращает расширение файлов mex (суффиксы). Эту функцию не следует вызывать до того, как будет найден соответствующий корень Matlab.

matlab_get_mex_suffix(
    matlab_root
    mex_suffix)

matlab_root

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

mex_suffix

имя переменной, в которой будет возвращен суффикс.

matlab_get_version_from_matlab_run

Эта функция запускает программу Matlab, указанную в аргументах, и извлекает её версию.

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. Тест использует фреймворк 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
    [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.

UNITTEST_PRECOMMAND

команда сценария Matlab, которая должна быть выполнена перед файлом, содержащим тест (например, инициализация устройства GPU на основе переменных CMake).

TIMEOUT

время ожидания теста в секундах. По умолчанию 180 секунд, так как тест Matlab может зависнуть.

ADDITIONAL_PATH

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

MATLAB_ADDITIONAL_STARTUP_OPTIONS

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

TEST_ARGS

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

NO_UNITTEST_FRAMEWORK

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

matlab_add_mex

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

matlab_add_mex(
    NAME <name>
    SRC src1 [src2 ...]
    [OUTPUT_NAME output_name]
    [DOCUMENTATION file.txt]
    [LINK_TO target1 target2 ...]
    [...]
)

NAME

имя цели.

SRC

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

LINK_TO

список дополнительных зависимостей для подключения. Цель подключается к libmex по умолчанию. Если Matlab_MX_LIBRARY определено, также подключается к libmx.

OUTPUT_NAME

если указано, заменяет имя по умолчанию. Имя по умолчанию - имя цели без префикса и с Matlab_MEX_EXTENSION суффиксом.

DOCUMENTATION

если задано, файл file.txt будет рассматриваться как файл документации для файла MEX. Этот файл копируется в ту же папку без обработки, с тем же именем, что и конечный файл mex, и с расширением .m. В этом случае, набрав help <name> в Matlab, отображается содержимое документации в этом файле.

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

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