qt_add_qml_plugin

Синопсис

qt_add_qml_plugin(
    target
    [BACKING_TARGET backing_target]
    [STATIC | SHARED]
    [OUTPUT_DIRECTORY]
    [URI]
    [CLASS_NAME]
    [NO_GENERATE_PLUGIN_SOURCE]
)

Если команды без версии отключены, используйте qt6_add_qml_plugin() вместо. Она поддерживает тот же набор аргументов, что и эта команда.

Описание

Эта команда создаёт целевой компонент плагина, связанный с модулем QML. Обычно она вызывается внутренне командой qt_add_qml_module() для создания или обновления плагина, связанного с целевым компонентом-основой. Вы не должны вызывать эту функцию напрямую, если у вас нет особых обстоятельств, требующих создания целевого компонента особым образом.

Документация для qt_add_qml_module() описывает различные структурные схемы для организации целевых компонентов CMake, связанных с модулем QML. Обратите внимание, что даже если модуль QML не имеет отдельного целевого компонента-основы и вся функциональность реализована непосредственно в плагине (что не рекомендуется), вы всё равно должны вызвать qt_add_qml_module(), а не qt_add_qml_plugin().

Аргументы

target указывает имя целевого компонента для использования в качестве плагина QML. Если он ещё не существует, он будет создан.

BACKING_TARGET указывает имя целевого компонента-основы, с которым связан плагин. Целевой компонент-основа может быть таким же, как и плагин target, в этом случае существует только один объединённый целевой компонент, но это не рекомендуется (см. qt_add_qml_module() для получения более подробной информации). BACKING_TARGET всегда должен быть указан, если нет особых обстоятельств, требующих создания целевого компонента плагина до целевого компонента-основы. Если BACKING_TARGET не указан, должен быть задан параметр URI.

По умолчанию плагин создаётся с типом, совместимым с целевым компонентом-основой. Если целевой компонент-основа — статическая библиотека, плагин также будет создан как статическая библиотека. Если целевой компонент-основа — динамическая библиотека, плагин будет создан как модульная библиотека. В случае отсутствия целевого компонента-основы или если плагин не имеет отдельного целевого компонента-основы, тип плагина можно указать с помощью ключевых слов STATIC или SHARED. Если тип плагина не определяется ни одним из вышеупомянутых условий, будет создан статический плагин, если Qt был скомпилирован как статические библиотеки, или модульная библиотека в противном случае.

OUTPUT_DIRECTORY указывает каталог, в котором будет создана библиотека плагина. Он всегда должен быть таким же, как и каталог файла qmldir модуля QML. Когда OUTPUT_DIRECTORY не указан, он будет получен из информации, хранящейся в BACKING_TARGET, если доступна. Обратите внимание, что это может отличаться от каталога библиотеки целевого компонента-основы. Если каталог вывода не может быть получен из целевого компонента-основы, по умолчанию используется CMAKE_CURRENT_BINARY_DIR.

URI объявляет идентификатор модуля QML, с которым связан этот плагин. Идентификатор модуля — это идентификатор модуля QML (в формате URI с точками). Если URI не указан, необходимо указать BACKING_TARGET и целевой компонент-основа должен иметь записанный в нём URI (обычно посредством предыдущего вызова qt_add_qml_module()).

Каждый плагин должен иметь класс C++, который регистрирует модуль в движке QML. По умолчанию, qt_add_qml_plugin() автоматически генерирует исходный код для этого класса C++, и добавляет его в список исходных файлов target . Сгенерированный класс плагина удовлетворяет требованиям необязательности плагина (см. Файлы qmldir определения модуля). Имя класса определяется следующим образом:

• Если CLASS_NAME задан, он будет использован. Он должен совпадать с именем, используемым в файле qmldir модуля QML.
• Если CLASS_NAME не задан, но BACKING_TARGET задан, имя класса C++ будет взято из данных, записанных в целевом компоненте-основе. Эти данные обычно записываются в результате предыдущего вызова qt_add_qml_module() и будут совпадать с именем, используемым в сгенерированном файле qmldir. Это рекомендуемый способ указания имени класса в большинстве случаев.
• Если имя класса по-прежнему не может быть определено, оно устанавливается равным URI модуля с точками, заменёнными на подчёркивания, и добавлен Plugin.

Некоторые плагины могут потребовать ручного написания класса плагина. Например, плагин может потребовать выполнения дополнительной инициализации или регистрации элементов, не реализованных в стандартном классе плагина. В таких случаях можно указать параметр NO_GENERATE_PLUGIN_SOURCE. Тогда вам придётся написать собственный класс плагина C++ и добавить его в target. Обратите внимание, что если вам необходимо написать собственный класс плагина, крайне маловероятно, что плагин может быть необязательным. Это, в свою очередь, означает, что ключевое слово NO_PLUGIN_OPTIONAL должно быть включено в вызов qt_add_qml_module() при определении модуля QML, иначе сгенерированный файл qmldir будет некорректным. Убедитесь, что ваш класс плагина использует то же самое имя класса, что и определено логикой выше.