QTP0004

QML 모듈 내에 QML 파일이 포함된 추가 디렉터리에는 별도의 qmldir 파일이 필요합니다.

이 정책은 Qt 6.8에서 도입되었습니다. 이 정책에 따라 빌드 시스템은 QML 모듈 내에 QML 파일이 포함된 추가 디렉터리마다 별도의 qmldir 파일을 생성합니다.

이 정책을 활성화하면 모듈에 포함된 각 QML 컴포넌트의 암시적 임포트가 모듈 자체와 동일해집니다. 즉, 모든 컴포넌트가 모듈을 명시적으로 임포트하지 않아도 서로를 인식할 수 있습니다.

이 정책의 ' OLD ' 동작은 모듈의 루트 디렉터리에 대해서만 qmldir 파일이 생성되는 것입니다.

이 정책의 ' NEW ' 동작은 모듈 내에 QML 파일이 포함된 각 디렉터리마다 별도의 qmldir 파일을 생성하는 것입니다. 생성된 각 qmldir 파일에는 암시적 임포트를 모듈의 표준 리소스 위치로 리디렉션하는 ` prefer ` 지시문이 포함되어 있습니다.

배경

QML 엔진은 항상 QML 파일이 위치한 디렉터리를 암시적으로 임포트합니다. 모듈 루트 디렉터리에 있는 파일의 경우, 이 암시적 임포트는 모듈 자체로 해결되므로 모든 동급 컴포넌트가 가시적으로 노출됩니다. 그러나 QML 파일이 하위 디렉터리에 배치되면, 암시적 임포트는 해당 하위 디렉터리로 해결됩니다. 이 경우 하위 디렉터리에 있는 컴포넌트는 명시적인 ` import ` 문을 추가하지 않으면 같은 모듈 내의 다른 컴포넌트를 인식할 수 없습니다. 이는 오류가 자주 발생하는 원인 중 하나입니다.

NEW 동작을 사용하면, 빌드 시스템은 각 하위 디렉터리에 qmldir 파일을 생성하며, 이 파일에는 모듈의 표준 리소스 위치를 가리키는 ` prefer ` 지시어가 포함됩니다. 이를 통해 모듈 내 모든 QML 파일의 암시적 임포트는 모듈 자체를 임포트하는 것과 동일해지므로, 디렉터리와 관계없이 모든 컴포넌트가 서로를 찾을 수 있습니다.

예시

QML 파일이 여러 하위 디렉터리에 분산되어 있는 모듈을 생각해 봅시다:

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Main.qml
        controls/MyButton.qml
        views/MyView.qml
)

일반적으로 views/MyView.qml 에서 controls 하위 디렉터리의 MyButton 를 사용해야 하는 경우가 많습니다. OLD 동작을 사용할 경우, 이 작업은 오류 메시지 없이 실패합니다. views/MyView.qml 는 views 하위 디렉터리를 암시적으로 임포트하므로, import MyModule 를 명시적으로 추가하지 않는 한 MyButton 를 찾을 수 없습니다.

NEW 동작을 사용할 경우, controls 및 views 하위 디렉터리 모두에 추가적인 qmldir 파일이 생성됩니다. 각 파일은 암시적 임포트를 모듈의 표준 리소스 위치로 리디렉션하므로, views/MyView.qml 은 명시적인 임포트 없이도 MyButton 및 모듈 내의 다른 모든 타입을 사용할 수 있습니다.

qt_add_qml_module() 를 호출하기 전에 프로젝트에서 이 정책을 명시적으로 설정할 수 있습니다:

qt_policy(SET QTP0004 NEW)

또는 REQUIRES 버전이 6.8 이상인 qt_standard_project_setup() 을 호출할 수도 있습니다.

정책을 명시적으로 설정하지 않으면 Qt 6.8에서 경고가 표시됩니다.