qmllint

qmllint는 Qt에 포함된 도구로, QML 파일의 구문적 유효성을 검증합니다. 사용 편의성을 위해 qmllint를 빌드 시스템에 통합할 수 있습니다. 또한 일부 QML 안티패턴에 대해서도 경고를 표시합니다. 특정 경고 유형을 비활성화하는 방법은 qmllint 경고 구성 항목을 참조하십시오.

기본적으로 일부 문제는 경고로 표시됩니다. --max-warnings 에서 설정할 수 있는 제한 개수보다 경고가 많을 경우, 종료 코드는 0이 아닌 값이 됩니다. 그러나 사소한 문제(예: 사용되지 않은 임포트)는 기본적으로 정보성 메시지로만 표시되며, 종료 코드에는 절대 영향을 미치지 않습니다. qmllint는 다양한 설정이 가능하며 , 경고를 비활성화하거나 경고 처리 방식을 변경할 수 있습니다.

qmllint는 다음 사항에 대해 경고를 표시합니다:

• 속성에 대한 무제한 접근
• 일치하는 신호가 없는 신호 핸들러 사용
• QML에서 with 문 사용
• QML 코드 컴파일과 관련된 문제
• 사용되지 않은 임포트
• 사용 중단된 컴포넌트 및 속성
• 그 외 다양한 사항

qmllint 경고 및 오류를 수정하는 방법은 ‘QML Lint 경고 및 오류’를 참조하십시오.

사용 가능한 모든 명령줄 옵션에 대한 개요와 설명을 보려면 qmllint --help 을 실행하십시오.

컴파일러 경고

qmllint는 qmlsc로 컴파일할 수 없는 코드에 대해 경고를 표시할 수 있습니다.

이러한 경고는 기본적으로 활성화되어 있지 않습니다. 이를 활성화하려면 qmllint가 컴파일러 경고 범주를 사용하도록 구성하십시오.

CMake에서 qmllint 사용하기

QML 모듈을 생성하기 위해 qt_add_qml_module() CMake API를 사용하는 프로젝트의 경우, all_qmllint 와 같은 편의 타깃이 자동으로 생성됩니다. 이 타깃은 특정 모듈이나 프로젝트의 모든 QML 파일에 대해 qmllint를 실행합니다.

수정 제안 사항 자동 적용

qmllint에서 출력된 경고를 해결하려면 상당한 수작업 편집 및 검증 작업이 필요할 수 있습니다. qmllint가 출력하는 일부 경고에는 해당 경고를 자동으로 해결하도록 트리거할 수 있는 수정 제안이 함께 제공됩니다. 이러한 수정 기능을 트리거하려면 다음을 수행할 수 있습니다.

• qmllint에 ` --fix ` 옵션을 전달합니다.
• IDE에서 수정 제안을 활성화합니다.

프로젝트 전체에 걸쳐 모든 수정 제안을 한 번에 적용하는 것은 변경 범위가 너무 클 수 있습니다. 따라서 작업을 관리하기 쉬운 부분으로 나누는 것이 좋습니다. 파일의 일부만 린팅하거나 특정 범주만 실행함으로써 작업을 분할할 수 있습니다.

qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>

이렇게 하면 ` --only-explicit-categories ` 및 ` --ignore-settings`을 사용하여 다른 모든 경고 범주를 비활성화함으로써, 무제한 액세스에 대해서만 사용 가능한 수정 사항을 적용하게 됩니다.

변경 사항에 대해 확신이 서지 않는 경우, --dry-run 을 사용하여 파일을 실제로 변경하지 않고도 안전하게 실행 결과를 확인할 수 있습니다.

컴포넌트 및 속성을 더 이상 사용하지 않는 것으로 표시하기

qmllint를 사용하면 속성과 컴포넌트 모두를 사용 중단으로 표시할 수 있습니다:

@Deprecated { reason: "Use NewCustomText instead" }
Text {
    @Deprecated { reason: "Use newProperty instead" }
    property int oldProperty
    property int newProperty
    Component.onCompleted: console.log(oldProperty);  // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead)
}

컴포넌트에 대한 사용 중단 경고는 해당 컴포넌트가 생성될 때마다 표시됩니다.

인라인 경고 비활성화

// qmllint disable 를 사용하여 파일 내의 경고를 언제든지 일시적으로 비활성화할 수 있습니다.

한 줄에서 경고가 발생하는 경우, 해당 줄의 끝에 xml-ph-0000@deepl.internal를 추가하여 비활성화할 수 있습니다:

Item {
    property string foo
    Item {
        property string bar: foo // qmllint disable unqualified
    }
}

또는 // qmllint disable 만 포함된 줄에 주석을 삽입하고, 해당 블록을 // qmllint enable 로 끝맺음으로써 일련의 줄에 대한 주석을 비활성화할 수도 있습니다:

Item {
    property string foo
    Item {
        // qmllint disable unqualified
        property string bar: foo
        property string bar2: foo
        // qmllint enable unqualified
    }
}

qmllint는 qmllint 로 시작하는 모든 한 줄 주석을 지시문으로 해석합니다. 따라서 경고를 활성화하거나 비활성화하려는 경우가 아니라면 주석을 이러한 방식으로 시작해서는 안 됩니다.

qmllint 경고 구성

qmllint가 출력하는 경고와 그 심각도 수준을 구성할 수 있습니다. 이 수준은 info, {warning}, error 또는 disable 일 수 있습니다. .qmllint.ini 설정 파일을 사용하거나 qmllint에 명령줄 옵션을 전달하여 경고를 사용자 정의할 수 있습니다. 명령줄 옵션은 기본값과 설정 파일보다 우선합니다.

명령줄을 통해 경고 범주의 수준을 사용자 정의하려면 해당 명령줄 옵션을 원하는 수준으로 설정하십시오.

예를 들어, 사용 중단된 기능에 대한 경고를 비활성화하려면 --deprecated=disable 옵션을 지정하여 qmllint를 호출하십시오. 또한 사용되지 않는 임포트를 오류로 처리하려면 --unused-imports=error 를 전달하십시오.

설정 파일을 수정하면 경고 설정을 보다 영구적으로 사용자 정의할 수 있습니다. 자세한 내용은 다음 섹션의 Settings 파일 관련 내용을 참조하십시오.

설정

명령줄 옵션을 전달하는 것 외에도 설정 파일을 통해 qmllint를 구성할 수 있습니다. 명령줄에서 --write-defaults 을 입력하면 설정 파일이 생성됩니다.

설정 파일의 이름은 .qmllint.ini 이며, 형식은 다음과 같습니다:

[General]
DisableDefaultImports=false
MaxWarnings=-1

[Warnings]
AccessSingletonViaObject=warning
AliasCycle=warning
AssignmentInCondition=warning
AttachedPropertyReuse=disable
BadSignalHandlerParameters=warning
Comma=warning
CompilerWarnings=disable
ComponentChildrenCount=warning
ConfusingExpressionStatement=warning
ConfusingMinuses=warning
ConfusingPluses=warning
ContextProperties=warning
Deprecated=warning
DuplicateEnumEntries=warning
DuplicateImport=warning
DuplicateInlineComponent=warning
DuplicatePropertyBinding=warning
DuplicatedName=warning
EnumEntryMatchesEnum=warning
EnumsAreNotTypes=warning
EqualityTypeCoercion=warning
Eval=warning
FunctionUsedBeforeDeclaration=disable
ImportFailure=warning
IncompatibleType=warning
InheritanceCycle=warning
InvalidLintDirective=warning
LintPluginWarnings=disable
LiteralConstructor=warning
MissingEnumEntry=warning
MissingProperty=warning
MissingType=warning
MultilineStrings=info
NonListProperty=warning
NonRootEnum=warning
PreferNonVarProperties=warning
PrefixedImportType=warning
PropertyAliasCycles=warning
QtDesignStudio.FunctionsNotSupportedInQmlUi=warning
QtDesignStudio.ImperativeCodeNotEditableInVisualDesigner=warning
QtDesignStudio.InvalidIdeInVisualDesigner=warning
QtDesignStudio.ReferenceToParentItemNotSupportedByVisualDesigner=warning
QtDesignStudio.UnsupportedRootTypeInQmlUi=warning
QtDesignStudio.UnsupportedTypeInQmlUi=warning
Quick.Anchors=warning
Quick.AttachedPropertyReuse=disable
Quick.AttachedPropertyType=warning
Quick.Color=warning
Quick.ControlsAttachedPropertyReuse=disable
Quick.ControlsNativeCustomize=warning
Quick.LayoutsPositioning=warning
Quick.PropertyChangesParsed=warning
Quick.StateNoChildItem=warning
Quick.UnexpectedVarType=warning
ReadOnlyProperty=warning
RedundantOptionalChaining=warning
RequiredProperty=warning
RestrictedType=warning
StalePropertyRead=warning
TopLevelComponent=warning
TranslationFunctionMismatch=warning
UncreatableType=warning
UnintentionalEmptyBlock=warning
UnqualifiedAccess=warning
UnreachableCode=warning
UnresolvedAlias=warning
UnresolvedType=warning
UnterminatedCase=warning
UnusedImports=info
UseProperFunction=warning
VarUsedBeforeDeclaration=warning
Void=disable
WithStatement=warning

경고 수준은 명령줄 옵션과 마찬가지로 info, warning, error 또는 disable 로 설정할 수 있습니다.

qmllint는 린팅 대상인 qml 파일의 위치에서 설정 파일을 자동으로 검색합니다. 또한 이 파일을 찾기 위해 모든 상위 디렉터리를 검색하고, 해당 설정 파일을 자동으로 적용합니다. --ignore-settings 를 사용하여 이 동작을 비활성화할 수 있습니다. 설정 파일의 경고 수준보다 우선순위가 높은 명령줄 매개변수를 지정하여 언제든지 이러한 기본값을 재정의할 수 있습니다.

컨텍스트 속성 설정

컨텍스트 속성은 별도의 설정 파일에서 이름으로 정의하거나 무시할 수 있습니다. 컨텍스트 속성 설정을 사용하면 컨텍스트 속성 사용에 대한 비자격 액세스 경고를 보다 세밀하게 비활성화할 수 있는 반면, ` .qmllint.ini `은 모든 비자격 액세스 경고를 비활성화할 수만 있어, 컨텍스트 속성과 관련이 없는 경고까지 포함될 가능성이 있습니다.

컨텍스트 속성 설정 파일의 이름은 ` .contextProperties.ini `이며, 프로젝트의 소스 폴더 내에 위치해야 합니다. 형식은 다음과 같습니다:

[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = false

컨텍스트 속성 이름에 대한 무제한 액세스와 관련된 qmllint 경고를 비활성화하려면, disableUnqualifiedAccess 파일에 해당 컨텍스트 속성 이름을 추가하십시오. 여러 컨텍스트 속성 이름은 쉼표로 구분하십시오.

컨텍스트 속성 사용에 대한 경고를 표시하려면, warnOnUsage 파일에 해당 컨텍스트 속성 이름을 추가하십시오. 여러 컨텍스트 속성 이름은 쉼표로 구분하십시오.

qmllint의 휴리스틱을 제어하려면 disableHeuristic 을 true 또는 false 로 설정하십시오.

스크립팅

qmllint는 --json <file> 옵션을 통해 JSON을 작성하거나 출력할 수 있으며, 이 경우 유효한 JSON 형식으로 경고 메시지, 경고가 발생한 파일 및 줄 번호, 심각도 수준이 반환됩니다. 파일 대신 stdout에 출력하려면 특수 파일 이름 '-'를 사용하십시오. 이를 통해 qmllint를 pre-commit 훅이나 CI 테스트에 더 쉽게 통합할 수 있습니다.