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. Доступна только если затребован компонент 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, файл скрипта unit-теста должен содержать скрипт для запуска, плюс команду выхода со значением выхода. Это значение выхода будет передано фреймворку 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

имя unit-теста в ctest.

UNITTEST_FILE

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

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)