QT_TARGET_QML_SOURCES

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

개요

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 을 통해 상태 비저장 라이브러리로 선언된 파일의 경우 이 옵션을 고려해야 합니다. qmldir 파일에 포함하면 해당 파일이 속한 모듈을 명시적 또는 암시적으로 임포트하는 모든 QML 문서의 범위에서 해당 파일이 다시 평가됩니다.

기본적으로 qmldir 파일을 생성할 때 유형을 제공하는 각 .qml 파일에 대해 단일 유형 항목이 생성됩니다. 이 파일에는 버전 번호 X.0 ( X )가 부여되며, 여기서 은 QML 모듈의 주 버전입니다. QML 모듈에 PAST_MAJOR_VERSIONS 설정이 있는 경우 해당 파일에도 동일한 패턴이 적용되어 각 과거 주요 버전 X 에 대해 X.0 이 추가됩니다. 파일에 다른 버전 집합에 대한 유형 항목을 대신 제공해야 하는 경우(예: .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를 활성화하는 것이 더 나은 옵션인 경우가 많습니다. 이러한 수동 설정이 여전히 필요한 경우에는 NO_GENERATE_EXTRA_QMLDIRS 을 qt_add_qml_module 으로 전달하는 것이 좋습니다. 추가 qmldir은 리소스 파일 앨리어싱을 고려하지 않기 때문입니다.

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 {}