En esta página

Creación de bibliotecas compartidas

En las siguientes secciones se enumeran algunos aspectos que deben tenerse en cuenta a la hora de crear bibliotecas compartidas.

Uso de símbolos de bibliotecas compartidas

Los símbolos —funciones, variables o clases— contenidos en bibliotecas compartidas y destinados a ser utilizados por clientes, como aplicaciones u otras bibliotecas, deben marcarse de una forma especial. Estos símbolos se denominan símbolos públicos y se exportan o se hacen visibles públicamente.

El resto de símbolos no deben ser visibles desde el exterior. En la mayoría de las plataformas, los compiladores los ocultan de forma predeterminada. En algunas plataformas, se requiere una opción especial del compilador para ocultar estos símbolos.

Al compilar una biblioteca compartida, esta debe marcarse para su exportación. Para utilizar la biblioteca compartida desde un cliente, algunas plataformas pueden requerir también una declaración de importación especial.

Dependiendo de la plataforma de destino, Qt proporciona macros especiales que contienen las definiciones necesarias:

  • Q_DECL_EXPORT deben añadirse a las declaraciones de los símbolos utilizados al compilar una biblioteca compartida.
  • Q_DECL_IMPORT deben añadirse a las declaraciones de los símbolos utilizados al compilar un cliente que utilice la biblioteca compartida.

Ahora, debemos asegurarnos de que se invoque la macro correcta, tanto si compilamos la propia biblioteca compartida como si solo compilamos el cliente que utiliza dicha biblioteca. Normalmente, esto se puede resolver añadiendo un encabezado especial.

Supongamos que queremos crear una biblioteca compartida llamada mysharedlib. Un encabezado especial para esta biblioteca, mysharedlib_global.h, tiene el siguiente aspecto:

#include <QtCore/QtGlobal>

#if defined(MYSHAREDLIB_LIBRARY)
#  define MYSHAREDLIB_EXPORT Q_DECL_EXPORT
#else
#  define MYSHAREDLIB_EXPORT Q_DECL_IMPORT
#endif

En cada archivo de cabecera de la biblioteca, especificamos lo siguiente:

#include "mysharedlib_global.h"

MYSHAREDLIB_EXPORT void foo();
class MYSHAREDLIB_EXPORT MyClass...

A continuación, debemos asegurarnos de que MYSHAREDLIB_LIBRARY esté definido para el compilador al compilar la propia biblioteca. Esto se hace en el sistema de compilación de la biblioteca. Si utilizamos CMake, ampliamos el objetivo de la biblioteca compartida:

target_compile_definitions(mysharedlib PRIVATE MYSHAREDLIB_LIBRARY)

Si utilizamos qmake, añadimos

DEFINES += MYSHAREDLIB_LIBRARY

al archivo .pro de la biblioteca compartida.

Nota: Los asistentes de bibliotecas de Qt Creator y Qt VS Tools te proporcionan un esqueleto que configura todo esto por ti.

Consideraciones sobre los archivos de cabecera

Normalmente, los clientes solo incluirán los archivos de cabecera públicos de las bibliotecas compartidas. Estas bibliotecas pueden instalarse en una ubicación diferente al implementarlas. Por lo tanto, es importante excluir otros archivos de cabecera internos que se hayan utilizado al compilar la biblioteca compartida.

Por ejemplo, la biblioteca podría proporcionar una clase que envuelva un dispositivo de hardware y contenga un identificador de dicho dispositivo, proporcionado por alguna biblioteca de terceros:

#include <footronics/device.h>

class MyDevice {
private:
    FOOTRONICS_DEVICE_HANDLE handle;
};

Se produce una situación similar con los formularios creados por Qt Widgets Designer al utilizar la agregación o la herencia múltiple:

#include "ui_widget.h"

class MyWidget : public QWidget {
private:
    Ui::MyWidget m_ui;
};

Al implementar la biblioteca, no debe haber ninguna dependencia de los encabezados internos footronics/device.h o ui_widget.h.

Esto puede evitarse utilizando el patrón «Puntero a la implementación» (Pointer to implementation ), descrito en diversos libros de programación en C++. Para las clases con semántica de valor, se recomienda utilizar ` QSharedDataPointer`.

Compatibilidad binaria

Para que los clientes que cargan una biblioteca compartida funcionen correctamente, la disposición en memoria de las clases que se utilizan debe coincidir exactamente con la disposición en memoria de la versión de la biblioteca que se utilizó para compilar el cliente. En otras palabras, la biblioteca que encuentra el cliente en tiempo de ejecución debe ser compatible binariamente con la versión utilizada en tiempo de compilación.

Esto no suele suponer un problema si el cliente es un paquete de software autónomo que incluye todas las bibliotecas que necesita.

Sin embargo, si la aplicación cliente depende de una biblioteca compartida que pertenece a un paquete de instalación diferente o al sistema operativo, entonces debemos plantearnos un esquema de versiones para las bibliotecas compartidas y decidir en qué nivel se debe mantener la compatibilidad binaria. Por ejemplo, se garantiza que las bibliotecas Qt con el mismo número de versión principal sean compatibles binariamente.

Mantener la compatibilidad binaria impone algunas restricciones a los cambios que se pueden realizar en las clases. Se puede encontrar una buena explicación en KDE - Políticas/Cuestiones de compatibilidad binaria con C++. Estas cuestiones deben tenerse en cuenta desde el inicio del diseño de la biblioteca. Recomendamos que se utilicen, siempre que sea posible, el principio de ocultación de información y la técnica del puntero a la implementación.

© 2026 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.