QML 모듈을 CMake로 포팅하기

Qt 6에서는 QML 모듈이 더욱 강력해지고 사용하기 쉬워졌습니다. 다음 섹션에서는 QML 모듈을 qt_add_qml_module CMake API로 포팅하는 방법을 설명합니다.

이미 qt_add_qml_module을 사용하는 QML 모듈을 현대화하는 방법에 대해서는 QML 모듈 현대화도 참조하십시오.

수정할 문제 식별

qmllint를 사용하여 프로세스를 지원하세요.

qt_add_qml_module로 정의된 각 QML 모듈에는 잠재적인 문제나 개선 사항을 식별하는 데 사용할 수 있는 _qmllint CMake 타겟이 있습니다. 예를 들어 MyQmlLibrary 라는 QML 모듈의 경우 MyQmlLibrary_qmllint 을 사용합니다. 모든 QML 모듈에서 qmllint를 실행하려면 all_qmllint 을 사용합니다.

QML 모듈 문제를 암시하는 qmllint의 경고 범주는 다음과 같습니다:

• [import]
• [unused-imports]
• [해결되지 않은 유형]
• [해결되지 않은 별칭]
• [missing-enum-entry]
• [missing-property]
• [missing-type]

qt_add_qml_module을 위한 프로젝트 준비하기

CMake에서 qt_add_qml_module을 사용 가능하게 만들기

프로젝트의 최상위 CMakeLists.txt 파일에 있는 find_package 호출에 Core 및 Qml 을 추가하여 CMake에서 qt_add_qml_module을 사용할 수 있도록 합니다:

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

qt_standard_project_setup 사용

qt_standard_project_setup은 무엇보다도 qt_add_qml_module에 필요한 Qt CMake 정책을 설정합니다.

프로젝트의 최상위 레벨 CMakeLists.txt 파일에서 qt_add_qml_module을 호출하기 전에 qt_standard_project_setup을 호출합니다:

qt_standard_project_setup(REQUIRES 6.8)

qt_add_qml_module 사용

qt_add_qml_module은 QML 모듈 생성을 처리하는 CMake 함수입니다. qmldir 및 qmltypes 파일을 자동으로 생성하고 qmlcachegen 또는 qmllint와 같은 툴을 설정합니다.

QML 모듈은 CMake에서 실행 파일과 라이브러리 타깃 모두에 추가할 수 있습니다. 실행 파일 대상에 추가된 QML 모듈은 다른 실행 파일에서 사용하거나 링크할 수 없지만 라이브러리 대상에 추가된 QML 모듈은 가능합니다.

실행 대상에 QML 모듈 추가하기

이 경우 QML 모듈의 소스 파일은 별도의 라이브러리로 컴파일되지 않고 실행 파일 자체의 일부로 취급됩니다. 즉, 이 모듈을 위한 모듈이나 플러그인 라이브러리가 생성되지 않고 모듈이 실행 파일에 완전히 통합됩니다. 따라서 모듈은 특정 프로그램에 묶여 있으며 다른 실행 파일이나 라이브러리에서 재사용할 수 없습니다.

실행 파일에 QML 모듈을 추가하려면 CMakeLists.txt:

# pre-existing:
qt_add_executable(MyApp main.cpp)

# add this
qt_add_qml_module(MyApp
    URI MyAppModule
    QML_FILES
        Main.qml # and possibly more .qml files
)

Main.qml 은 QQmlApplicationEngine::loadFromModule 또는 QQmlComponent::loadFromModule 과 같은 loadFromModule 메서드로 인스턴스화할 수 있도록 대문자로 시작해야 합니다. 또한 빌드 폴더에서 이름 충돌을 방지하기 위해 QML 모듈 URI는 대상 이름과 달라야 합니다.

라이브러리 대상에 QML 모듈 추가

라이브러리에 QML 모듈을 추가하려면 CMakeLists.txt:

qt_add_qml_module(MyQmlLibrary
    URI MyQmlModule
    QML_FILES MyQmlComponent1.qml MyQmlComponent2.qml...
    SOURCES MyCppComponent1.h MyCppComponent1.cpp MyCppComponent2.h MyCppComponent2.cpp...
    RESOURCES MyResource1.png MyResource2.png...
)

이 예제에서와 같이 MyQmlLibrary 타깃이 아직 존재하지 않는 경우 qt_add_qml_module을 통해 SHARED 라이브러리를 생성합니다.

loadFromModule을 사용하여 QML 파일 로드하기

예를 들어 loadFromModule 을 사용하여 QML 파일을 로드합니다:

engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
// becomes
engine.loadFromModule("MyQmlModule", "Main");

손으로 쓴 qmldir 파일 제거하기

qt_add_qml_module은 qmldir 파일을 자동으로 생성합니다. qmldir 에 싱글톤이 있는 경우 qt_add_qml_module을 호출하기 전에 CMakeLists.txt 에 선언합니다:

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

그 뒤에 직접 작성한 qmldir 을 삭제하세요.

qmlplugindump로 생성된 qmltypes 파일 제거하기

모든 유형이 선언적 유형 등록을 사용하는 경우qt_add_qml_module은 qmltypes 파일을 자동 생성하므로 qmlplugindump 와 같은 도구를 사용하여 qmltypes 파일을 직접 생성할 필요가 없습니다.

이렇게 하려면 qmlRegisterType 및 그 변형에 대한 수동 호출을 제거하세요. 그런 다음 예를 들어 QML_ELEMENT 을 사용하여 선언적으로 유형을 등록하세요:

// add this header
#include <QtQml/qqmlregistrations.h>

class MyComponent: public QObject {
    Q_OBJECT

    // add this line to register MyComponent as 'MyComponent' in QML.
    QML_ELEMENT
    ....
};

외부 유형 등록과 같은 더 복잡한 등록 사례를 처리하는 방법은 QML 유형 시스템으로 C++ 유형 등록하기를 참조하세요.

그 후에 직접 작성한 qmltypes 파일을 삭제하세요.

손으로 쓴 타입 등록 플러그인 제거

qt_add_qml_module은 QML 모듈 플러그인을 자동으로 생성할 수 있습니다. 플러그인의 유일한 임무가 유형 등록이라면 손으로 쓴 플러그인이 필요하지 않습니다. 선언적 유형 등록으로 전환하여 플러그인에서 모든 코드가 제거된 경우 플러그인을 완전히 제거하세요.

자동 플러그인 생성을 허용하려면 qt_add_qml_module에서 NO_PLUGIN, NO_PLUGIN_OPTIONAL, NO_CREATE_PLUGIN_TARGET, NO_GENERATE_PLUGIN_SOURCE 인수를 제거해야 합니다.

qrc 파일 제거

qt_add_qml_module은 qrc 파일을 자동으로 생성합니다. 이미지나 사운드 파일과 같은 qrc 파일에 리소스를 나열하려면 qt_add_qml_module의 RESOURCES 인수에 추가합니다. 모듈의 리소스는 :/qt/qml/MyQmlLibraryModule/ 에서 찾을 수 있습니다.

디렉토리 임포트를 QML 모듈 임포트로 바꾸기

디렉터리 가져오기를 QML 모듈 가져오기로 대체합니다. 예를 들어

import "content" // contains SomeType.qml
// becomes
import MyQmlModule // contains SomeType.qml

SomeType {
    ...
}

QML 모듈 내부의 파일은 자체 QML 모듈을 자동으로 가져옵니다. 자체 가져오기를 제거할 수 있습니다.