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 и вызовет ошибку, если найден MCR вместо обычной установки Matlab.
• 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. Доступна только если запрошен компонент ENG_LIBRARY.

Matlab_MAT_LIBRARY

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

Matlab_ENGINE_LIBRARY

библиотека движка Matlab C++, всегда доступна для R2018a и новее.

Matlab_DATAARRAY_LIBRARY

библиотека массивов данных Matlab C++, всегда доступна для R2018a и новее.

Matlab_LIBRARIES

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

Matlab_MEX_COMPILER

компилятор mex Matlab. В настоящее время не используется. Доступна только если запрошен компонент MEX_COMPILER.

Matlab_MCC_COMPILER

компилятор 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, файл скрипта 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

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

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]
    [...]
)

NAME

имя целевого файла.

SRC

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

LINK_TO

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

OUTPUT_NAME

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

DOCUMENTATION

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

R2017b or R2018a may be given to specify the version of the C API

для использования: R2017b указывает традиционный (отдельный комплексный) C API и соответствует флагу -R2017b для команды mex . R2018a указывает новый интегрированный комплексный C API и соответствует флагу -R2018a для команды mex. Игнорируется для версий MATLAB до R2018a. По умолчанию R2017b.

MODULE or SHARED may be given to specify the type of library to be

создано. EXECUTABLE может быть указано, чтобы создать исполняемый файл вместо библиотеки. Если тип не задан явно, тип SHARED.

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

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