El sistema de recursos de Qt

El sistema de recursos Qt es un mecanismo independiente de la plataforma para enviar archivos de recursos en una aplicación. Utilízalo si tu aplicación necesita siempre un cierto conjunto de archivos (como iconos, archivos de traducción, imágenes), y no quieres utilizar medios específicos del sistema para empaquetar y localizar estos recursos.

Lo más habitual es que los archivos de recursos estén incrustados en el ejecutable de tu aplicación, o en bibliotecas y plugins que son cargados por el ejecutable de la aplicación. Alternativamente, los archivos de recursos también pueden almacenarse en un archivo de recursos externo.

El sistema de recursos se basa en una estrecha cooperación entre el compilador de recursos rcc de Qt, el sistema de compilación y la API de ejecución de Qt.

El Qt Resource Compiler (rcc)

La herramienta de línea de comandos Resource Compiler (rcc) lee archivos de recursos y genera un archivo fuente C++ o Python, o un archivo .rcc.

La lista de archivos y metadatos relacionados se pasa a rcc en forma de archivo de colección de recursos Qt.

Por defecto, rcc generará código fuente C++ que luego se compilará como parte de un ejecutable o biblioteca. La opción -g python genera código fuente Python en su lugar. La opción -binary genera un archivo binario que, por convención, se guarda en un archivo .rcc y puede cargarse en tiempo de ejecución.

Archivo de colección de recursos Qt (.qrc)

Un archivo .qrc es un documento XML que enumera los archivos locales que se incluirán como recursos en tiempo de ejecución. Sirve de entrada a rcc.

He aquí un ejemplo de archivo .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>

Cada elemento <file> del XML identifica un archivo en el árbol de fuentes de la aplicación. La ruta se resuelve en relación con el directorio que contiene el archivo .qrc.

La ruta también se utiliza por defecto para identificar el contenido del archivo en tiempo de ejecución. Es decir, el archivo copy.png estará disponible en el sistema de recursos como :/images/copy.png o qrc:/images/copy.png. Para anular este nombre predeterminado en tiempo de ejecución, consulte Prefijos y alias.

Qt Creator, Qt Design Studio, Qt Widgets Designer, y Qt Visual Studio Tools le permiten crear, inspeccionar y editar archivos .qrc a través de una cómoda interfaz de usuario. Excepto Qt Widgets Designer, también proporcionan asistentes para proyectos que utilizan el sistema de recursos Qt.

Integración del sistema de compilación

El procesamiento de archivos de recursos con rcc se realiza normalmente en el momento de compilar la aplicación. Varias herramientas de compilación tienen soporte dedicado para esto, incluyendo CMake y qmake.

CMake

Si CMAKE_AUTORCC está habilitado, puedes simplemente añadir archivos .qrc como fuentes a tu ejecutable o librería. Los archivos de recursos referenciados se incrustarán en el binario:

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

Consulte la documentación AUTORCC de CMake para más detalles sobre AUTORCC.

Una alternativa a AUTORCC es usar la función qt_add_resources de CMake de Qt6Core, que da más control sobre la creación de recursos. Por ejemplo, permite especificar el contenido del recurso directamente en el archivo del proyecto sin escribir primero un archivo .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
)

Por último, qt_add_qml_module permite incrustar recursos Qt Quick en el sistema de recursos de la aplicación. La función está definida en el componente Qml del paquete CMake Qt6.

qmake

qmake soporta el manejo de recursos con la variable RESOURCES. Si añade una ruta de archivo .qrc a la variable, los archivos de recursos listados se incrustarán en la biblioteca o ejecutable generados:

RESOURCES = application.qrc

Para aplicaciones simples, también es posible dejar que qmake genere el archivo .qrc por usted, evitando la necesidad de mantener un archivo adicional:

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

RESOURCES = resources

Esto crea un recurso de varios archivos .png, que son direccionables así: ":/images/copy.png".

Si la disposición de directorios de los archivos que desea incrustar en el recurso no coincide con las expectativas de la aplicación, puede especificar resources.base. base es un prefijo de ruta que denota el punto raíz del alias del archivo. En el ejemplo siguiente, si resources.base se establece como "images", entonces copy.png se puede direccionar como ":/copy.png".

API en tiempo de ejecución

La API de Qt que se ocupa de iterar y leer archivos tiene soporte incorporado para el Sistema de Recursos de Qt. Puede pasar una ruta de recurso en lugar de una ruta de archivo local a QFile y QDir, pero también por ejemplo a los constructores QIcon, QImage, y QPixmap:

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

El prefijo : hace explícito que "/images/cut.png" debe ser cargado desde el Sistema de Recursos Qt.

También puedes hacer referencia al sistema de recursos de Qt a través de un QUrl. Utiliza el esquema qrc en este caso:

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

Temas Avanzados

Prefijos

Un archivo .qrc puede establecer un prefijo que se añadirá a cada nombre de archivo local, dado en un elemento <file>, para obtener el nombre por el que se conocerá el archivo dentro del sistema de recursos.

Los prefijos permiten estructurar los recursos, evitando choques entre archivos de recursos añadidos a través de diferentes archivos .qrc en diferentes bibliotecas o plugins.

Alias

A veces es conveniente hacer que un archivo de recursos esté disponible en una ruta diferente en tiempo de ejecución. Los archivos .qrc permiten esto estableciendo un atributo alias:

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

El archivo es de la aplicación a continuación, sólo accesible como :/cut-img.png o qrc:/cut-img.png.

Descartar el contenido del archivo

A veces se desea añadir un nodo de archivo al sistema de archivos de recursos, pero en realidad no se desea añadir el contenido del archivo. Los archivos .qrc lo permiten estableciendo el atributo empty en true.

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

El archivo resultante sigue siendo accesible desde la aplicación, pero su contenido está vacío.

Esto resulta útil para eliminar el código fuente QML del binario de una aplicación.

Selectores de lenguaje

Algunos recursos necesitan cambiar en función de la configuración regional del usuario, como los archivos de traducción o los iconos. Los Archivos de Recopilación de Recursos soportan esto a través de un atributo lang a la etiqueta qresource, especificando una cadena de localización adecuada. Por ejemplo:

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

Si la configuración regional del usuario es francesa (es decir, QLocale::system().language() es francés), :/cut.jpg o qrc:/cut.jpg se convierten en una referencia a la imagen cut_fr.jpg. Para otras configuraciones regionales, se utiliza cut.jpg.

Consulte la documentación de QLocale para obtener una descripción del formato que debe utilizarse para las cadenas de configuración regional.

Consulte QFileSelector para conocer un mecanismo adicional para seleccionar recursos específicos de la configuración regional.

Incrustación de archivos de gran tamaño

Por defecto, rcc incrusta los archivos de recursos en los ejecutables en forma de matrices C++. Esto puede resultar problemático, especialmente en el caso de recursos de gran tamaño.

Si el compilador tarda demasiado, o incluso falla por desbordamiento de memoria, puede optar por un modo especial en el que los recursos se incrustan como parte de un proceso en dos pasos. El compilador de C++ sólo reserva espacio suficiente en el ejecutable o la biblioteca de destino para los recursos. La incrustación real del contenido y los metadatos del archivo de recursos se realiza después de la fase de compilación y enlace, mediante otra llamada a rcc.

Para qmake, esto se activa añadiendo resources_big a la variable CONFIG:

CONFIG += resources_big

Para CMake, es necesario utilizar la función qt_add_big_resources.

Archivos de recursos externos

Una alternativa a la incrustación de los archivos de recursos en el binario es almacenarlos en un archivo separado .rcc. rcc permite esto con la opción -binary. Dicho archivo .rcc debe cargarse en tiempo de ejecución con QResource.

Por ejemplo, un conjunto de datos de recursos especificados en un archivo .qrc puede compilarse de la siguiente manera:

rcc -binary myresource.qrc -o myresource.rcc

En la aplicación, este recurso se registraría con un código como éste:

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

Si usas CMake, puedes usar la función qt_add_binary_resources para programar la llamada rcc de arriba:

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

Recursos en una aplicación Qt for Python

El archivo de colección de recursos se convierte en un módulo de Python utilizando el compilador de recursos rcc:

rcc -g python mainwindow.qrc > mainwindow_rc.py

A continuación, el módulo puede importarse en la aplicación:

import mainwindow_rc.py

Compresión

rcc intenta comprimir el contenido para optimizar el uso de espacio en disco en los binarios finales. Por defecto, realizará una comprobación heurística para determinar si merece la pena comprimir y almacenará el contenido sin comprimir si no comprime lo suficiente. Para controlar el umbral, puede utilizar la opción -threshold, que indica a rcc el porcentaje del tamaño del archivo original que debe ganarse para que almacene el archivo en formato comprimido.

rcc -threshold 25 myresources.qrc

El valor por defecto es "70", lo que indica que el archivo comprimido debe ser un 70% más pequeño que el original (no más del 30% del tamaño del archivo original).

Si lo desea, puede desactivar la compresión. Esto puede ser útil si sus recursos ya contienen un formato comprimido, como los archivos .png, y no desea incurrir en el coste de CPU en el momento de la compilación para confirmar que no se puede comprimir. Otra razón es si el uso del disco no es un problema y la aplicación prefiere mantener el contenido como páginas de memoria limpias en tiempo de ejecución. Para ello, introduzca el argumento -no-compress en la línea de comandos.

rcc -no-compress myresources.qrc

rcc también le da cierto control sobre el nivel de compresión y el algoritmo de compresión, por ejemplo:

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

También es posible utilizar compress, threshold como atributos en una etiqueta .qrc file. Para seleccionar el algoritmo, establezca el atributo compression-algorithm.

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

Lo anterior seleccionará el algoritmo zstd con nivel de compresión 1.

rcc admite los siguientes algoritmos y niveles de compresión:

• best: utiliza el mejor algoritmo entre los siguientes, en su nivel de compresión más alto, para conseguir la mayor compresión a costa de utilizar mucho tiempo de CPU durante la compilación. Este valor es útil en el archivo XML para indicar que un archivo debe comprimirse al máximo, independientemente de los algoritmos que admita rcc.
• zstd: utilizan la biblioteca Zstandard para comprimir contenidos. Los niveles de compresión válidos van de 1 a 19, 1 es la menor compresión (menor tiempo de CPU) y 19 es la mayor compresión (mayor tiempo de CPU). El nivel por defecto es 14. Un valor especial de 0 indica a la biblioteca zstd que elija un valor predeterminado definido por la implementación.
• zlibEl nivel de compresión: utiliza la biblioteca zlib para comprimir los contenidos. Los niveles de compresión válidos van de 1 a 9, siendo 1 el que aplica la menor compresión (menor tiempo de CPU) y 9 el que aplica la mayor compresión (mayor tiempo de CPU). El valor especial 0 significa "sin compresión" y no debe utilizarse. El valor por defecto está definido por la implementación, pero normalmente es el nivel 6.
• none: sin compresión. Es igual que la opción -no-compress.

La compatibilidad con Zstandard y zlib es opcional. Si no se detecta una biblioteca determinada en tiempo de compilación, al intentar pasar -compress-algo para esa biblioteca se producirá un error. El algoritmo de compresión por defecto es zstd si está habilitado, zlib si no lo está.

Carga y descarga explícitas de recursos incrustados

Los recursos incrustados en el ejecutable C++ o en el código de la biblioteca se registran automáticamente en el sistema de recursos de Qt en un constructor de una variable global interna. Dado que las variables globales se inicializan antes de que se ejecute main(), los recursos están disponibles cuando el programa comienza a ejecutarse.

Cuando se incrustan recursos en bibliotecas estáticas, el enlazador de C++ puede eliminar las variables estáticas que registran los recursos. Por lo tanto, si incrusta recursos en una biblioteca estática, deberá registrarlos explícitamente llamando a Q_INIT_RESOURCE() con el nombre base del archivo .qrc. Por ejemplo:

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

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

También puedes eliminar explícitamente los recursos registrados de la aplicación, por ejemplo al descargar un plugin. Utilice Q_CLEANUP_RESOURCE() para ello.

Nota: Como los inicializadores de recursos generados por rcc son declarados en el espacio de nombres global, tus llamadas a Q_INIT_RESOURCE() y Q_CLEANUP_RESOURCE() necesitan ser hechas fuera de cualquier espacio de nombres.