Clazy 검사를 활용한 C++ 애플리케이션의 Qt 6 포팅

Qt 5에서 Qt 6으로 애플리케이션을 이식하는 데 도움을 드리기 위해 Clazy 프레임워크 내에 몇 가지 검사 기능과 수정 사항을 구현했습니다. 개발자의 설명에 따르면, “Clazy는 clang이 Qt의 의미론을 이해할 수 있도록 해주는 컴파일러 플러그인”입니다. Clazy(https://invent.kde.org/sdk/clazy)를 다운로드하고, Qt 6으로의 이전을 더욱 원활하게 진행하기 위해 아래 내용을 읽어보세요.

Clazy 검사는 컴파일 시 플러그인으로 실행하거나, clazy-standalone 를 사용하여 JSON 컴파일 데이터베이스를 통해 실행할 수 있습니다. 수정 사항은 나중에 clang-apply-replacements 를 사용하여 적용됩니다.

Qt 6 이식에 특화된 Clazy 검사

다음 체크 항목들은 Qt 5에서 Qt 6으로의 이식을 용이하게 하기 위해 마련되었습니다.

• qt6-deprecated-api-fixes
• qt6-header-fixes
• qt6-qhash-signature
• qt6-fwd-fixes
• missing-qobject-macro

이 검사들은 Qt 5를 대상으로 실행해야 합니다. 수정된 코드는 Qt 6에서만 컴파일될 것입니다. 이러한 이유로 앞서 언급한 검사들은 한 번에 모두 실행해야 합니다. Clazy는 수정 사항을 적용할 때 충돌을 피하기 위해 한 번에 하나의 테스트만 실행할 것을 권장하지만, 이러한 검사들을 플러그인으로 실행할 때는 이 방법이 불가능합니다.

Clazy 검사 적용 방법

Clazy와 함께 프로젝트를 설정하고, 검사를 선택 및 적용하는 방법은 다음 링크에서 자세히 확인할 수 있습니다: https://invent.kde.org/sdk/clazy#setting-up-your-project-to-build-with-clazy.

플러그인이 아닌 JSON 컴파일 데이터베이스를 통해 검사를 실행하려면 clazy-standalone 를 사용해야 합니다. 자세한 지침은 https://invent.kde.org/sdk/clazy#clazy-standalone-and-json-database-support를 참조하십시오.

간단히 말해, 최신 버전의 Clazy가 설치되어 있다고 가정할 때, 플러그인으로 검사를 실행하기 위해 수행해야 할 작업은 아래와 같습니다.

Clazy와 함께 프로젝트가 실행되도록 설정하십시오.

qmake를 사용하는 경우

사용 중인 OS에 맞게 qmake 명령어에 다음 줄을 추가하십시오:

-spec linux-clang QMAKE_CXX="clazy"
-spec macx-clang QMAKE_CXX="clazy"

MSVC가 설치된 Windows의 경우 QMAKE_CXX="clazy-cl.bat" 를 추가하십시오.

qmake를 실행합니다.

CMake를 사용하는 경우

cmake 명령어에 -DCMAKE_CXX_COMPILER=clazy 를 추가하십시오.

cmake를 실행하십시오.

다음 검사 항목을 선택하십시오:

export CLAZY_CHECKS="qt6-deprecated-api-fixes,qt6-header-fixes,
qt6-qhash-signature,qt6-qlatin1stringchar-to-u,qt6-fwd-fixes,missing-qobject-macro"

fixits를 활성화합니다:

export CLAZY_EXPORT_FIXES=ON

Clazy가 무시할 디렉터리를 설정하십시오:

export CLAZY_IGNORE_DIRS=.*lib_dir.*

이렇게 하면 라이브러리 파일에서 Clazy 검사가 실행되지 않습니다. 라이브러리 경로가 -isystem 및 -framework 대신 -I 및 -F 로 포함되어 있는 경우 이 설정이 필요합니다. 또한, 검사를 유발하는 헤더 파일이 포함된 라이브러리 파일에 있는 경우 qt-header-fixes 검사에서 발생하는 경고를 방지하기 위해서도 이 설정이 필요합니다.

코드를 컴파일하십시오.

컴파일 과정에서 소스 파일 옆에 .yaml 파일이 생성됩니다.

수정 사항을 적용하려면 다음 명령을 실행하십시오:

clang-apply-replacements <path_to_yaml_files>

이렇게 하면 소스 파일이 수정되므로, 코드를 백업해 두는 것이 좋습니다.

fixits 간에 충돌이 있는 경우, 알림이 표시되며 어떤 파일도 변경되지 않습니다.

모든 포팅 작업이 자동 수정 기능으로 처리되는 것은 아닙니다. 컴파일 중 표시되는 경고 메시지를 주의 깊게 확인하여 수동으로 변경해야 할 코드를 파악하십시오.

Clazy 검사를 적용하는 방법 Qt Creator

Qt Creator 내에서 Clazy 검사를 사용하려면 ‘ Tools ’ > ‘ Options ’ > ‘ Analyzer ’을 선택하십시오(또는 Qt Creator macOS에서는 > Preferences > Analyzer 을 선택하면 됩니다).

사용자 정의 구성을 생성하고, Qt Creator 버전 4.14.1 이상에서 Level 2 및 Manual Level 섹션에 있는 포팅 전용 Clazy 검사를 선택해야 합니다. qt6 필터를 사용하면 대부분의 검사를 찾을 수 있습니다. 위에서 제시한 목록에 포함된 검사만 선택하도록 주의하십시오.

검사를 실행하려면 ‘ Analyze ’ > ‘ Clang-Tidy and Clazy ’을 선택하십시오.

Clazy 검사 구성 및 실행에 대한 자세한 내용은 Qt Creator: Clang Tools를 참조하십시오.

주의 사항

Qt Creator 에서는 수정 제안 간의 충돌에 대해 경고가 표시되지 않습니다. 같은 줄에 두 개 이상의 수정 제안이 있는 경우, 수정 제안을 적용할 때 주의하십시오.

fixit이 적용된 후에는 새로운 코드가 Qt 6에서만 컴파일되므로, 검사를 다시 실행하면 실패하게 됩니다.