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
• macOS: установленные версии 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, даже если у этих библиотек разные 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)