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
• OS X: Установленные версии 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 (по умолчанию, доступен начиная с 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
    [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.

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

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

matlab_add_mex

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