Qt 리소스 시스템

Qt 리소스 시스템은 애플리케이션에서 리소스 파일을 제공하기 위한 플랫폼 독립적인 메커니즘입니다. 애플리케이션에 항상 특정 파일 세트(예: 아이콘, 번역 파일, 이미지)가 필요하고 이러한 리소스를 패키징하고 찾기 위해 시스템별 수단을 사용하고 싶지 않은 경우 이 시스템을 사용합니다.

가장 일반적으로 리소스 파일은 애플리케이션 실행 파일에 포함되거나 애플리케이션 실행 파일에 의해 로드되는 라이브러리 및 플러그인에 포함됩니다. 또는 리소스 파일을 외부 리소스 파일에 저장할 수도 있습니다.

리소스 시스템은 Qt의 rcc 리소스 컴파일러, 빌드 시스템, Qt 런타임 API 간의 긴밀한 협력을 기반으로 합니다.

Qt Resource Compiler (rcc)

Resource Compiler (rcc ) 명령줄 도구는 리소스 파일을 읽고 C++ 또는 Python 소스 파일 또는 .rcc 파일을 생성합니다.

파일 목록과 관련 메타데이터는 Qt 리소스 컬렉션 파일 형태로 rcc 으로 전달됩니다.

기본적으로 rcc는 실행 파일 또는 라이브러리의 일부로 컴파일되는 C++ 소스 코드를 생성합니다. -g python 옵션은 대신 Python 소스 코드를 생성합니다. -binary 옵션은 규칙에 따라 .rcc 파일에 저장되며 런타임에 로드할 수 있는 바이너리 아카이브를 생성합니다.

Qt 리소스 컬렉션 파일(.qrc)

.qrc 파일은 런타임 리소스로 포함할 로컬 파일을 열거하는 XML 문서입니다. rcc 에 대한 입력 역할을 합니다.

다음은 .qrc 파일의 예입니다:

<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>

XML의 각 <file> 요소는 애플리케이션의 소스 트리에 있는 파일을 식별합니다. 경로는 .qrc 파일이 포함된 디렉터리를 기준으로 확인됩니다.

경로는 기본적으로 런타임에 파일의 콘텐츠를 식별하는 데도 사용됩니다. 즉, titlebarLeft.png 파일은 리소스 시스템에서 :/res/titlebarLeft.png 또는 qrc:/res/titlebarLeft.png 로 사용할 수 있습니다. 이 기본 런타임 이름을 재정의하려면 접두사 및 별칭을 참조하세요.

Qt Creator, Qt Design Studio, Qt Widgets 디자이너 및 Qt Visual Studio Tools 를 사용하면 편리한 사용자 인터페이스를 통해 .qrc 파일을 생성, 검사 및 편집할 수 있습니다. Qt Widgets Designer를 제외하고 Qt 리소스 시스템을 사용하는 프로젝트를 위한 마법사도 제공합니다.

빌드 시스템 통합

rcc 리소스 파일의 처리는 일반적으로 애플리케이션을 빌드할 때 수행됩니다. CMake 및 qmake를 비롯한 여러 빌드 도구가 이를 지원합니다.

CMake

CMAKE_AUTORCC 가 활성화된 경우 실행 파일이나 라이브러리에 .qrc 파일을 소스로 추가하기만 하면 됩니다. 그러면 참조된 리소스 파일이 바이너리에 임베드됩니다:

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

AUTORCC에 대한 자세한 내용은 CMake의 AUTORCC 설명서를 참조하세요.

AUTORCC의 대안으로 리소스 생성을 보다 세밀하게 제어할 수 있는 Qt6Core의 CMake 함수 qt_add_resources를 사용할 수 있습니다. 예를 들어 .qrc 파일을 먼저 작성하지 않고 프로젝트 파일에서 직접 리소스의 내용을 지정할 수 있습니다:

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

마지막으로 qt_add_qml_module을 사용하면 Qt Quick 리소스를 애플리케이션의 리소스 시스템에 임베드할 수 있습니다. 이 함수는 Qt6 CMake 패키지의 Qml 구성 요소에 정의되어 있습니다.

qmake

qmake는 RESOURCES 변수를 사용하여 리소스를 처리하는 기능을 지원합니다. 변수에 .qrc 파일 경로를 추가하면 나열된 리소스 파일이 생성된 라이브러리 또는 실행 파일에 포함됩니다:

RESOURCES = application.qrc

이렇게 하면 다음과 같이 주소 지정이 가능한 여러 개의 .png 파일로 구성된 리소스가 생성됩니다: ":/res/titlebarLeft.png".

리소스에 포함하려는 파일의 디렉토리 레이아웃이 애플리케이션의 예상과 일치하지 않는 경우 resources.base 을 지정할 수 있습니다. base 은 파일 별칭의 루트 지점을 나타내는 경로 접두사입니다. 위의 예에서 resources.base 가 "res" 로 설정된 경우 titlebarLeft.png 는 ":/titlebarLeft.png" 로 주소 지정할 수 있습니다.

런타임 API

파일 반복과 읽기를 처리하는 Qt API는 Qt 리소스 시스템을 기본적으로 지원합니다. QFile 와 QDir 에는 로컬 파일 경로 대신 리소스 경로를 전달할 수 있으며, QIcon, QImage, QPixmap 생성자에도 전달할 수 있습니다:

    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

: 접두사는 "/images/cut.png"가 Qt 리소스 시스템에서 로드되어야 함을 명시합니다.

QUrl 을 통해 Qt 리소스 시스템을 참조할 수도 있습니다. 이 경우 qrc 스키마를 사용합니다:

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

고급 주제

접두사

.qrc 파일은 <file> 요소에 지정된 각 로컬 파일 이름에 접두사를 추가하여 리소스 시스템 내에서 파일을 알릴 수 있는 이름을 설정할 수 있습니다.

접두사를 사용하면 서로 다른 라이브러리 또는 플러그인에서 서로 다른 .qrc 파일을 통해 추가된 리소스 파일 간의 충돌을 방지하여 리소스를 구조화할 수 있습니다.

별칭

런타임에 다른 경로로 리소스 파일을 사용할 수 있도록 하는 것이 편리한 경우가 있습니다. .qrc 파일은 alias 어트리뷰트를 설정하여 이를 허용합니다:

<file alias="cut-img.png">images/cut.png</file>

그러면 해당 파일은 애플리케이션에서 :/cut-img.png 또는 qrc:/cut-img.png 으로만 액세스할 수 있습니다.

파일 내용 삭제하기

리소스 파일 시스템에 파일 노드를 추가하고 싶지만 실제로 파일 내용을 추가하고 싶지 않은 경우가 있습니다. .qrc 파일은 empty 속성을 true 로 설정하여 이를 허용합니다.

<file empty="true">Button.qml</file>

그러면 애플리케이션에서 결과 파일에 계속 액세스할 수 있지만 그 내용은 비어 있습니다.

이 방법은 애플리케이션 바이너리에서 QML 소스 코드를 제거할 때 유용합니다.

언어 선택기

번역 파일이나 아이콘과 같은 일부 리소스는 사용자의 로캘에 따라 변경해야 합니다. 리소스 컬렉션 파일은 qresource 태그에 lang 속성을 추가하여 적절한 로캘 문자열을 지정함으로써 이를 지원합니다. 예를 들어

<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

사용자의 로캘이 프랑스어인 경우(즉, QLocale::system().language()가 프랑스어인 경우) :/cut.jpg 또는 qrc:/cut.jpg 는 cut_fr.jpg 이미지에 대한 참조가 됩니다. 다른 로캘의 경우 cut.jpg 이 사용됩니다.

로캘 문자열에 사용할 형식에 대한 설명은 QLocale 문서를 참조하세요.

로캘별 리소스를 선택하는 추가 메커니즘은 QFileSelector 을 참조하세요.

대용량 파일 임베드하기

기본적으로 rcc 리소스 파일은 C++ 배열 형태로 실행 파일에 임베드됩니다. 이는 특히 대용량 리소스의 경우 문제가 될 수 있습니다.

컴파일러가 너무 오래 걸리거나 메모리 오버플로로 인해 실패하는 경우, 리소스를 2단계 프로세스의 일부로 임베드하는 특수 모드를 선택할 수 있습니다. C++ 컴파일러는 대상 실행 파일 또는 라이브러리에서 리소스를 위한 충분한 공간만 예약합니다. 리소스 파일의 콘텐츠와 메타데이터의 실제 임베딩은 컴파일 및 링크 단계 이후에 또 다른 rcc 호출을 통해 수행됩니다.

CMake의 경우 qt_add_big_resources 함수를 사용해야 합니다.

외부 리소스 파일

리소스 파일을 바이너리에 임베드하는 대신 별도의 .rcc 파일에 저장하는 방법도 있습니다. rcc 에서는 -binary 옵션을 사용하여 이를 허용합니다. 그런 다음 이러한 .rcc 파일은 런타임에 QResource 을 사용하여 로드해야 합니다.

예를 들어 .qrc 파일에 지정된 리소스 데이터 집합은 다음과 같은 방식으로 컴파일할 수 있습니다:

rcc -binary myresource.qrc -o myresource.rcc

애플리케이션에서 이 리소스는 다음과 같은 코드로 등록됩니다:

QResource::registerResource("/path/to/myresource.rcc");

CMake를 사용하는 경우, qt_add_binary_resources 함수를 사용하여 위의 rcc 호출을 예약할 수 있습니다:

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Qt for Python 애플리케이션의 리소스

리소스 수집 파일은 Resource Compiler rcc를 사용하여 Python 모듈로 변환됩니다:

rcc -g python mainwindow.qrc > mainwindow_rc.py

그런 다음 애플리케이션에서 모듈을 가져올 수 있습니다:

import mainwindow_rc.py

압축

rcc 은 최종 바이너리에서 디스크 공간 사용을 최적화하기 위해 콘텐츠 압축을 시도합니다. 기본적으로 휴리스틱 검사를 수행하여 압축할 가치가 있는지 여부를 결정하고 충분히 압축하지 못하면 콘텐츠를 압축하지 않은 상태로 저장합니다. 임계값을 제어하려면 -threshold 옵션을 사용하여 파일을 압축된 형태로 저장하기 위해 확보해야 하는 원본 파일 크기의 비율을 rcc 에 알려주면 됩니다.

rcc -threshold 25 myresources.qrc

기본값은 "70"으로, 압축된 파일은 원본보다 70% 작아야 함을 나타냅니다(원본 파일 크기의 30% 이하).

원하는 경우 압축을 해제할 수 있습니다. 리소스에 이미 압축된 형식(예: .png 파일)이 포함되어 있고 빌드 시 압축할 수 없는지 확인하기 위해 CPU 비용을 발생시키고 싶지 않은 경우에 유용할 수 있습니다. 또 다른 이유는 디스크 사용량이 문제가 되지 않고 애플리케이션이 런타임에 콘텐츠를 깨끗한 메모리 페이지로 유지하는 것을 선호하는 경우입니다. 이 경우 -no-compress 명령줄 인수를 지정하면 됩니다.

rcc -no-compress myresources.qrc

rcc 또한 압축 수준과 압축 알고리즘을 일부 제어할 수 있습니다:

rcc -compress 2 -compress-algo zlib myresources.qrc

.qrc file 태그의 속성으로 compress, threshold 을 사용할 수도 있습니다. 알고리즘을 선택하려면 compression-algorithm 속성을 설정하세요.

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

위는 압축 레벨 1의 zstd 알고리즘을 선택합니다.

rcc 다음과 같은 압축 알고리즘과 압축 수준을 지원합니다:

• best아래 알고리즘 중 가장 좋은 알고리즘을 가장 높은 압축 수준에서 사용하여 컴파일 시 많은 CPU 시간을 사용하는 대신 압축을 가장 많이 달성합니다. 이 값은 rcc 에서 지원하는 알고리즘에 관계없이 파일이 가장 압축되어야 함을 나타내는 데 XML 파일에서 유용합니다.
• zstdZstandard 라이브러리를 사용하여 콘텐츠를 압축합니다. 유효한 압축 수준 범위는 1에서 19까지이며, 1은 최소 압축(CPU 시간 최소화), 19는 최대 압축(CPU 시간 최대)입니다. 기본 수준은 14입니다. 특수 값 0은 zstd 라이브러리가 구현에서 정의한 기본값을 선택하도록 지시합니다.
• zlibzlib 라이브러리를 사용하여 콘텐츠를 압축합니다. 유효한 압축 수준은 1에서 9까지이며, 1은 최소 압축(최소 CPU 시간), 9는 최대 압축(최대 CPU 시간)을 적용합니다. 특수 값 0은 "압축 없음"을 의미하므로 사용해서는 안 됩니다. 기본값은 구현에 따라 정의되지만 일반적으로 레벨 6입니다.
• none: 압축하지 않음. 이는 -no-compress 옵션과 동일합니다.

Zstandard와 zlib에 대한 지원은 선택 사항입니다. 컴파일 시 지정된 라이브러리가 감지되지 않은 경우 해당 라이브러리에 대해 -compress-algo 을 전달하려고 하면 오류가 발생합니다. 기본 압축 알고리즘은 활성화된 경우 zstd, 그렇지 않은 경우 zlib 입니다.

임베디드 리소스의 명시적 로드 및 언로드

C++ 실행 파일이나 라이브러리 코드에 내장된 리소스는 내부 전역 변수의 생성자에서 Qt 리소스 시스템에 자동으로 등록됩니다. 전역 변수는 main() 실행 전에 초기화되므로 프로그램이 실행되기 시작하면 리소스를 사용할 수 있습니다.

정적 라이브러리에 리소스를 임베드할 때 C++ 링커는 리소스를 등록하는 정적 변수를 제거할 수 있습니다. 따라서 정적 라이브러리에 리소스를 임베드하는 경우 .qrc 파일의 기본 이름으로 Q_INIT_RESOURCE()를 호출하여 리소스를 명시적으로 등록해야 합니다. 예를 들어

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    ...
}

플러그인을 언로드할 때와 같이 애플리케이션에서 등록된 리소스를 명시적으로 제거할 수도 있습니다. 이를 위해 Q_CLEANUP_RESOURCE()를 사용합니다.

참고: rcc에서 생성된 리소스 초기화기는 전역 네임스페이스에서 선언되므로 Q_INIT_RESOURCE() 및 Q_CLEANUP_RESOURCE()에 대한 호출은 네임스페이스 외부에서 수행해야 합니다.