qt_add_qml_module

QML 모듈을 정의합니다.

이 명령어는 Qt 6.2에서 도입되었습니다.

이 명령은 Qt6 패키지의 Qml 구성 요소에 정의되어 있으며, 다음과 같이 불러올 수 있습니다:

find_package(Qt6 REQUIRED COMPONENTS Qml)

구문

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_GENERATE_QTCONF]                          # since Qt 6.12
    [NO_GENERATE_AOT_VALIDATION]                  # since Qt 6.12
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_RESOURCE_TARGET_PATH]
    [NO_IMPORT_SCAN]
    [DISCARD_QML_CONTENTS]
    [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 모듈 빌드하기 ”를 참조하십시오.

설명

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

개념적 개요와 일반적인 사용 예제는 “CMake를 사용하여 모든 것을 통합하기”를 참조하십시오. 사용자 정의 디렉터리 레이아웃 및 버전 관리와 같은 고급 주제에 대해서는 “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 옵션이 필요합니다.

또한 NO_PLUGIN 가 지정되지 않은 경우, STATIC QML 모듈도 정적 QML 플러그인을 생성합니다. 이러한 STATIC QML 모듈을 임포트하는 타겟은 해당 QML 플러그인에 명시적으로 링크해야 합니다.

백업 타겟이 없는 플러그인 타겟

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

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

이러한 구성 방식이 배포 측면에서 다소 간단해 보일 수 있지만, 로드 시간 성능이 더 우수할 가능성이 있으므로 가능한 경우 별도의 백킹 타깃을 사용하는 것이 바람직합니다.

QML 모듈로 실행 가능

실행 파일(executable) 타깃은 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 configure 실행 중에 백킹 타깃의 .qml 파일이 스캔되어 모듈에서 사용하는 임포트 항목을 파악하고 링크 관계를 설정합니다( NO_IMPORT_SCAN 키워드를 지정하여 이 기능을 비활성화할 수 있습니다). .qml 파일이 모듈에 추가되거나 제거되면, CMakeLists.txt 파일이 수정되었으므로 일반적으로 CMake가 자동으로 재실행되고 관련 파일이 다시 스캔됩니다. 개발 과정에서 기존 .qml 파일에 임포트나 타입이 추가되거나 제거될 수 있습니다. 이 자체만으로는 CMake가 자동으로 재실행되지 않으므로, qmldir 파일을 강제로 재생성하고 모든 링크 관계를 업데이트하려면 CMake를 명시적으로 재실행해야 합니다.

빌드 시 백킹 타깃의 C++ 소스 코드가 스캔되어 타입 정보 파일과 관련 타입을 등록하는 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 타겟도 제공됩니다.

dump_qml_context_properties 라는 전역 빌드 타깃이 자동으로 생성되며, 이 타깃은 qml 컨텍스트 속성 덤프 파일이 아직 존재하지 않을 때 qmlcontextpropertydump를 실행합니다. qmlcontextpropertydump는 qmllint가 QML 내 컨텍스트 속성 사용에 대해 경고를 표시할 수 있도록 qml 컨텍스트 속성 덤프 파일을 생성합니다.

clean_qml_context_properties 전역 빌드 타깃을 사용하면 이미 존재하는 qml 컨텍스트 속성 덤프 파일을 삭제할 수 있으며, 향후 dump_qml_context_properties 전역 빌드 타깃을 실행할 때 qml 컨텍스트 속성 덤프 파일을 재계산하는 데 사용할 수 있습니다.

QT_QMLLINT_CONTEXT_PROPERTY_DUMP 변수가 활성화된 경우, 린팅 타깃은 dump_qml_context_properties 빌드 타깃에 의존합니다.

.js 파일의 명명 규칙

컴포넌트로 참조될 JavaScript 파일 이름은 대문자로 시작해야 합니다.

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

싱글톤

QML 모듈에 싱글톤 유형을 제공하는 ` .qml ` 파일이 있는 경우, ` singleton ` 명령이 ` qmldir ` 파일에 기록되도록 하기 위해 해당 파일의 ` QT_QML_SINGLETON_TYPE ` 소스 속성을 ` TRUE`로 설정해야 합니다. 이는 ` 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 파일이 컴파일됩니다. qmltc는 자바스크립트 코드를 컴파일하지 않으므로, .js 및 .mjs 로 끝나는 파일은 무시됩니다. 또한, 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: 이 소스 파일 속성을 사용하여 qmltc가 특정 QML 파일을 무시하도록 지정하십시오.

인수

qt_add_qml_module 의 인수는 다음과 같은 범주로 분류됩니다:

필수 인수

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

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

모듈 URI에 대한 더 자세한 내용은 ‘식별된 모듈(Identified Modules )’을 참조하십시오.

버전

QML 모듈은 Major.Minor 형식의 모듈 식별자( VERSION )를 정의할 수도 있습니다. 이때 Major 와 Minor 는 모두 정수여야 합니다. .Patch 구성 요소를 추가할 수 있지만, 이는 무시됩니다. 모듈이 타입을 제공하는 이전 주요 버전 목록은 PAST_MAJOR_VERSIONS 키워드 뒤에 선택적으로 지정할 수도 있습니다(아래 참조). 버전 번호 지정에 대한 더 자세한 내용은 ‘식별된 모듈(Identified Modules )’을, 과거 주요 버전 등록에 대해서는 ‘과거 주요 버전 등록(Registering past major versions)’을, 모듈 버전 동기화에 대해서는 ‘모듈 버전 동기화 유지 ( Keeping module versions in sync)’를 참조하십시오.

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

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

SOURCES 는 백킹 타깃에 추가할 비-QML 소스 목록을 지정합니다. 이는 편의성을 위해 제공되며, 내장된 CMake 명령어 ` target_sources() `를 사용하여 소스를 백킹 타깃에 추가하는 것과 동일합니다.

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 파일이 암시적 임포트를 통해 자체 모듈을 임포트하도록 보장합니다. 이 동작은 QML 모듈에 ` NO_GENERATE_EXTRA_QMLDIRS ` 플래그를 전달하여 비활성화할 수 있습니다. ` NO_GENERATE_QMLDIR `는 ` NO_GENERATE_EXTRA_QMLDIRS`를 암시합니다.

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

RESOURCE_PREFIX 는 프로젝트의 네임스페이스를 캡슐화하기 위한 것이며, 프로젝트에서 정의하는 모든 QML 모듈에 대해 일반적으로 동일하게 사용됩니다.

그러나 대신 QTP0001 CMake 정책을 설정하는 것이 더 좋습니다. 이 정책은 QML 모듈이 QML 엔진의 기본 임포트 경로 중 하나 아래에 위치하도록 보장하는 기본 리소스 접두사를 정의합니다.

RESOURCE_PREFIX 를 설정하는 경우, QML 엔진이 QML 모듈을 찾을 수 있도록 해당 경로를 QML 엔진의 임포트 경로에 추가해야 합니다.

QTP0001이 활성화된 경우(예: qt_standard_project_setup(REQUIRES 6.5) 를 통해), 기본값은 "/qt/qml/" 이며, 그렇지 않은 경우 "/" 입니다.

컴파일된 리소스에 다양한 파일이 추가되면, 해당 파일들은 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 을 지정하면, 현재 모듈이 임포트되는 버전이 임포트할 모듈로 전달됩니다. 모듈 YourModule 에 QtQuick/auto 항목이 있고, QML 파일이 import YourModule 3.14 를 지정하는 경우, 이는 QtQuick 의 3.14 버전을 임포트하는 결과를 낳습니다. 공통된 버전 관리 체계를 따르는 관련 모듈의 경우, auto 을 사용해야 합니다.

IMPORTS 의 항목은 대상 이름 앞에 TARGET 키워드를 붙여 CMake 대상을 참조할 수도 있습니다. 이 경우 QML 모듈 URI는 대상에서 자동으로 결정됩니다. 이를 위해서는 CMake 정책 QTP0005를 활성화해야 합니다.

예를 들어, QML 모듈은 해당 모듈을 제공하는 CMake 타깃을 참조하여 다른 모듈을 가져올 수 있습니다:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    IMPORTS
        TARGET OtherQmlModule
)

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

OPTIONAL_IMPORTS 의 항목은 대상 이름 앞에 TARGET 키워드를 붙여 CMake 대상을 참조할 수도 있습니다. 이 경우 QML 모듈 URI는 대상에서 자동으로 결정됩니다. 이를 위해서는 CMake 정책 QTP0005를 활성화해야 합니다.

예를 들어:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET OptionalQmlModule
)

DEFAULT_IMPORTS 는 선택적 임포트 중 툴링이 로드해야 할 기본 항목을 지정합니다. 모듈 내의 각 OPTIONAL_IMPORTS 그룹마다 하나의 항목을 지정해야 합니다. 선택적 임포트는 런타임에야 해결되므로, qmllint와 같은 툴링은 일반적으로 어떤 선택적 임포트를 해결해야 할지 알 수 없습니다. 이를 해결하기 위해 선택적 임포트 중 하나를 기본 임포트로 지정할 수 있으며, 그러면 툴링이 이를 선택하게 됩니다. 별도의 구성 없이 런타임에 사용되는 선택적 임포트가 하나 있다면, 그것이 기본 임포트로 지정하기에 가장 적합한 후보입니다.

DEFAULT_IMPORTS 의 항목은 대상 이름 앞에 TARGET 키워드를 붙여 CMake 대상을 참조할 수도 있습니다. 이 경우 QML 모듈 URI는 대상에서 자동으로 결정됩니다. 이를 위해서는 CMake 정책 QTP0005를 적용해야 합니다.

예를 들어:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET BackendA
        TARGET BackendB
    DEFAULT_IMPORTS
        TARGET BackendA
)

DEPENDENCIES 는 이 모듈이 의존하지만 반드시 가져오지는 않는 다른 QML 모듈들의 목록을 제공합니다. 이는 일반적으로 C++ 수준에서만 존재하는 의존성에 사용되며, 예를 들어 다른 모듈에서 정의된 C++ 유형을 사용하거나 상속하는 클래스를 QML에 등록하는 모듈과 같은 경우입니다.

예를 들어, 다음과 같이 ` QQuickItem `의 서브클래스를 생성하고자 하는 경우:

class MyItem: public QQuickItem { ... };

이 경우, ` QQuickItem`을 포함하는 ` QtQuick` 모듈이 ` DEPENDENCIES ` 옵션을 통해 종속성으로 선언되어 있는지 확인해야 합니다:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQuick
)

이렇게 하지 않을 경우, 린팅 오류가 발생하거나 qmltc를 사용한 타입 컴파일 중, 혹은 qmlcachegen을 사용한 C++ 바인딩 및 함수 컴파일 중에 오류가 발생할 수 있습니다.

또 다른 예시는 다음과 같습니다:

class MyComponent : public QObject {
    Q_OBJECT
    QML_ELEMENT

    // ...

signals:
    void sigZoomAtMousePosition(const QPointF& aMousePos, double aZoomScaleFactor);
};

이 경우, QML 툴링이 QPointF 를 찾아 사용할 수 있도록 DEPENDENCIES QtQml 가 필요합니다:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQml
)

DEPENDENCIES 의 항목은 대상 이름 앞에 TARGET 키워드를 붙여 CMake 대상을 참조할 수도 있습니다. 이 경우 QML 모듈 URI와 임포트 경로는 해당 대상에서 자동으로 결정됩니다. 이를 위해서는 CMake 정책 QTP0005를 활성화해야 합니다.

예를 들어, QML 모듈은 해당 모듈을 제공하는 CMake 타깃을 참조하여 다른 모듈에 대한 종속성을 선언할 수 있습니다:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET OtherQmlModule
)

백업 타깃이 실행 파일이고 TARGET 종속성이 사용되는 경우( QTP0005 필요), qt_add_qml_module() 은 빌드 트리 내 실행 파일 옆에 qt.conf 파일을 자동으로 생성합니다. 이 파일은 QML 임포트 경로를 구성하여, 수동으로 IMPORT_PATH 항목을 추가할 필요 없이 QML 엔진이 실행 시 모듈의 종속성을 찾을 수 있도록 합니다. NO_GENERATE_QTCONF 옵션을 사용하면 이 동작이 억제되는데, 생성된 파일이 빌드 디렉터리에 이미 존재하는 qt.conf 파일과 충돌하는 경우 이 옵션이 필요할 수 있습니다. 이 옵션은 Qt 6.12에서 도입되었습니다.

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

IMPORT_PATH 을 사용하여, 이 모듈이 의존하는 다른 QML 모듈을 찾을 수 있는 검색 경로를 추가할 수 있습니다. 다른 모듈들은 검색 경로 중 하나 아래에 있는 자체 대상 경로 내에 qmldir 파일을 가지고 있어야 합니다. Qt는 IMPORT_PATH 아래에 있는 모든 파일이 신뢰할 수 있는 출처에서 온 것으로 간주합니다.

백킹 타깃이 정적 라이브러리이고 해당 정적 라이브러리가 설치될 경우, OUTPUT_TARGETS 를 지정하여 함께 설치해야 할 추가 타깃 목록을 저장할 변수를 제공해야 합니다. 이러한 추가 타깃은 qt_add_qml_module() 에 의해 내부적으로 생성되며, 리소스가 올바르게 설정되고 로드되도록 보장하기 위한 일환으로 백킹 타깃의 링크 요구 사항에 의해 참조됩니다.

타깃 및 플러그인 타깃

다음 옵션들은 플러그인 타깃이 생성되고 구성되는 방식을 제어합니다. 대부분의 모듈에서는 기본값이 적절하므로 이러한 옵션 중 어느 것도 필요하지 않습니다. 일반적인 시나리오:

• 기본값 — 생성된 소스 파일과 함께 별도의 플러그인 타깃이 자동으로 생성됩니다. 이 플러그인은 선택 사항입니다(백엔드 라이브러리가 직접 링크될 때는 로드되지 않음).
• 사용자 정의 플러그인 — NO_GENERATE_PLUGIN_SOURCE를 사용하여 자체 플러그인 클래스 구현을 제공합니다. 또한 사용자 정의 플러그인 클래스와 일치하도록 CLASS_NAME을 설정해야 합니다. 일반적으로 플러그인에 상당한 양의 코드가 포함되므로 NO_PLUGIN_OPTIONAL도 함께 설정해야 합니다.
• 플러그인 없음 — 모듈이 항상 직접 링크되고 동적으로 로드되지 않는 경우 NO_PLUGIN을 사용합니다.
• 실행 파일 대상 — 플러그인이 자동으로 생성되지 않습니다.

PLUGIN_TARGET QML 모듈과 연관된 플러그인 타깃을 지정합니다. ` PLUGIN_TARGET `는 백킹 타깃 ` target`과 동일할 수 있으며, 이 경우 별도의 백킹 타깃은 생성되지 않습니다. ` PLUGIN_TARGET `가 지정되지 않으면, 기본적으로 ` target `에 ` plugin `가 추가된 형태로 설정됩니다. 예를 들어, 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 ` 키워드도 필요합니다.

자동 유형 등록

qt_add_qml_module 여러 파일을 자동으로 생성합니다. 다음 옵션들은 생성될 내용을 제어합니다. 대부분의 경우 기본값이 적절하므로 이러한 옵션은 필요하지 않습니다.

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 키워드를 지정해야 하는 경우는 드물겠지만, 이 키워드를 사용하는 경우 호출 측에서도 IMPORT_PATH를 추가해야 할 가능성이 높습니다. 그래야 린팅, QML 소스의 캐시된 컴파일, 정적 빌드 시 플러그인의 자동 임포트, 비정적 빌드 시 임포트된 QML 모듈의 배포 등이 모두 올바르게 작동할 수 있습니다.

Qt Quick 디자이너 호환성

DESIGNER_SUPPORTED QML 모듈이 Qt Quick Designer를 지원하는 경우 호환성을 보장해야 합니다. 이 설정이 지정되면 생성된 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 빌드의 경우, configure 단계에서 ` qmlimportscanner `이 실행되어 QML 모듈의 ` .qml ` 파일을 스캔하고 해당 모듈이 사용하는 QML 임포트를 식별합니다(` qt_import_qml_plugins()` 참조). 비정적 Qt 빌드의 경우, 대상이 실행 파일인 경우 배포 스크립트에 필요한 정보를 제공하기 위해 빌드 시점에 유사한 스캔이 수행됩니다( qt_deploy_qml_imports() 참조). NO_IMPORT_SCAN 옵션을 지정하여 두 스캔 모두 비활성화할 수 있습니다. 이렇게 하면 프로젝트 측에서 정적 빌드 시 필요한 모든 플러그인이 인스턴스화되고 링크되도록 보장할 책임이 있습니다. 비정적 빌드의 경우, 프로젝트에서 실행 파일 대상에 사용되는 모든 QML 모듈을 수동으로 파악하여 배포해야 합니다.

DISCARD_QML_CONTENTS

기본적으로 QML 및 JS 소스 파일의 내용은 타깃의 리소스 시스템에 포함됩니다. DISCARD_QML_CONTENTS 를 사용하여 이러한 내용을 제거하고 바이너리 크기를 줄일 수 있습니다.

qmltc의 인수

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

TYPE_COMPILER_NAMESPACE 이 인수를 사용하면 qmltc가 코드를 생성하는 네임스페이스를 재정의할 수 있습니다. 기본적으로 생성된 코드의 네임스페이스는 URI에 표시된 모듈 계층 구조를 따릅니다. 예를 들어, URI가 MyModule 인 모듈의 경우 MyModule 가 되고, URI가 com.example.MyModule 인 모듈의 경우 com::example::Module 가 됩니다. TYPE_COMPILER_NAMESPACE 옵션을 지정하면 생성된 코드를 사용자 정의 네임스페이스에 배치할 수 있으며, 이 경우 서로 다른 하위 네임스페이스는 “::”로 구분됩니다. 예를 들어, MyNamespace 내부에 있는 MySubnamespace 네임스페이스의 경우 “MyNamespace::MySubnamespace”와 같이 표기됩니다. "::"를 제외하고는 C++ 네임스페이스 명명 규칙이 적용됩니다.

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