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. Доступна только если запрошен компонент 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, даже если эти библиотеки имеют разные 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
    [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 перед запуском 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

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