FindMatlab

Находит установленные инсталляции MATLAB и предоставляет инструменты и библиотеки MATLAB для cmake.

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

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

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

• MX_LIBRARY, ENG_LIBRARY и MAT_LIBRARY: соответственно библиотеки MX, ENG и MAT MATLAB
• MAIN_PROGRAM программа бинарного исполняемого файла MATLAB.
• MEX_COMPILER компилятор MEX.
• SIMULINK среда Simulink.

Переменная 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_MAT_LIBRARY

библиотека MATLAB матриц. Доступна только если компонент MAT_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, даже если у этих библиотек разные SONAME. Возможным решением является скрытие символов библиотек, с которыми связан целевой 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
    [CUSTOM_MATLAB_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 unittest. Его путь будет автоматически добавлен в путь Matlab.

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

NAME

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

SRC

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

LINK_TO

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

OUTPUT_NAME

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

DOCUMENTATION

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

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)