QT_ADD_QML_MODULE

이 명령은 Qt 6.2에 도입되었습니다.

개요

qt_add_qml_module(
    target
    URI uri
    [VERSION version]
    [PAST_MAJOR_VERSIONS ...]
    [STATIC | SHARED]
    [PLUGIN_TARGET plugin_target]
    [OUTPUT_DIRECTORY output_dir]
    [RESOURCE_PREFIX resource_prefix]
    [CLASS_NAME class_name]
    [TYPEINFO typeinfo]
    [IMPORTS ...]
    [OPTIONAL_IMPORTS ...]
    [DEFAULT_IMPORTS ...]
    [DEPENDENCIES ...]
    [IMPORT_PATH ...]
    [SOURCES ...]
    [QML_FILES ...]
    [RESOURCES ...]
    [OUTPUT_TARGETS out_targets_var]
    [DESIGNER_SUPPORTED]
    [FOLLOW_FOREIGN_VERSIONING]
    [NAMESPACE namespace]
    [NO_PLUGIN]
    [NO_PLUGIN_OPTIONAL]
    [NO_CREATE_PLUGIN_TARGET]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NO_GENERATE_QMLTYPES]
    [NO_GENERATE_QMLDIR]
    [NO_GENERATE_EXTRA_QMLDIRS]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_RESOURCE_TARGET_PATH]
    [NO_IMPORT_SCAN]
    [ENABLE_TYPE_COMPILER]
    [TYPE_COMPILER_NAMESPACE namespace]
    [QMLTC_EXPORT_DIRECTIVE export_macro]
    [QMLTC_EXPORT_FILE_NAME header_defining_export_macro]

)

버전 없는 명령이 비활성화되어 있으면 qt6_add_qml_module() 을 대신 사용합니다. 이 명령과 동일한 인수 집합을 지원합니다.

QML 모듈을 정의하는 예는 QML 애플리케이션 빌드하기 및 재사용 가능한 QML 모듈 빌드하기를 참조하세요.

QML 모듈에 대한 정보가 프로젝트에 노출되도록 프로젝트를 구성하려면 QT_QML_GENERATE_QMLLS_INI를 참조하십시오. QML Language Server.

설명

이 명령은 C++ 소스, .qml 파일 또는 둘 다로 구성될 수 있는 QML 모듈을 정의합니다. 이 명령은 필수 모듈 세부 정보가 제공되고 일관성을 유지하도록 합니다. 또한 .qml 소스의 캐시 컴파일, 리소스 임베딩, 린팅 검사 및 일부 주요 모듈 파일의 자동 생성과 같은 기능을 설정하고 조정합니다.

대상 구조

QML 모듈은 몇 가지 다른 방식으로 구조화할 수 있습니다. 다음 시나리오는 일반적인 배열입니다:

별도의 백킹 및 플러그인 타깃 분리

대부분의 QML 모듈에 권장되는 배열입니다. 모듈의 모든 기능은 첫 번째 명령 인수로 제공되는 백킹 대상에서 구현됩니다. C++ 소스, .qml 파일 및 리소스는 모두 백킹 타깃에 추가해야 합니다. 백킹 타깃은 프로젝트에서 정의한 다른 라이브러리와 같은 위치에 설치해야 하는 라이브러리입니다.

백업 대상이 생성되는 소스 디렉터리 구조는 QML 모듈의 대상 경로와 일치해야 합니다(대상 경로는 점으로 대체된 모듈의 URI이며 슬래시로 대체됨). 소스 디렉터리 구조가 대상 경로와 일치하지 않으면 qt_add_qml_module() 에서 경고를 표시합니다.

다음 예는 URI가 MyThings.Panels 인 QML 모듈에 적합한 소스 디렉터리 구조를 보여줍니다. qt_add_qml_module() 에 대한 호출은 표시된 CMakeLists.txt 파일에 있습니다.

src
 +-- MyThings
      +-- Panels
           +-- CMakeLists.txt

별도의 플러그인 타깃이 QML 모듈과 연결됩니다. 애플리케이션이 아직 백킹 대상에 연결되지 않은 경우 런타임에 모듈을 동적으로 로드하는 데 사용됩니다. 플러그인 타깃은 라이브러리이기도 하며 일반적으로 모듈의 qmldir 파일과 같은 디렉터리에 설치됩니다.

플러그인 타깃에는 플러그인 클래스의 사소한 구현만 포함하는 것이 이상적입니다. 이렇게 하면 qmldir 파일에서 플러그인을 선택 사항으로 지정할 수 있습니다. 그러면 다른 타깃이 백업 타깃에 직접 링크할 수 있고 런타임에 플러그인이 필요하지 않으므로 로드 시간 성능이 향상될 수 있습니다. 기본적으로 최소한의 플러그인 클래스를 정의하는 C++ 소스 파일이 자동으로 생성되어 플러그인 타겟에 추가됩니다. QML 모듈에 사용자 지정 플러그인 클래스 구현이 필요한 경우 NO_GENERATE_PLUGIN_SOURCE 및 일반적으로 NO_PLUGIN_OPTIONAL 옵션이 필요합니다.

STATIC QML 모듈은 NO_PLUGIN 을 지정하지 않으면 정적 QML 플러그인을 생성하기도 합니다. 이러한 STATIC QML 모듈을 가져오는 대상은 해당 QML 플러그인에 명시적으로 링크해야 합니다.

지원 대상이 없는 플러그인 대상

플러그인 타깃을 자체 백킹 타깃으로 사용하여 QML 모듈을 정의할 수 있습니다. 이 경우 모듈은 런타임에 동적으로 로드되어야 하며 다른 타깃에서 직접 링크할 수 없습니다. 이러한 배열을 만들려면 PLUGIN_TARGET 키워드를 사용해야 하며, 플러그인 타겟 이름으로 target 을 반복해야 합니다. 예를 들어

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

이 배열은 배포가 약간 더 간단해 보일 수 있지만 로드 시간 성능이 잠재적으로 더 좋을 수 있으므로 가능한 경우 별도의 백업 타깃을 사용하는 것이 좋습니다.

QML 모듈로 실행

실행 타깃은 QML 모듈의 백업 타깃으로 사용할 수 있습니다. 이 경우 QML 모듈은 항상 애플리케이션의 일부로 직접 로드되므로 플러그인 라이브러리가 없습니다. qt_add_qml_module() 명령은 실행 파일이 백업 대상으로 사용되는 시기를 감지하여 별도의 플러그인 생성을 자동으로 비활성화합니다. 이 배열을 사용할 때는 이름에 PLUGIN 이 포함된 옵션을 사용하지 마세요.

실행 파일을 백업 대상으로 사용하는 경우 소스 디렉터리 구조가 QML 모듈의 대상 경로와 일치하지 않을 것으로 예상됩니다. 컴파일된 리소스에 대한 추가적인 대상 경로 차이점은 컴파일된 QML 소스 캐싱하기를 참조하세요.

qmldir 및 typeinfo 파일 자동 생성

기본적으로 정의 중인 QML 모듈에 대해 qmldir 파일과 typeinfo 파일이 자동 생성됩니다. 이러한 파일의 내용은 이 명령에 주어진 다양한 인수와 백업 대상에 추가된 소스 및 .qml 파일에 따라 결정됩니다. OUTPUT_DIRECTORY 인수는 qmldir 및 typeinfo 파일이 기록될 위치를 결정합니다. QML 모듈에 플러그인이 있는 경우 해당 플러그인도 qmldir 파일과 같은 디렉터리에 만들어집니다.

QTP0004 정책이 NEW 로 설정된 경우 .qml 파일이 포함된 추가 디렉토리에 대해 qmldir 파일이 하나 더 생성됩니다. 이러한 추가 qmldir 파일은 prefer 지시문을 통해 모듈의 기본 디렉토리로 리디렉션될 뿐입니다. 이는 모듈의 모든 QML 컴포넌트가 어느 디렉터리에 저장되어 있든 서로 액세스할 수 있도록 하기 위한 것입니다.

정적으로 빌드된 Qt를 사용하는 경우, CMake 구성 실행 중에 백업 대상의 .qml 파일을 검사하여 모듈에서 사용하는 임포트를 결정하고 연결 관계를 설정합니다( NO_IMPORT_SCAN 키워드를 지정하여 이를 비활성화할 수 있음). .qml 파일이 모듈에 추가되거나 모듈에서 제거되면 일반적으로 CMakeLists.txt 파일이 수정되었으므로 CMake가 자동으로 다시 실행되고 관련 파일이 다시 스캔됩니다. 개발 과정에서 기존 .qml 파일에 가져오기 또는 유형이 추가되거나 제거될 수 있습니다. 이 자체로는 CMake가 자동으로 다시 실행되지 않으므로 명시적으로 CMake를 다시 실행하여 qmldir 파일을 다시 생성하고 모든 연결 관계를 업데이트해야 합니다.

빌드 시점에 백업 대상의 C++ 소스를 스캔하여 typeinfo 파일과 관련 유형을 등록하는 C++ 파일을 생성합니다. 생성된 C++ 파일은 자동으로 백업 대상에 소스로 추가됩니다. 이를 위해서는 대상에서 AUTOMOC 을 활성화해야 합니다. 일반적으로 qt_add_qml_module() 을 호출하기 전에 CMAKE_AUTOMOC 변수를 TRUE 으로 설정하거나 AUTOMOC 대상 속성이 이미 TRUE 으로 설정된 기존 대상을 전달하여 이를 보장할 책임이 프로젝트에 있습니다. 대상에서 AUTOMOC 이 비활성화되어 있어도 오류는 아니지만 프로젝트가 결과를 처리할 책임이 있습니다. 여기에는 누락된 세부 정보가 있는 typeinfo 파일을 자동 생성하도록 허용하는 대신 수동으로 생성하고 유형을 등록하기 위해 C++ 코드를 추가해야 하는 작업이 포함될 수 있습니다.

프로젝트는 가능하면 자동 생성된 typeinfo 및 qmldir 파일을 사용하는 것을 선호해야 합니다. 유지 관리가 더 쉽고 손으로 직접 작성한 파일과 같은 오류에 취약하지 않습니다. 하지만 프로젝트에서 이러한 파일을 직접 제공해야 하는 상황에서는 자동 생성을 비활성화할 수 있습니다. NO_GENERATE_QMLDIR 옵션은 qmldir 자동 생성을 비활성화하고 NO_GENERATE_QMLTYPES 옵션은 typeinfo 및 C++ 유형 등록 자동 생성을 비활성화합니다. 자동 생성된 typeinfo 파일은 허용되지만 프로젝트에서 해당 파일에 다른 이름을 사용하려는 경우 TYPEINFO 옵션을 사용하여 기본 이름을 재정의할 수 있습니다(일반적으로는 필요하지 않음).

컴파일된 QML 소스 캐싱

QML_FILES 인수를 통해 모듈에 추가된 모든 .qml, .js, .mjs 파일은 바이트코드로 컴파일되어 백킹 대상에 직접 캐시됩니다. 이렇게 하면 모듈의 로드 시간 성능이 향상됩니다. 컴파일되지 않은 원본 파일도 백업 대상의 리소스에 저장되는데, 이는 특정 상황에서 QML 엔진이 여전히 필요할 수 있기 때문입니다.

각 파일의 리소스 경로는 현재 소스 디렉터리(CMAKE_CURRENT_SOURCE_DIR)를 기준으로 한 경로에 따라 결정됩니다. 이 리소스 경로는 RESOURCE_PREFIX와 대상 경로를 연결하여 형성된 접두사에 추가됩니다(단, 이에 대한 예외는 NO_RESOURCE_TARGET_PATH를 참조하세요).

QTP0001 정책이 NEW 으로 설정된 경우 RESOURCE_PREFIX는 기본적으로 QML 엔진의 기본 가져오기 경로인 /qt/qml/ 으로 설정됩니다. 이렇게 하면 모듈이 QML 가져오기 경로에 배치되며 추가 설정 없이도 모듈을 찾을 수 있습니다.

일반적으로 프로젝트는 .qml 파일을 리소스에서와 동일한 상대 위치에 배치하는 것을 목표로 해야 합니다. .qml 파일이 원하는 리소스 경로와 다른 상대 디렉터리에 있는 경우 리소스에서 해당 파일의 위치를 명시적으로 지정해야 합니다. 이는 QT_RESOURCE_ALIAS 소스 파일 속성을 설정하여 수행되며, .qml 파일을 추가하기 전에 설정해야 합니다. 예를 들어

set_source_files_properties(path/to/somewhere/MyFrame.qml PROPERTIES
    QT_RESOURCE_ALIAS MyFrame.qml
)

qt_add_qml_module(someTarget
    URI MyCo.Frames
    RESOURCE_PREFIX /my.company.com/imports
    QML_FILES
        path/to/somewhere/MyFrame.qml
        AnotherFrame.qml
)

위의 예에서 대상 경로는 MyCo/Frames 입니다. 소스 파일 속성을 고려한 후 두 개의 .qml 파일은 다음 리소스 경로에서 찾을 수 있습니다:

• /my.company.com/imports/MyCo/Frames/MyFrame.qml
• /my.company.com/imports/MyCo/Frames/AnotherFrame.qml

드물지만 사용할 qmlcachegen 프로그램의 자동 선택을 재정의하려는 경우 모듈 대상에 QT_QMLCACHEGEN_EXECUTABLE 대상 속성을 설정할 수 있습니다. 예를 들어

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

이렇게 하면 더 나은 대체 프로그램을 사용할 수 있는 경우에도 사용할 프로그램으로 qmlcachegen이 명시적으로 선택됩니다.

또한 QT_QMLCACHEGEN_ARGUMENTS 옵션을 설정하여 추가 인수를 qmlcachegen에 전달할 수 있습니다. 특히 --only-bytecode 옵션은 QML 스크립트 코드를 C++로 컴파일하는 기능을 해제합니다. 예를 들어

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)

또 다른 중요한 인수는 --direct-calls 입니다. Qt Quick Compiler 확장이 설치되어 있는 경우 이를 사용하여 QML 스크립트 컴파일러의 직접 모드를 활성화할 수 있습니다. 확장이 설치되어 있지 않으면 인수가 무시됩니다. 이를 위한 QT_QMLCACHEGEN_DIRECT_CALLS 이라는 단축키가 있습니다.

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_DIRECT_CALLS ON
)

마지막으로 --verbose 인수를 사용하여 qmlcachegen의 진단 출력을 볼 수 있습니다:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--verbose"
)

이 플래그를 설정하면 qmlcachegen은 C++로 컴파일할 수 없는 각 함수에 대해 경고를 출력합니다. 이러한 경고 중 일부는 QML 코드의 문제를 가리키고 일부는 QML 언어의 특정 기능이 C++ 코드 생성기에서 구현되지 않았음을 알려줍니다. 두 경우 모두 qmlcachegen은 해당 함수에 대한 바이트 코드를 생성합니다. QML 코드의 문제만 확인하려면 대신 qmllint와 그에 대해 생성된 타깃을 사용해야 합니다.

QML 소스 린팅하기

QML_FILES 키워드를 통해 또는 나중에 qt_target_qml_sources()를 호출하여 .qml 파일이 모듈에 추가되면 별도의 린팅 타겟이 자동으로 생성됩니다. 린팅 타겟의 이름은 target 다음에 _qmllint 이 됩니다. 모든 개별 *_qmllint 타깃에 의존하는 all_qmllint 타깃도 편의상 제공됩니다.

.js 파일의 이름 지정 규칙

컴포넌트로 지정하려는 JavaScript 파일 이름은 대문자로 시작해야 합니다.

또는 소문자 파일 이름을 사용하고 소스 파일 속성 QT_QML_SOURCE_TYPENAME을 원하는 유형 이름으로 설정할 수 있습니다.

싱글톤

QML 모듈에 싱글톤 유형을 제공하는 .qml 파일이 있는 경우, 이러한 파일의 QT_QML_SINGLETON_TYPE 소스 속성을 TRUE 로 설정해야 singleton 명령이 qmldir 파일에 기록됩니다. 이 작업은 pragma Singleton 문이 포함된 QML 파일과 함께 수행해야 합니다. 싱글톤이 속한 모듈을 만들기 전에 소스 속성을 설정해야 합니다.

QT_QML_SINGLETON_TYPE 속성을 설정하는 방법에 대한 예는 qt_target_qml_sources()를 참조하세요.

QML 타입 컴파일러로 QML을 C++로 컴파일하기

QML 모듈에 .qml 파일이 있는 경우, qmltc를 사용하여 C++로 컴파일할 수 있습니다. 바이트코드 컴파일과 달리, ENABLE_TYPE_COMPILER 인수를 통해 명시적으로 qmltc를 활성화해야 합니다. 이 경우 QML_FILES 아래에 지정된 .qml 파일이 컴파일됩니다. .js 및 .mjs 로 끝나는 파일은 qmltc가 자바스크립트 코드를 컴파일하지 않으므로 무시됩니다. 또한 QT_QML_SKIP_TYPE_COMPILER 소스 파일 속성으로 표시된 파일도 건너뜁니다.

기본적으로 qmltc는 지정된 .qml 파일에 대해 소문자 .h 및 .cpp 파일을 생성합니다. 예를 들어 Foo.qml 은 foo.h 과 foo.cpp 로 컴파일됩니다.

생성된 C++ 파일은 target 의 BINARY_DIR 하위 디렉터리의 전용 .qmltc/<target>/ 하위 디렉터리에 배치됩니다. 그러면 이 파일은 자동으로 대상 소스에 추가되고 다른 소스 파일과 함께 Qt C++ 코드로 컴파일됩니다.

QML_FILES를 처리하는 동안 다음과 같은 소스 파일 속성이 준수됩니다:

• QT_QMLTC_FILE_BASENAME이 소스 파일 속성을 사용하여 기본값이 아닌 .h 및 .cpp 파일 이름을 지정하면 충돌하는 파일 이름을 해결하는 데 유용할 수 있습니다(예: 컴파일 중인 main.qml이 있지만 main.h가 이미 존재하므로 #include "main.h"가 예상한 대로 작동하지 않을 수 있다고 가정해 보십시오). QT_QMLTC_FILE_BASENAME은 파일 이름(확장자 제외)으로 예상되므로 앞의 디렉터리는 모두 무시됩니다. 기본 동작의 경우와 달리 QT_QMLTC_FILE_BASENAME은 소문자가 아닙니다.
• QT_QML_SKIP_TYPE_COMPILER이 소스 파일 속성을 사용하여 QML 파일을 무시하도록 지정할 수 있습니다.

인수

필수 인수

target 은 QML 모듈의 백업 대상 이름을 지정합니다. 기본적으로 Qt가 공유 라이브러리로 빌드된 경우 공유 라이브러리로, 그렇지 않은 경우 정적 라이브러리로 생성됩니다. 이 선택은 STATIC 또는 SHARED 옵션을 사용하여 명시적으로 재정의할 수 있습니다.

모든 QML 모듈은 URI. QtQuick.Layouts 과 같은 점으로 구분된 URI 표기법으로 지정해야 합니다. 각 세그먼트는 올바른 형식의 ECMAScript 식별자 이름이어야 합니다. 예를 들어 세그먼트가 숫자로 시작해서는 안 되며 - (마이너스) 문자를 포함해서는 안 된다는 뜻입니다. URI 은 디렉토리 이름으로 번역되므로 라틴 알파벳의 영숫자, 밑줄 및 점으로 제한해야 합니다. 다른 QML 모듈은 모듈을 가져오기 위해 가져오기 문에서 이 이름을 사용할 수 있습니다. URI 은 생성된 qmldir 파일의 module 줄에 사용됩니다. URI 는 점을 슬래시로 대체하여 대상 경로를 형성하는 데에도 사용됩니다.

모듈 URI에 대한 자세한 내용은 식별된 모듈을 참조하세요.

버전

QML 모듈은 Major.Minor 형식으로 VERSION 를 정의할 수도 있습니다. 여기서 Major 와 Minor 는 모두 정수여야 합니다. .Patch 컴포넌트를 추가할 수 있지만 무시됩니다. 모듈이 유형을 제공하는 이전 주요 버전 목록은 PAST_MAJOR_VERSIONS 키워드 뒤에 선택적으로 지정할 수도 있습니다(아래 참조). 버전 번호 지정에 대한 자세한 내용은 식별된 모듈, 이전 주요 버전을 등록하는 방법은 이전 주요 버전 등록하기, 모듈 버전을 동기화 상태로 유지하는 방법은 모듈 버전 동기화 유지하기를 참조하세요.

버전이 필요하지 않은 경우 VERSION 인수를 생략해야 합니다. 기본값은 가능한 가장 높은 버전입니다. QML 모듈의 내부 버전 관리에는 몇 가지 근본적인 결함이 있습니다. 외부 패키지 관리 메커니즘을 사용하여 QML 모듈의 여러 버전을 관리해야 합니다.

모듈에 소스 및 리소스 추가하기

SOURCES 는 백업 대상에 추가할 비QML 소스 목록을 지정합니다. 이 기능은 편의를 위해 제공되며 기본 제공 target_sources() CMake 명령으로 소스를 백업 대상에 추가하는 것과 동일합니다.

QML_FILES 모듈의 .qml, .js 및 .mjs 파일을 나열합니다. NO_CACHEGEN 옵션을 지정하지 않으면 이 파일들은 자동으로 바이트코드로 컴파일되어 지원 대상에 임베드됩니다. 컴파일되지 않은 파일은 NO_CACHEGEN 을 지정하더라도 항상 백업 대상의 임베디드 리소스에 저장됩니다. NO_LINT 옵션을 지정하지 않으면 컴파일되지 않은 파일은 별도의 사용자 정의 빌드 대상을 통해 qmllint 에서도 처리됩니다. 또한 이 파일은 기본적으로 생성된 qmldir 파일의 유형 정보를 채우는 데 사용됩니다. NO_GENERATE_QMLDIR 을 지정하면 qmldir 파일의 자동 생성을 비활성화할 수 있습니다. 일반적으로는 사용하지 않는 것이 좋지만 프로젝트에서 자체 qmldir 파일을 제공해야 하는 경우 이 옵션을 사용할 수 있습니다. Qt 6.8부터 QTP0004를 활성화하면 qt_add_qml_module 은 QML 모듈의 각 하위 디렉터리에 대해 qmldir 파일을 추가로 생성하여 각 QML 파일이 암시적 가져오기를 통해 자체 모듈을 가져오도록 합니다. 이 동작은 NO_GENERATE_EXTRA_QMLDIRS 플래그를 전달하여 QML 모듈에 대해 해제할 수 있습니다. NO_GENERATE_QMLDIR 은 NO_GENERATE_EXTRA_QMLDIRS 을 의미합니다.

RESOURCES 는 QML 코드에서 참조된 이미지와 같이 모듈에 필요한 다른 파일을 나열합니다. 이러한 파일은 컴파일된 리소스로 추가됩니다(해당 파일이 위치할 기준점에 대한 설명은 RESOURCE_PREFIX 참조). 필요한 경우 .qml 파일과 마찬가지로 QT_RESOURCE_ALIAS 소스 속성을 설정하여 상대 위치를 제어할 수 있습니다( 컴파일된 QML 소스 캐싱 참조).

RESOURCE_PREFIX 는 프로젝트의 네임스페이스를 캡슐화하기 위한 것으로, 프로젝트가 정의하는 모든 QML 모듈에 대해 동일한 경우가 많습니다. 프로젝트에서 사용하거나 사용할 가능성이 있는 다른 프로젝트의 리소스 접두사와 충돌하지 않도록 선택해야 합니다. 프로젝트가 속한 조직의 도메인 이름을 통합하는 것도 좋은 선택입니다. 일반적인 규칙은 도메인 이름에 /imports 을 추가하여 리소스 접두사를 만드는 것입니다. 예를 들어

qt_add_qml_module(someTarget
    RESOURCE_PREFIX /my.company.com/imports
    ...
)

컴파일된 리소스에 다양한 파일이 추가되면 RESOURCE_PREFIX 와 대상 경로를 연결하여 형성된 경로 아래에 배치됩니다. 백업 대상이 실행 파일인 특수한 경우에는 모듈의 .qml 파일 및 기타 리소스를 RESOURCE_PREFIX 바로 아래에 배치하는 것이 바람직할 수 있습니다. 이는 NO_RESOURCE_TARGET_PATH 옵션을 지정하여 수행할 수 있으며, 이는 백업 대상이 실행 파일인 경우에만 사용할 수 있습니다.

과거 주요 버전 등록하기

PAST_MAJOR_VERSIONS 에는 모듈이 제공하는 추가 주요 버전 목록이 포함되어 있습니다. 이러한 각 버전과 QT_QML_SOURCE_VERSIONS 설정이 없는 각 QML 파일에 대해 추가 버전을 지정하기 위해 qmldir 파일에 추가 항목이 생성됩니다. 또한 생성된 모듈 등록 코드는 C++ 쪽에서 qmlRegisterModule()를 사용하여 과거의 주요 버전을 등록합니다. NO_GENERATE_QMLTYPES 을 지정하지 않는 한 모듈 등록 코드는 QML 모듈에 대해 자동으로 생성됩니다(하지만 이 옵션의 사용을 권장하지 않습니다). PAST_MAJOR_VERSIONS 을 사용하면 모듈을 가져올 때 약간의 오버헤드가 추가됩니다. 모듈의 주 버전을 가능한 한 드물게 증가시켜야 합니다. 이 모듈을 임포트하는 모든 QML 파일에서 임포트 시 버전을 생략할 수 있게 되면 PAST_MAJOR_VERSIONS 을 생략해도 안전합니다. 그러면 모든 QML 파일이 모듈의 최신 버전을 가져오게 됩니다. 버전별 가져오기를 지원해야 하는 경우에는 제한된 수의 과거 주요 버전만 지원하는 것을 고려하세요.

모듈 종속성 선언하기

IMPORTS 모듈 종속성 선언은 이 모듈이 임포트하는 다른 QML 모듈의 목록을 제공합니다. 여기에 나열된 각 모듈은 생성된 qmldir 파일에 import 항목으로 추가됩니다. QML 파일이 이 모듈을 가져오면 IMPORTS 아래에 나열된 모든 모듈도 함께 가져옵니다. 선택적으로 QtQuick/2.0 와 같이 슬래시 뒤에 버전을 추가하여 버전을 지정할 수 있습니다. 버전을 생략하면 사용 가능한 가장 큰 버전이 가져옵니다. QtQuick/2 과 같이 주 버전만 지정할 수도 있습니다. 이 경우 지정된 주 버전과 함께 사용 가능한 가장 큰 부 버전을 가져옵니다. 마지막으로 auto 을 버전(QtQuick/auto)으로 지정할 수 있습니다. auto 을 지정하면 현재 모듈을 가져오기 중인 버전이 가져오려는 모듈에 전파됩니다. 모듈에 QtQuick/auto 항목이 주어졌을 때 YourModule, QML 파일이 import YourModule 3.14 을 지정하면 QtQuick 의 버전 3.14 을 가져오게 됩니다. 일반적인 버전 관리 체계를 따르는 관련 모듈의 경우 auto 을 사용해야 합니다.

OPTIONAL_IMPORTS 는 이 모듈이 런타임에 임포트할 수 있는 다른 QML 모듈의 목록을 제공합니다. 현재 모듈을 임포트할 때 QML 엔진이 자동으로 가져오는 것이 아니라 qmllint 와 같은 도구에 대한 힌트 역할을 합니다. 버전은 IMPORTS 와 같은 방식으로 지정할 수 있습니다. 여기에 나열된 각 모듈은 생성된 qmldir 파일에 optional import 항목으로 추가됩니다.

DEFAULT_IMPORTS 는 선택적 가져오기 중 툴링에 의해 로드되어야 하는 기본 항목을 지정합니다. 모듈의 모든 OPTIONAL_IMPORTS 그룹에 대해 하나의 항목을 지정해야 합니다. 선택적 임포트는 런타임에만 확인되므로 일반적으로 qmllint와 같은 도구는 어떤 선택적 임포트를 확인해야 하는지 알 수 없습니다. 이 문제를 해결하려면 선택적 가져오기 중 하나를 기본 가져오기로 지정하면 도구가 이를 선택합니다. 추가 구성 없이 런타임에 사용되는 선택적 가져오기가 하나 있는 경우 기본 가져오기에 이상적인 후보입니다.

DEPENDENCIES 는 이 모듈이 종속되어 있지만 반드시 임포트하지는 않는 다른 QML 모듈의 목록을 제공합니다. 일반적으로 다른 모듈에 정의된 클래스의 서브클래스인 클래스를 QML에 등록하는 모듈과 같이 C++ 수준에서만 존재하는 종속성에 사용됩니다.

예를 들어 QQuickItem 을 다음과 같이 서브클래싱하려는 경우입니다:

class MyItem: public QQuickItem { ... };

를 포함하는 QQuickItem, QtQuick 을 포함하는 모듈이 DEPENDENCIES 옵션을 통해 종속성으로 선언되었는지 확인해야 합니다. 그렇게 하지 않으면 qmltc를 사용한 유형 컴파일 또는 qmlcachegen을 사용한 C++로의 바인딩 및 함수 컴파일 중에 오류가 발생할 수 있습니다.

종속성의 모듈 버전은 모듈 이름과 함께 IMPORTS 및 OPTIONAL_IMPORTS 에 사용된 것과 동일한 형식으로 지정해야 합니다. 여기에 나열된 각 모듈은 생성된 qmldir 파일에 depends 항목으로 추가됩니다.

IMPORT_PATH 를 사용하여 이 모듈이 의존하는 다른 QML 모듈을 찾을 수 있는 검색 경로에 추가할 수 있습니다. 다른 모듈은 검색 경로 중 하나 아래의 자체 대상 경로 아래에 qmldir 파일이 있어야 합니다.

백업 대상이 정적 라이브러리이고 해당 정적 라이브러리가 설치될 경우 OUTPUT_TARGETS 에 설치해야 하는 추가 대상 목록을 저장할 변수를 제공해야 합니다. 이러한 추가 대상은 qt_add_qml_module() 에서 내부적으로 생성되며 리소스가 올바르게 설정되고 로드되는지 확인하기 위한 일환으로 백업 대상의 연결 요구 사항에서 참조합니다.

타깃 및 플러그인 타깃

PLUGIN_TARGET QML 모듈과 연결된 플러그인 대상을 지정합니다. PLUGIN_TARGET 은 백킹 target 과 동일할 수 있으며, 이 경우 별도의 백킹 타깃이 없습니다. PLUGIN_TARGET 을 지정하지 않으면 기본값은 plugin 이 추가된 target 입니다. 예를 들어 mymodule 라는 백업 대상의 기본 플러그인 이름은 mymoduleplugin 입니다. 플러그인 대상의 이름은 생성된 qmldir 파일의 plugin 행을 채우는 데 사용됩니다. 따라서 OUTPUT_NAME 같은 대상 속성이나 관련 속성을 설정하여 플러그인의 출력 이름을 변경하려고 해서는 안 됩니다.

백업 target 과 플러그인 대상(다른 경우)은 이미 존재하지 않는 한 명령에 의해 생성됩니다. 프로젝트는 일반적으로 명령에 의해 생성되도록 하여 적절한 대상 유형으로 생성되도록 해야 합니다. target 백업이 정적 라이브러리인 경우 플러그인도 정적 라이브러리로 생성됩니다. target 이 공유 라이브러리인 경우 플러그인은 모듈 라이브러리로 생성됩니다. 기존 target 이 전달되고 실행 가능한 대상인 경우 플러그인이 생성되지 않습니다. 항상 백업 대상에 직접 연결하고 플러그인이 필요하지 않은 경우 NO_PLUGIN 옵션을 추가하여 비활성화할 수 있습니다. NO_PLUGIN 및 PLUGIN_TARGET 을 모두 지정하면 오류가 발생합니다.

특정 상황에서는 프로젝트에서 플러그인 대상 생성을 호출 이후까지 지연시키고 싶을 수 있습니다. 이러한 상황에서는 NO_CREATE_PLUGIN_TARGET 옵션을 지정할 수 있습니다. 그러면 프로젝트는 플러그인 타깃이 생성된 후 플러그인 타깃에서 qt_add_qml_plugin()을 호출할 것으로 예상됩니다. NO_CREATE_PLUGIN_TARGET 을 지정한 경우 PLUGIN_TARGET 도 함께 지정하여 플러그인 대상의 이름을 명시적으로 지정해야 합니다.

기본적으로 qt_add_qml_module() 은 CLASS_NAME 인자로 명명된 플러그인 클래스를 구현하는 .cpp 파일을 자동 생성합니다. 생성된 .cpp 파일은 컴파일할 소스 파일로 플러그인 대상에 자동으로 추가됩니다. 프로젝트에서 플러그인 클래스의 자체 구현을 제공하려는 경우 NO_GENERATE_PLUGIN_SOURCE 옵션을 제공해야 합니다. CLASS_NAME 을 제공하지 않으면 기본적으로 URI 에 점을 밑줄로 바꾼 다음 Plugin 을 추가합니다. QML 모듈에 플러그인이 없는 경우 생성된 qmldir 파일에 클래스 이름이 classname 줄로 기록됩니다. 사용자 정의 플러그인 코드가 포함된 C++ 파일을 플러그인 대상에 추가해야 합니다. 플러그인에는 단순히 지원 라이브러리를 로드하는 것 이상의 기능이 포함되어 있을 가능성이 높으므로 NO_PLUGIN_OPTIONAL도 추가해야 할 것입니다. 그렇지 않으면 QML 엔진이 백킹 라이브러리가 이미 연결되어 있음을 감지하면 플러그인 로드를 건너뛸 수 있습니다.

NO_PLUGIN 키워드를 지정하면 플러그인이 빌드되지 않습니다. 따라서 이 키워드는 플러그인 대상을 사용자 정의하는 모든 옵션, 특히 NO_GENERATE_PLUGIN_SOURCE, NO_PLUGIN_OPTIONAL, PLUGIN_TARGET, NO_CREATE_PLUGIN_TARGET 및 CLASS_NAME과 호환되지 않습니다. 모듈에 대한 플러그인을 제공하지 않는 경우 해당 모듈의 지원 라이브러리가 실행 파일에 링크된 경우에만 모듈을 완전히 사용할 수 있습니다. 일반적으로 링커가 사용하지 않는 라이브러리에 대한 링크를 유지한다고 보장하기는 어렵습니다.

NO_PLUGIN_OPTIONAL 키워드가 주어지면 플러그인은 생성된 qmldir 파일에 비옵션으로 기록됩니다. QML 모듈의 모든 기능이 해당 지원 대상에 구현되어 있고 플러그인 대상은 분리되어 있는 경우 플러그인은 옵션이 될 수 있으며, 이는 기본 및 권장 배열입니다. 자동 생성된 플러그인 소스 파일은 이 요구 사항을 충족합니다. 프로젝트에서 플러그인에 대한 자체 .cpp 구현을 제공하는 경우, 일반적으로 플러그인에는 QML 모듈에 필요한 기능이 거의 확실하게 포함되어 있으므로 NO_PLUGIN_OPTIONAL 키워드도 필요하다는 의미입니다.

자동 유형 등록

유형 등록은 AUTOMOC에서 처리하는 백업 대상의 C++ 소스에 대해 자동으로 수행됩니다. 이렇게 하면 출력 디렉터리에 typeinfo 파일이 생성되며, 파일 이름은 target 이름에 .qmltypes 이 추가됩니다. 이 파일 이름은 원하는 경우 TYPEINFO 옵션을 사용하여 변경할 수 있지만 일반적으로는 변경할 필요가 없습니다. 파일 이름은 생성된 qmldir 파일에 typeinfo 항목으로도 기록됩니다. NO_GENERATE_QMLTYPES 옵션을 사용하여 자동 유형 등록을 비활성화할 수 있으며, 이 경우 typeinfo 파일은 생성되지 않지만 프로젝트는 여전히 typeinfo 파일을 생성하여 생성된 qmldir 파일과 동일한 디렉터리에 배치합니다.

OUTPUT_DIRECTORY 플러그인 라이브러리, qmldir 및 typeinfo 파일이 생성되는 위치를 지정합니다. 이 키워드를 지정하지 않으면 기본값은 QT_QML_OUTPUT_DIRECTORY 변수 값에 추가된 대상 경로( URI)로 구성됩니다. 해당 변수가 정의되지 않은 경우 기본값은 백업 대상 유형에 따라 달라집니다. 실행 파일의 경우 ${CMAKE_CURRENT_BINARY_DIR} 에 추가된 대상 경로가 값이 되지만, 다른 대상의 경우 ${CMAKE_CURRENT_BINARY_DIR} 이 됩니다. 소스 트리의 구조가 QML 모듈 대상 경로의 구조와 일치하는 경우(적극 권장됨) QT_QML_OUTPUT_DIRECTORY가 필요하지 않은 경우가 많습니다. 대상 경로의 구조를 일치시키려면 모듈 URI의 세그먼트와 똑같이 디렉터리를 호출해야 합니다. 예를 들어 모듈 URI가 MyUpperCaseThing.mylowercasething 인 경우 이를 MyUpperCaseThing/mylowercasething/ 이라는 디렉토리에 넣어야 합니다.

OUTPUT_DIRECTORY 키워드를 지정해야 하는 경우는 드물지만, 이 키워드를 사용하는 경우 호출자는 린팅, qml 소스의 캐시 컴파일, 정적 빌드에서 플러그인 자동 가져오기, 비정적 빌드에서 가져온 QML 모듈 배포가 모두 제대로 작동하는지 확인하기 위해 IMPORT_PATH에 추가해야 할 가능성이 높습니다.

Qt Quick 디자이너 호환성

DESIGNER_SUPPORTED 는 QML 모듈이 Qt Quick 디자이너를 지원하는 경우 제공해야 합니다. 이 경우 생성된 qmldir 파일에는 designersupported 줄이 포함됩니다. 이것이 Qt Quick Designer가 플러그인을 처리하는 방식에 어떤 영향을 미치는지는 모듈 정의 qmldir 파일을 참조하세요.

모듈 버전 동기화 유지

FOLLOW_FOREIGN_VERSIONING 키워드는 다른 QML 모듈에 있는 자체 C++로 정의된 QML 유형의 기본 유형과 관련이 있습니다. 일반적으로 모듈의 버전 관리 체계는 기본 유형을 제공하는 모듈의 버전 관리 체계와 일치하지 않습니다. 따라서 기본적으로 기본 유형의 모든 개정판은 모듈을 가져올 때 사용할 수 있습니다. FOLLOW_FOREIGN_VERSIONING 을 지정하면 기본 유형과 해당 속성에 첨부된 버전 정보가 존중됩니다. 따라서 import MyModule 2.8 은 MyModule 이외의 모든 기본 유형의 버전 2.8 까지의 버전 프로퍼티만 사용할 수 있습니다. 이 기능은 주로 모듈 버전을 기준이 되는 다른 모듈과 동기화 상태를 유지하려는 경우에 유용합니다. 이 경우 사용자 정의 유형이 가져오는 것보다 더 큰 모듈의 기본 유형 버전에 있는 프로퍼티를 노출하지 않도록 할 수 있습니다.

생성된 코드의 C++ 네임스페이스

네임스페이스에 NAMESPACE 키워드를 지정하면 플러그인 및 등록 코드가 이 이름의 C++ 네임스페이스로 생성됩니다.

qmlimportscanner 및 NO_IMPORT_SCAN

정적 Qt 빌드의 경우, 설정 시 qmlimportscanner 이 실행되어 QML 모듈의 .qml 파일을 스캔하고 사용하는 QML 임포트를 식별합니다( qt_import_qml_plugins() 참조). 정적이 아닌 Qt 빌드의 경우, 대상이 실행 파일인 경우 빌드 시점에 유사한 검사를 수행하여 배포 스크립트에 필요한 정보를 제공합니다( qt_deploy_qml_imports() 참조). NO_IMPORT_SCAN 옵션을 제공하여 두 검사 모두 비활성화할 수 있습니다. 이렇게 하면 프로젝트가 정적 빌드에 필요한 모든 플러그인이 인스턴스화되고 링크되었는지 확인하는 책임을 맡게 됩니다. 정적이 아닌 빌드의 경우 프로젝트는 실행 대상에서 사용하는 모든 QML 모듈을 수동으로 작업하고 배포해야 합니다.

qmltc의 인수

ENABLE_TYPE_COMPILER 를 사용하여 .qml 파일을 C++ 소스 코드로 컴파일할 수 있습니다. 소스 속성이 QT_QML_SKIP_TYPE_COMPILER 인 파일은 C++로 컴파일되지 않습니다.

TYPE_COMPILER_NAMESPACE 인수를 사용하면 qmltc가 코드를 생성하는 네임스페이스를 재정의할 수 있습니다. 기본적으로 생성된 코드의 네임스페이스는 URI에 표시된 대로 모듈 계층 구조를 따릅니다(예: URI가 MyModule 인 모듈의 경우 MyModule, URI가 com::example::Module 인 모듈의 경우 com.example.MyModule). TYPE_COMPILER_NAMESPACE 옵션을 지정하면 생성된 코드를 사용자 정의 네임스페이스에 대신 넣을 수 있으며, 여기서 다른 하위 네임스페이스는 "::"로 구분해야 합니다(예: MyNamespace 안에 있는 네임스페이스 MySubnamespace의 경우 "MyNamespace::MySubnamespace"). "::" 외에도 C++ 네임스페이스 명명 규칙이 적용됩니다.

QMLTC_QMLTC_EXPORT_DIRECTIVE qmltc에서 생성된 클래스를 qml 라이브러리에서 내보내야 하는 경우 QMLTC_EXPORT_FILE_NAME 와 함께 사용해야 합니다. 기본적으로 qmltc에서 생성된 클래스는 해당 라이브러리에서 내보내지 않습니다. 현재 라이브러리의 내보내기 매크로를 정의하는 헤더는 QMLTC_EXPORT_FILE_NAME 에 선택적 인수로 지정할 수 있으며 내보내기 매크로 이름은 QMLTC_QMLTC_EXPORT_DIRECTIVE 에 인수로 지정해야 합니다. 내보내기 매크로의 헤더가 이미 기본 클래스에 간접적으로 포함되어 있는 경우와 같이 추가 포함이 필요하지 않거나 원하지 않는 경우에는 QMLTC_EXPORT_FILE_NAME 옵션을 생략할 수 있습니다.