Qt 리소스 시스템

Qt 리소스 시스템은 애플리케이션에 리소스 파일을 포함시키기 위한 플랫폼 독립적인 메커니즘입니다. 애플리케이션에 항상 특정 파일 세트(아이콘, 번역 파일, 이미지 등)가 필요하고, 이러한 리소스를 패키징하고 찾는 데 시스템별 방법을 사용하고 싶지 않은 경우 이 시스템을 사용하십시오.

가장 일반적인 경우, 리소스 파일은 애플리케이션 실행 파일이나 애플리케이션 실행 파일이 로드하는 라이브러리 및 플러그인에 내장됩니다. 또는 리소스 파일을 외부 리소스 파일에 저장할 수도 있습니다.

리소스 시스템은 Qt의 rcc Resource Compiler, 빌드 시스템, 그리고 Qt 런타임 API 간의 긴밀한 협력을 기반으로 합니다.

Qt XML 리소스 컴파일러( 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 파일이 포함된 디렉터리를 기준으로 상대 경로로 해석됩니다.

이 경로는 기본적으로 런타임에 파일의 내용을 식별하는 데에도 사용됩니다. 즉, copy.png 파일은 리소스 시스템에서 :/images/copy.png 또는 qrc:/images/copy.png 로 사용할 수 있습니다. 이 기본 런타임 이름을 재정의하려면 ‘접두사 및 별칭’을 참조하십시오.

Qt Creator, Qt Design Studio, Qt Widgets Designer, Qt Extension for Visual Studio Code, 그리고 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

간단한 애플리케이션의 경우, qmake가 자동으로 ` .qrc ` 파일을 생성하도록 설정하여 별도의 파일을 관리할 필요가 없도록 할 수도 있습니다:

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

이렇게 하면 여러 개의 .png 파일로 구성된 리소스가 생성되며, 이 파일들은 ":/images/copy.png" 와 같은 방식으로 참조할 수 있습니다.

리소스에 포함하려는 파일의 디렉터리 구조가 애플리케이션의 예상과 일치하지 않는 경우, ` resources.base`을 지정할 수 있습니다. ` base `은 파일 별칭의 루트 지점을 나타내는 경로 접두사입니다. 아래 예시에서, ` resources.base `이 ` "images"`로 설정되어 있다면, ` copy.png `은 ` ":/copy.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()가 French인 경우), :/cut.jpg 또는 qrc:/cut.jpg 는 cut_fr.jpg 이미지에 대한 참조가 됩니다. 다른 로케일의 경우 cut.jpg 가 사용됩니다.

로케일 문자열에 사용할 형식에 대한 설명은 QLocale 문서를 참조하십시오.

로케일별 리소스를 선택하는 추가적인 메커니즘에 대해서는 QFileSelector 를 참조하십시오.

대용량 파일 삽입

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

컴파일러가 너무 오래 걸리거나 메모리 오버플로우로 인해 오류가 발생하는 경우, 2단계 프로세스를 통해 리소스를 삽입하는 특수 모드를 선택할 수 있습니다. C++ 컴파일러는 대상 실행 파일이나 라이브러리 내에 리소스를 수용할 수 있는 충분한 공간만 확보합니다. 리소스 파일의 내용과 메타데이터를 실제로 임베딩하는 작업은 컴파일 및 링크 단계가 끝난 후, 별도의 rcc 호출을 통해 수행됩니다.

qmake의 경우, ` CONFIG ` 변수에 ` resources_big `를 추가하여 이 기능을 활성화할 수 있습니다:

CONFIG += resources_big

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 시간을 소모하는 대가로 최대한의 압축률을 달성합니다. 이 값은 XML 파일에서 rcc 가 지원하는 알고리즘과 관계없이 파일을 최대한 압축해야 함을 나타내는 데 유용합니다.
• zstd: Zstandard 라이브러리를 사용하여 내용을 압축합니다. 유효한 압축 수준은 1부터 19까지이며, 1은 압축률이 가장 낮고(CPU 시간 최소), 19는 압축률이 가장 높습니다(CPU 시간 최대). 기본 수준은 14입니다. 0이라는 특수 값을 지정하면 zstd 라이브러리가 구현에 정의된 기본값을 선택하도록 지시합니다.
• zlib: zlib 라이브러리를 사용하여 내용을 압축합니다. 유효한 압축 수준은 1에서 9까지이며, 1은 압축률이 가장 낮고(CPU 시간 최소화), 9는 압축률이 가장 높습니다(CPU 시간 최대화). 특수 값 0은 “압축 없음”을 의미하므로 사용해서는 안 됩니다. 기본값은 구현에 따라 다르지만, 일반적으로 레벨 6입니다.
• none: 압축을 적용하지 않습니다. 이는 -no-compress 옵션과 동일합니다.

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

내장 리소스의 명시적 로딩 및 언로딩

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

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

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

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

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

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