qt_target_qml_sources

기존 QML 모듈 타깃에 QML 파일 및 리소스를 추가합니다.

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

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

find_package(Qt6 REQUIRED COMPONENTS Qml)

구문

qt_target_qml_sources(
    target
    [QML_FILES ...]
    [RESOURCES ...]
    [PREFIX resource_path]
    [OUTPUT_TARGETS out_targets_var]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_QMLDIR_TYPES]
)

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

설명

qt_target_qml_sources() qt_add_qml_module()이 호출된 후에도 QML 모듈에 파일을 추가할 수 있게 해줍니다. 일반적으로 .qml 파일 및 리소스 세트를 qt_add_qml_module() 에 직접 전달하지만, 경우에 따라 qt_add_qml_module() 이 호출된 후에 파일을 추가하는 것이 바람직하거나 심지어 필요할 수도 있습니다. 예를 들어, ` if ` 문 표현식에 따라 조건부로 파일을 추가하거나, 특정 기준이 충족될 때만 추가되는 하위 디렉터리에서 파일을 추가하고자 할 수 있습니다. 리소스 접두사가 다르거나, 린팅 및 바이트코드 컴파일이 비활성화된 등 다른 파일들과 특성이 다른 파일 집합을 추가하고 싶을 수도 있습니다. ` qt_target_qml_sources() ` 명령어는 이러한 시나리오를 가능하게 합니다.

인수

target 는 QML 모듈의 백킹 타깃이어야 하며, QML 모듈에 별도의 백킹 타깃이 없는 경우 해당 모듈의 플러그인 타깃이어야 합니다.

QML_FILES 는 QML 모듈에 추가될 .qml, .js 및 .mjs 파일 목록입니다. 이 옵션은 바이트코드로의 자동 컴파일 및 린트 처리를 포함하여, qt_add_qml_module() 명령의 QML_FILES 옵션과 정확히 동일한 효과를 갖습니다.

NO_CACHEGEN 및 NO_LINT 옵션 역시 qt_add_qml_module()에서와 동일한 효과를 나타냅니다. 이 옵션들은 QML_FILES 로 나열된 파일들에 대해 바이트코드 컴파일 및 린트 처리를 비활성화합니다. 이러한 동작은 소스 파일 속성을 사용하여 개별 파일에 대해서만 지정할 수도 있습니다.

NO_QMLDIR_TYPES QML_FILES 가 생성된 qmldir 파일에 유형으로 추가되는 것을 방지합니다.

RESOURCES qt_add_qml_module() 명령어의 ` RESOURCES ` 옵션과 정확히 동일한 효과를 가집니다. 이 옵션은 ` target `에 일반 리소스로 추가될 파일 목록을 제공합니다. 이러한 파일은 일반적으로 QML 코드가 어떤 방식으로든 참조하는 이미지, 셰이더 등과 같은 것들입니다.

QML_FILES 또는 RESOURCES 을 통해 모듈에 추가된 파일은 qt_add_qml_module() 명령어로 추가된 경우와 동일하게 동일한 리소스 접두사와 대상 경로 아래에 배치됩니다. 이는 PREFIX 옵션을 사용하여 다른 위치를 지정함으로써 재정의할 수 있습니다. PREFIX 키워드 뒤에 오는 값은 대상 경로를 추가하지 않고 그대로 사용됩니다. 각 파일의 최종 리소스 경로는 접두사와 ` CMAKE_CURRENT_SOURCE_DIR` 아래의 파일 경로가 결합된 형태가 됩니다. QT_RESOURCE_ALIAS 소스 파일 속성을 사용하여 해당 상대 경로를 재정의할 수도 있습니다.

qt_add_qml_module(backing
    URI Example
    VERSION 1.0
    RESOURCE_PREFIX /my.company.com/imports
)

qt_target_qml_sources(backing
    QML_FILES special/First.qml
    RESOURCES icons/logo.png
)

qt_target_qml_sources(backing
    PREFIX /other.company.com/debugging
    QML_FILES Inspector.qml
)

위의 예제에서, backing 타깃의 리소스는 다음과 같은 내용을 갖게 됩니다:

• /my.company.com/imports/Example/special/First.qml
• /my.company.com/imports/Example/icons/logo.png
• /other.company.com/debugging/Inspector.qml

OUTPUT_TARGETS 이는 qt_add_qml_module()의 동일한 옵션과 유사합니다. 이 옵션을 사용하여 정적 빌드용으로 생성된 추가 타깃을 저장할 변수의 이름을 지정합니다. target 이 설치될 경우, 링크 요구 사항을 충족하기 위해 이러한 추가 타깃도 함께 설치되어야 합니다.

소스 파일 속성

여러 소스 파일 속성을 사용하여 QML 모듈 처리 과정의 다양한 단계에서 개별 .qml 파일이 처리되는 방식을 제어할 수 있습니다. 이러한 속성은 qt_target_qml_sources() 또는 qt_add_qml_module() 호출에서 지정된 상위 수준 옵션을 재정의합니다. 이 두 명령 중 하나를 사용하여 파일을 추가하기 전에 이러한 모든 속성을 설정해야 합니다.

QT_QML_SKIP_QMLLINT 소스 파일에 ` TRUE ` 속성을 설정하면 해당 파일이 자동 qmllint 처리에 포함되지 않도록 할 수 있습니다. 기본적으로 모든 ` .qml ` 파일은 대상의 린트 실행에 포함되지만, 이 옵션을 사용하여 특정 파일을 제외할 수 있습니다.

QT_QML_SKIP_CACHEGEN TRUE 로 설정하면 소스 파일이 바이트 코드로 컴파일되지 않도록 하는 유사한 기능을 수행합니다. 단, 해당 파일은 컴파일되지 않은 형태로 에 리소스로 추가된다는 점에 유의하십시오( target 컴파일된 QML 소스 캐싱 참조).

QT_QML_SKIP_QMLDIR_ENTRY 소스 파일 속성을 TRUE 로 설정하면 해당 QML 또는 JavaScript 파일이 QML 모듈의 qmldir 파일에 타입으로 추가되는 것을 방지할 수 있습니다( qmldir 및 typeinfo 파일 자동 생성 참조). 이는 일반적으로 비공개 JavaScript 파일과 같이 공개 타입을 노출하지 않는 파일에 사용됩니다. ECMAScript 모듈이 아니며 .pragma library 를 통해 무상태 라이브러리로 선언되지 않은, 이름이 대문자로 된 JavaScript 파일의 경우 이 옵션을 고려해야 합니다. 이러한 파일을 ` qmldir ` 파일에 포함하면, 해당 파일이 속한 모듈을 명시적 또는 묵시적으로 임포트하는 모든 QML 문서의 범위 내에서 파일이 재평가됩니다.

기본적으로 qmldir 파일을 생성할 때, 타입을 제공하는 각 .qml 파일에 대해 단일 타입 항목이 생성됩니다. 이 항목에는 X.0 형식의 버전 번호가 부여되며, 여기서 X 는 QML 모듈의 주요 버전입니다. QML 모듈에 PAST_MAJOR_VERSIONS 가 설정되어 있는 경우, 동일한 패턴이 해당 버전에도 적용되며, 과거 주요 버전마다 X.0 를 추가합니다( X). 대신 파일이 다른 버전 세트에 대한 타입 항목을 제공해야 하는 경우(예: .0 릴리스 이후 마이너 패치 버전에서 처음 추가된 경우), 소스 파일의 QT_QML_SOURCE_VERSIONS 속성에 해당 버전을 지정하십시오. 각 버전마다 하나의 타입 항목이 생성됩니다.

.qml 파일이 제공하는 타입이 싱글톤인 경우, 해당 파일의 ` QT_QML_SINGLETON_TYPE ` 속성을 ` TRUE`로 설정하십시오. 마찬가지로, 파일의 ` QT_QML_INTERNAL_TYPE ` 소스 속성을 ` TRUE `로 설정하여 해당 파일이 제공하는 타입이 내부 타입임을 나타낼 수 있습니다. QT_QML_SOURCE_TYPENAME 속성을 사용하여 타입 자체의 이름을 재정의할 수도 있습니다. 이 세 가지 설정은 모두 생성된 qmldir 파일 내의 해당 파일 타입 항목에 반영됩니다. 소스 속성은 싱글톤이 속한 모듈을 생성하기 전에 설정해야 합니다.

QML_FILES 또는 RESOURCES 로 나열된 모든 파일은 target 의 리소스에 추가됩니다. 리소스 내에서의 위치는 기준점과 상대 경로로 구성됩니다. 기준점은 기본적으로 QML 모듈의 리소스 접두사와 대상 경로를 연결한 형태이지만, PREFIX 인수를 사용하여 재정의할 수 있습니다. 상대 경로는 기본적으로 ` target`의 ` SOURCE_DIR ` 타깃 속성에 상대적인 파일 경로로 설정됩니다. 이 상대 경로는 소스 파일의 ` QT_RESOURCE_ALIAS ` 속성을 설정하여 재정의할 수 있습니다. 이는 일반적으로 서로 다른 디렉터리에서 파일을 수집하여 리소스 내의 공통 위치에 표시되도록 하는 데 사용됩니다. 그러나 Qt 6.8부터는 Qml 모듈의 모든 파일을 암시적 임포트에서 찾을 수 있도록 하는 것이 목표라면, QTP0004를 활성화하는 것이 더 나은 선택인 경우가 많습니다. 이러한 수동 설정이 여전히 필요한 경우에는, 추가적인 qmldirs가 리소스 파일 별칭을 고려하지 않으므로 ` qt_add_qml_module`에 ` NO_GENERATE_EXTRA_QMLDIRS `를 전달하는 것이 좋습니다.

set_source_files_properties(nested/way/down/File.qml PROPERTIES
    QT_RESOURCE_ALIAS File.qml
)
set_source_files_properties(TemplateFile.qml PROPERTIES
    QT_RESOURCE_ALIAS templates/File.qml
    QT_QML_SKIP_QMLDIR_ENTRY TRUE
    QT_QML_SKIP_QMLLINT TRUE
    QT_QML_SKIP_CACHEGEN TRUE
)
set_source_files_properties(FunnySingleton.qml PROPERTIES
    QT_QML_SINGLETON_TYPE TRUE
)
qt_add_qml_module(qt_target_qml_sources_example
    URI Example
    VERSION 2.3
    RESOURCE_PREFIX /my.company.com/imports
    NO_GENERATE_EXTRA_QMLDIRS
    QML_FILES
        nested/way/down/File.qml
        TemplateFile.qml
        FunnySingleton.qml
)

set_source_files_properties(some_old_thing.qml PROPERTIES
    QT_QML_SOURCE_VERSIONS "1.1;2.0"
    QT_QML_SOURCE_TYPENAME OldThing
)
set_source_files_properties(../../../images/button-types.png PROPERTIES
    QT_RESOURCE_ALIAS button-types.png
)
qt_target_qml_sources(qt_target_qml_sources_example
    QML_FILES some_old_thing.qml
    RESOURCES
        ../../../images/button-types.png
        doc/README.txt
)

위의 예에서, qt_target_qml_sources_example 타깃의 리소스는 다음과 같은 내용을 갖게 됩니다:

• /my.company.com/imports/Example/File.qml
• /my.company.com/imports/Example/FunnySingleton.qml
• /my.company.com/imports/Example/templates/File.qml
• /my.company.com/imports/Example/some_old_thing.qml
• /my.company.com/imports/Example/button-types.png
• /my.company.com/imports/Example/doc/README.txt

생성된 qmldir 파일에는 다음과 같은 유형 항목이 포함됩니다:

File 2.0 File.qml
singleton FunnySingleton 2.0 FunnySingleton.qml
OldThing 1.1 some_old_thing.qml
OldThing 2.0 some_old_thing.qml

pragma Singleton
import QtQml

QtObject {}