QML 정적 분석 1 - 기본 설정

이 장에서는 qmllint 확장 플러그인의 기본 구조와 이를 qmllint와 함께 사용하는 방법을 소개합니다.

플러그인을 만들려면 먼저 QmlCompiler 모듈을 사용할 수 있도록 설정해야 합니다:

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)

그런 다음 플러그인을 생성하고 QmlCompiler 모듈에 연결합니다.

qt_add_plugin(HelloWorldPlugin)

target_sources(HelloWorldPlugin
    PRIVATE
        helloplugin.h
        helloplugin.cpp
)

target_link_libraries(HelloWorldPlugin PRIVATE Qt::QmlCompiler)

구현은 플러그인으로 Qt를 확장하는 패턴을 따릅니다: QQmlSA::LintPlugin 을 서브클래싱합니다,

class HelloWorldPlugin : public QObject, public QQmlSA::LintPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QmlLintPluginInterface_iid FILE "plugin.json")
    Q_INTERFACES(QQmlSA::LintPlugin)

public:
    void registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement) override;
};

플러그인은 몇 가지 중요한 정보가 들어있는 plugin.json 파일을 참조합니다:

{
    "name": "HelloWorld",
    "author": "Qt Example",
    "description": "Demonstrates how to write a qmllint plugin",
    "version": "1.0",
    "loggingCategories": [
        {
            "name": "hello-world",
            "settingsName": "HelloWorld",
            "description": "Used to create test messages"
        }
    ]
}

name, author, version 및 description 은 플러그인을 설명하는 메타데이터입니다.

각 플러그인에는 경고를 주제별로 그룹화하는 데 사용되는 하나 이상의 로깅 카테고리가 있을 수 있습니다. loggingCategories 는 다음과 같이 구성된 카테고리 배열을 사용합니다.

name로 구성되며, 카테고리를 식별하는 데 사용되며, qmllint의 플래그 이름으로 사용됩니다,
settingsName로 구성되며, qmllint.ini에서 카테고리를 구성하는 데 사용됩니다.
description카테고리로 태그된 경고 메시지의 종류를 설명해야 합니다.

이 예제에서는 hello-world 라는 하나의 로깅 카테고리만 있습니다. 각 카테고리에 대해 플러그인에서 LoggerWarningId 객체를 만들어야 합니다.

static constexpr QQmlSA::LoggerWarningId helloWorld { "Plugin.HelloWorld.hello-world" };

이 객체는 Plugin.<plugin name>.<category name> 형식의 문자열 리터럴로 구성합니다.

마지막으로 플러그인이 실제로 유용한 작업을 수행하려면 registerPasses 함수를 구현해야 합니다.

void HelloWorldPlugin::registerPasses(QQmlSA::PassManager *관리자, const QQmlSA::Element &rootElement) { const bool pluginIsEnabled =  manager->isCategoryEnabled(helloWorld);    qDebug() << "Hello World plugin is" << (pluginIsEnabled ? "enabled" : "disabled");
   if (!pluginIsEnabled) return; // 어차피 플러그인이 비활성화되면 등록 건너뛰기 // 여기에 나중에 패스를 등록합니다}

카테고리가 활성화되었는지 확인하고 qDebug 를 통해 상태를 나타내는 진단을 인쇄합니다. 현재 플러그인은 패스를 등록하지 않기 때문에 유용한 기능을 수행하지 않습니다. 이 작업은 이 튜토리얼의 다음 부분에서 수행됩니다.

하지만 플러그인이 올바르게 감지되는지 이미 확인할 수 있습니다. 다음 명령을 사용하여 확인합니다:

qmllint -P /path/to/the/directory/containing/the/plugin --Plugin.HelloWorld.hello-world info test.qml

-P 옵션은 지정된 폴더에서 플러그인을 찾으라고 qmllint에 지시합니다. Qt 내부 카테고리와의 충돌을 피하기 위해 플러그인 카테고리 앞에는 항상 "플러그인"이 붙고 그 뒤에 점, 플러그인 이름, 또 다른 점, 마지막으로 카테고리가 붙습니다. 명령을 실행하면 Hello World Plugin is enabled 이 출력됩니다.

QML 정적 분석 튜토리얼 QML 정적 분석 2 - 커스텀 패스

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.