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 unit test (>= 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.

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_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

имя теста в 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

Добавляет цель 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)