CMake를 활용한 통합

qt_add_qml_module CMake 명령어는 QML 모듈을 정의하는 데 권장되는 방법입니다. 이 명령어는 타입 등록, 리소스 임베딩, 플러그인 생성 및 툴 통합을 자동화합니다. 이 페이지에서는 ` qt_add_qml_module `의 기본 개념을 설명하고 일반적인 사용 패턴을 단계별로 안내합니다.

모든 옵션에 대한 전체 참조 내용은 qt_add_qml_module을 참조하십시오.

핵심 개념

예제를 살펴보기 전에, qt_add_qml_module 가 실제로 무엇을 생성하는지 이해하는 것이 도움이 됩니다:

• 백킹 타겟 ( backing target ) — 모듈의 C++ 코드, 컴파일된 QML 파일 및 리소스를 포함하는 라이브러리(또는 실행 파일)입니다. 이는 ` qt_add_qml_module `의 첫 번째 인자이며, 링크 대상으로 사용되는 타겟입니다. 기존 타겟( qt_add_executable 또는 qt_add_library 로 미리 생성된 것)일 수도 있고, ` qt_add_qml_module `가 이를 대신 생성해 줄 수도 있습니다.
• 플러그인 타겟 — QML 엔진이 실행 시점에 모듈을 동적으로 로드할 수 있게 해주는 작은 라이브러리입니다. 이 타겟은 자동으로 생성되며 백킹 타겟과는 별개입니다. 실행 파일이 백킹 타겟에 직접 링크될 경우, 플러그인은 실행 시점에 로드되지 않습니다. NO_PLUGIN을 사용하여 플러그인을 완전히 생략할 수 있습니다.
• qmldir 파일 — 모듈이 제공하는 유형과 해당 유형을 찾을 수 있는 위치를 QML 엔진에 알려주는 모듈 메타데이터 파일입니다. 이 파일은 자동으로 생성됩니다.
• typeinfo 파일 (.qmltypes) — QML 툴링(qmlcachegen, qmllint, qmlls, Qt Creator)에서 사용하는 기계 가독형 타입 정보입니다. 이 파일 또한 자동으로 생성됩니다.

디렉터리 구조

소스 디렉터리 구조는 모듈의 URI를 반영해야 합니다. URI는 점을 슬래시로 대체하여 경로로 변환됩니다. 예를 들어, URI가 MyCompany.Controls 인 모듈은 다음 위치에 있어야 합니다:

src/MyCompany/Controls/CMakeLists.txt
src/MyCompany/Controls/Button.qml
src/MyCompany/Controls/mywidget.cpp
src/MyCompany/Controls/mywidget.h

이 규칙을 따르면 QML 엔진과 툴링이 별도의 구성 없이도 모듈을 찾을 수 있습니다. 디렉터리 구조가 URI와 일치하지 않는 경우, 빌드 결과물이 URI와 일치하는 경로에 저장되도록 OUTPUT_DIRECTORY를 설정하고, QML 엔진과 툴링이 모듈을 찾을 수 있도록 IMPORT_PATH를 설정해야 합니다.

일반적인 패턴

QML 전용 애플리케이션

가장 간단한 경우: C++ 타입이 없고 QML 파일만 포함된 실행 파일입니다.

cmake_minimum_required(VERSION 3.16)
project(myapp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)
qt_standard_project_setup(REQUIRES 6.8)

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
        Button.qml
    RESOURCES
        images/logo.png
)

target_link_libraries(myapp PRIVATE Qt6::Quick)

백업 대상이 실행 파일이기 때문에 플러그인은 생성되지 않습니다. QML 파일은 컴파일되어 리소스로 포함됩니다. RESOURCES 키워드는 QML이 아닌 파일(이미지, 글꼴 등)을 동일한 리소스 계층 구조에 추가합니다.

C++ 타입이 포함된 애플리케이션

QML에 C++ 타입을 노출하는 애플리케이션:

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
    SOURCES
        backend.cpp backend.h
)

backend.h 내의 C++ 타입은 QML_ELEMENT (또는 QML_NAMED_ELEMENT 와 같은 유사한 매크로)로 주석이 달아야 하며, Q_OBJECT 또는 Q_GADGET 매크로를 사용해야 합니다. 타입 등록은 AUTOMOC 를 통해 자동으로 이루어집니다. 사용 가능한 등록 매크로에 대한 전체 개요는 ‘QML 타입 시스템에 C++ 타입 등록하기’를 참조하십시오.

재사용 가능한 라이브러리 모듈

다른 프로젝트나 모듈에서 가져올 수 있도록 라이브러리로 패키지화된 QML 모듈:

# In src/MyCompany/Controls/CMakeLists.txt
qt_add_qml_module(mycontrols
    URI MyCompany.Controls
    QML_FILES
        Button.qml
        Slider.qml
    SOURCES
        theme.cpp theme.h
)

이렇게 하면 mycontrols (백엔드 라이브러리)와 mycontrolsplugin (플러그인)이라는 두 개의 타깃이 생성됩니다. 다른 모듈은 QML에서 ` import MyCompany.Controls `를 사용하여 이를 임포트합니다. ` mycontrols `에 직접 링크하는 애플리케이션은 실행 시점에 플러그인을 로드할 필요가 없습니다.

라이브러리 모듈을 사용하는 애플리케이션

위의 ‘재사용 가능한 라이브러리 모듈’ 예제에서 mycontrols 모듈을 사용하는 방법:

# In the application's CMakeLists.txt
qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES Main.qml
    DEPENDENCIES TARGET mycontrols
)

target_link_libraries(myapp PRIVATE mycontrols)

DEPENDENCIES 줄은 QML 툴링(qmlcachegen, qmllint, qmlls)이 MyCompany.Controls 에서 제공하는 타입을 찾을 수 있도록 보장합니다.

// In Main.qml
import MyCompany.Controls

Button { text: "Click me" }

싱글톤을 포함하는 모듈

싱글톤 타입을 제공하는 QML 파일은 qt_add_qml_module 호출 앞에 소스 파일 속성을 설정해야 합니다:

set_source_files_properties(Theme.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Theme.qml
        Main.qml
)

또한 QML 파일에는 pragma Singleton 가 포함되어야 합니다. CMake 속성과 QML 프래그마가 모두 필요합니다.

사용자 정의 플러그인이 포함된 모듈

사용자 정의 초기화(예: 이미지 제공자 등록)를 수행해야 하는 경우, 자체 QQmlEngineExtensionPlugin 서브클래스를 제공할 수 있습니다.

# In CMakeLists.txt
qt_add_qml_module(mymodule
    URI MyModule
    NO_GENERATE_PLUGIN_SOURCE
    NO_PLUGIN_OPTIONAL
    CLASS_NAME MyModulePlugin
    QML_FILES
        Main.qml
    SOURCES
        myimageprovider.cpp myimageprovider.h
)

# Add the custom plugin source to the plugin target
target_sources(mymoduleplugin PRIVATE plugin.cpp)

// In plugin.cpp
#include <QtQml/QQmlEngineExtensionPlugin>
#include "myimageprovider.h"

class MyModulePlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
public:
    void initializeEngine(QQmlEngine *engine, const char *uri) override
    {
        engine->addImageProvider("myprovider", new MyImageProvider);
    }
};

#include "plugin.moc"

NO_GENERATE_PLUGIN_SOURCE는 빌드 시스템에 기본 플러그인 소스 코드를 생성하지 말라고 지시합니다. CLASS_NAME은 구현 내의 클래스 이름과 일치해야 합니다. NO_PLUGIN_OPTIONAL은 그렇지 않을 경우 건너뛸 수 있는 초기화 로직을 포함하고 있으므로, 플러그인이 항상 로드되도록 보장합니다.

추가 QML 파일 추가

초기 qt_add_qml_module 호출 이후에 추가된 QML 파일의 경우, qt_target_qml_sources를 사용하십시오:

qt_target_qml_sources(my_qml_module
    QML_FILES
        DynamicallyAddedType.qml
)

이는 플랫폼이나 구성에 따라 파일을 조건부로 포함할 때 유용합니다.

자세한 CMake 참조

모든 CMake 명령어, 속성, 변수 및 정책에 대한 자세한 내용은 QML용 CMake 통합을 참조하십시오.