qt_add_qml_plugin

QML 모듈과 연관된 플러그인을 정의합니다.

이 명령어는 ` Qt6 ` 패키지의 ` Qml ` 컴포넌트에 정의되어 있으며, 다음과 같이 불러올 수 있습니다:

find_package(Qt6 REQUIRED COMPONENTS Qml)

개요

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

버전 정보가 없는 명령어가 비활성화된 경우, 대신 qt6_add_qml_plugin() 을 사용하십시오. 이 명령어는 본 명령어와 동일한 인자 세트를 지원합니다.

설명

이 명령은 QML 모듈과 연관된 플러그인 타깃을 생성합니다. 일반적으로 qt_add_qml_module() 에 의해 내부적으로 호출되어, 해당 백킹 타깃과 연관된 플러그인을 생성하거나 업데이트합니다. 특별한 방식으로 타깃을 생성해야 하는 특별한 상황이 아닌 이상, 이 함수를 직접 호출해서는 안 됩니다.

qt_add_qml_module() 에 대한 문서에는 QML 모듈과 연관된 CMake 타깃을 구성하는 다양한 구조적 패턴이 설명되어 있습니다. QML 모듈에 별도의 백킹 타겟이 없고 모든 기능이 플러그인 내에서 직접 구현되는 경우(권장되는 방식은 아님)에도, ` qt_add_qml_plugin()` 대신 ` qt_add_qml_module()` 을 호출해야 합니다.

인수

target 는 QML 플러그인에 사용할 타깃의 이름을 지정합니다. 해당 타깃이 아직 존재하지 않으면 생성됩니다.

BACKING_TARGET 플러그인이 연결된 백킹 타깃의 이름을 지정합니다. 백킹 타깃은 플러그인 target 과 동일할 수 있으며, 이 경우 병합된 타깃은 하나뿐이지만 일반적으로 권장되지 않습니다(자세한 내용은 qt_add_qml_module() 참조). 플러그인 타깃을 백킹 타깃보다 먼저 생성해야 하는 특별한 상황이 아닌 한, BACKING_TARGET 는 항상 제공되어야 합니다. BACKING_TARGET 가 제공되지 않는 경우, URI 옵션을 반드시 지정해야 합니다.

기본적으로 플러그인은 백킹 타깃과 호환되는 유형으로 생성됩니다. 백킹 타깃이 정적 라이브러리인 경우, 플러그인도 정적 라이브러리로 생성됩니다. 백킹 타깃이 공유 라이브러리인 경우, 플러그인은 모듈 라이브러리로 생성됩니다. 백킹 타겟이 지정되지 않았거나 플러그인에 별도의 백킹 타겟이 없는 경우, 플러그인 유형은 STATIC 또는 SHARED 키워드 중 하나로 지정할 수 있습니다. 앞서 언급한 조건 중 어느 것으로도 플러그인 유형이 결정되지 않는 경우, Qt가 정적 라이브러리로 빌드된 경우에는 정적 플러그인이 생성되고, 그렇지 않은 경우에는 모듈 라이브러리 플러그인이 생성됩니다.

OUTPUT_DIRECTORY 플러그인 라이브러리가 생성될 디렉터리를 지정합니다. 이 위치는 항상 QML 모듈의 qmldir 파일에 명시된 위치와 동일해야 합니다. OUTPUT_DIRECTORY 가 지정되지 않은 경우, 가능한 경우 BACKING_TARGET 에 저장된 정보에서 해당 위치를 가져옵니다. 이는 백킹 타깃 자체 라이브러리의 디렉터리와 다를 수 있다는 점에 유의하십시오. 백킹 타깃에서 출력 디렉터리를 가져올 수 없는 경우, 기본적으로 CMAKE_CURRENT_BINARY_DIR 이 사용됩니다.

URI 이 플러그인이 연관된 QML 모듈의 모듈 식별자를 선언합니다. 모듈 식별자는 QML 모듈에 대한 (점 구분 URI 표기법) 식별자입니다. URI 가 지정되지 않은 경우, BACKING_TARGET 를 제공해야 하며, 백킹 타깃에 해당 URI가 기록되어 있어야 합니다(일반적으로 이전에 qt_add_qml_module()을 호출하여 기록됨).

각 플러그인에는 QML 엔진에 모듈을 등록하는 C++ 클래스가 있어야 합니다. 기본적으로 qt_add_qml_plugin() 는 이 C++ 클래스의 소스 코드를 자동 생성하여 target 의 소스 목록에 추가합니다. 생성된 플러그인 클래스는 플러그인이 선택 사항이어야 한다는 요구 사항을 충족합니다( ‘모듈 정의 qmldir 파일’ 참조). 클래스 이름은 다음과 같이 결정됩니다:

• CLASS_NAME 가 지정된 경우, 해당 이름이 사용됩니다. 이 이름은 QML 모듈의 qmldir 파일에 사용된 이름과 일치해야 합니다.
• CLASS_NAME 가 지정되지 않았으나 BACKING_TARGET 가 지정된 경우, C++ 클래스 이름은 해당 백킹 타깃에 기록된 세부 정보에서 가져옵니다. 이러한 세부 정보는 대개 이전에 qt_add_qml_module()을 호출하여 기록된 것이며, 생성된 qmldir 파일에서 사용된 이름과 일치합니다. 이는 대부분의 상황에서 클래스 이름을 제공하는 권장 방법입니다.
• 그래도 클래스 이름을 결정할 수 없는 경우, 모듈의 URI에서 점(.)을 밑줄(_)로 대체하고 Plugin 를 추가한 값으로 설정됩니다.

NAMESPACE 키워드와 함께 네임스페이스가 지정된 경우, 플러그인 코드는 이 이름의 C++ 네임스페이스 내에 생성됩니다.

일부 플러그인의 경우 플러그인 클래스를 수동으로 작성해야 할 수도 있습니다. 예를 들어, 플러그인이 추가 초기화를 수행하거나 기본 플러그인 클래스에서 구현되지 않은 항목을 등록해야 할 수 있습니다. 이러한 경우 NO_GENERATE_PLUGIN_SOURCE 옵션을 지정할 수 있습니다. 이 경우 사용자는 직접 C++ 플러그인 클래스를 작성하여 ` target`에 추가해야 합니다. 직접 플러그인 클래스를 작성해야 하는 경우, 해당 플러그인을 선택 사항으로 설정할 가능성은 매우 낮다는 점에 유의하십시오. 이는 다시 말해, QML 모듈을 정의할 때 qt_add_qml_module() 호출에 NO_PLUGIN_OPTIONAL 키워드를 포함해야 함을 의미하며, 그렇지 않으면 생성된 qmldir 파일에 오류가 발생합니다. 플러그인 클래스가 바로 위의 논리에 따라 결정된 것과 동일한 클래스 이름을 사용하는지 확인하십시오.