Técnicas de depuración
A continuación te ofrecemos algunos consejos útiles que te ayudarán a depurar tu software basado en Qt.
Configuración de Qt para la depuración
Al configurar Qt para su instalación, es posible asegurarse de que se compile incluyendo símbolos de depuración, lo que facilita la localización de errores en aplicaciones y bibliotecas. Sin embargo, en algunas plataformas, compilar Qt en modo de depuración hará que las aplicaciones tengan un tamaño mayor del deseado.
Depuración en macOS y Xcode
Depuración con o sin marcos de trabajo
La información básica que necesitas saber sobre las bibliotecas y los marcos de trabajo de depuración se encuentra en developer.apple.com, en la Nota técnica de Apple TN2124.
Al compilar Qt, los marcos se compilan de forma predeterminada, y dentro de cada marco encontrarás tanto una versión de lanzamiento como una de depuración (por ejemplo, QtCore y QtCore_debug). Si se pasa el indicador « -no-framework » al compilar Qt, se generan dos dylibs para cada biblioteca de Qt (por ejemplo, libQtCore.4.dylib y libQtCore_debug.4.dylib).
Lo que ocurre al enlazar depende de si se utilizan marcos de trabajo o no. No vemos ninguna razón de peso para recomendar uno sobre el otro.
Con marcos de trabajo:
Dado que las bibliotecas de versión final y de depuración se encuentran dentro del marco de trabajo, la aplicación simplemente se enlaza con dicho marco. Así, al ejecutarla en el depurador, obtendrás la versión final o la versión de depuración, dependiendo de si has establecido DYLD_IMAGE_SUFFIX. Si no lo estableces, obtendrás la versión final por defecto (es decir, la que no es _debug). Si se establece DYLD_IMAGE_SUFFIX=_debug, se obtiene la versión de depuración.
Sin marcos de trabajo:
Cuando le indicas a qmake que genere un Makefile con la configuración de depuración, este se vinculará con la versión _debug de las bibliotecas y generará símbolos de depuración para la aplicación. Al ejecutar este programa en GDB, funcionará igual que al ejecutar GDB en otras plataformas, y podrás realizar un seguimiento dentro de Qt.
Opciones de línea de comandos reconocidas por Qt
Al ejecutar una aplicación Qt, puedes especificar varias opciones de línea de comandos que pueden ayudarte con la depuración. Estas son reconocidas por QApplication.
| Opción | Descripción |
|---|---|
-nograb | La aplicación nunca debe capturar the mouse ni the keyboard. Esta opción está activada por defecto cuando el programa se ejecuta en el depurador gdb bajo Linux. |
-dograb | Ignora cualquier -nograb implícito o explícito. -dograb tiene prioridad sobre -nograb incluso cuando -nograb sea el último elemento de la línea de comandos. |
Variables de entorno reconocidas por Qt
En tiempo de ejecución, una aplicación Qt reconoce muchas variables de entorno, algunas de las cuales pueden resultar útiles para la depuración:
| Variable | Descripción |
|---|---|
QT_DEBUG_PLUGINS | Establecer en un valor distinto de cero para que Qt muestre información de diagnóstico sobre cada complemento (C++) que intente cargar. |
QML_IMPORT_TRACE | Establezca un valor distinto de cero para que QML muestre información de diagnóstico procedente del mecanismo de carga de importaciones. |
QT_HASH_SEED | Establecéla en un valor entero para desactivar QHash y QSet, que utilizan un nuevo orden aleatorio cada vez que se ejecuta la aplicación, lo que en algunos casos podría dificultar las pruebas y la depuración. |
QT_WIN_DEBUG_CONSOLE | En Windows, las aplicaciones GUI no están vinculadas a una consola, por lo que la salida escrita en stdout y stderr no es visible para el usuario. Los IDE suelen redirigir y mostrar la salida, pero al ejecutar una aplicación desde la línea de comandos, la salida de depuración se pierde. Para acceder a la salida, configura esta variable de entorno en new para que la aplicación asigne una nueva consola, o en attach para que la aplicación intente vincularse a la consola del proceso padre. |
Mensajes de advertencia y depuración
Qt incluye macros globales de C++ para escribir texto de advertencia y depuración. Las macros simples utilizan un valor predeterminado logging category; las macros de registro categorizadas te permiten especificar la categoría. Puedes utilizarlas para los siguientes fines:
| Macro simple | Macro categorizada | Finalidad |
|---|---|---|
| qDebug() | qCDebug() | Se utiliza para escribir salida de depuración personalizada |
| qInfo() | qCInfo() | Se utiliza para mensajes informativos |
| qWarning() | qCWarning() | Se utiliza para informar de advertencias y errores recuperables en tu aplicación o biblioteca |
| qCritical() | qCCritical() | Se utiliza para escribir mensajes de error críticos y notificar errores del sistema |
| qFatal() | - | Se utiliza para escribir mensajes sobre errores fatales justo antes de salir |
Si se incluye el archivo de cabecera <QtDebug>, la macro qDebug() también se puede utilizar como flujo de salida. Por ejemplo:
qDebug() << "Widget" << widget << "at position" << widget->pos();La implementación de Qt de estas macros envía la salida a stderr en Unix/Linux y macOS. En Windows, si se trata de una aplicación de consola, el texto se envía a la consola; en caso contrario, se envía al depurador.
Por defecto, solo se muestra el mensaje. Puedes incluir información adicional configurando la variable de entorno QT_MESSAGE_PATTERN. Por ejemplo:
QT_MESSAGE_PATTERN="[%{time process} %{type}] %{appname} %{category} %{function} - %{message}"El formato se documenta en ` qSetMessagePattern()`. También puede instalar su propio gestor de mensajes utilizando ` qInstallMessageHandler()`.
Si se establece la variable de entorno QT_FATAL_WARNINGS, qWarning() finaliza su ejecución tras mostrar el mensaje de advertencia. Esto facilita la obtención de un seguimiento de pila en el depurador.
qDebug(), qInfo() y qWarning() son herramientas de depuración. Se pueden omitir en la compilación definiendo QT_NO_DEBUG_OUTPUT, QT_NO_INFO_OUTPUT o QT_NO_WARNING_OUTPUT durante la compilación.
Las funciones de depuración QObject::dumpObjectTree() y QObject::dumpObjectInfo() suelen resultar útiles cuando una aplicación tiene un aspecto o un comportamiento extraño. Son más útiles si se utiliza object names que si no, pero suelen ser útiles incluso sin nombres.
En QML, dumpItemTree() cumple la misma función.
Cómo proporcionar soporte para el operador de flujo qDebug()
Puedes implementar el operador de flujo utilizado por qDebug() para proporcionar soporte de depuración a tus clases. La clase que implementa el flujo es QDebug. Utiliza QDebugStateSaver para guardar temporalmente las opciones de formato del flujo. Utiliza nospace() y QTextStream manipulators para personalizar aún más el formato.
A continuación se muestra un ejemplo de una clase que representa una coordenada 2D.
QDebug operator<<(QDebug dbg, const Coordinate &c)
{
QDebugStateSaver saver(dbg);
dbg.nospace() << "(" << c.x() << ", " << c.y() << ")";
return dbg;
}La integración de tipos personalizados con el sistema de metaobjetos de Qt se trata con más detalle en el documento «Creación de tipos Qt personalizados ».
Macros de depuración
El archivo de cabecera <QtGlobal> contiene algunas macros de depuración y « #define».
Tres macros importantes son:
- Q_ASSERT(cond), donde
condes una expresión booleana, escribe la advertencia «ASSERT:'cond' en el archivo xyz.cpp, línea 234» y sale del programa sicondes falso. - Q_ASSERT_X(cond, where, what), donde
condes una expresión booleana,whereuna ubicación ywhatun mensaje, muestra la advertencia: «Fallo de ASSERT enwhere: 'what', archivo xyz.cpp, línea 234» y sale del programa sicondes falso. - Q_CHECK_PTR(ptr), donde
ptres un puntero. Muestra la advertencia «En el archivo xyz.cpp, línea 234: Falta de memoria» y sale del programa siptres 0.
Estas macros son útiles para detectar errores en el programa, por ejemplo, de esta forma:
char *alloc(int size)
{
Q_ASSERT(size > 0);
char *ptr = new char[size];
Q_CHECK_PTR(ptr);
return ptr;
}Q_ASSERT(), Q_ASSERT_X() y Q_CHECK_PTR() se expanden a nada si QT_NO_DEBUG está definido durante la compilación. Por este motivo, los argumentos de estas macros no deben tener efectos secundarios. A continuación se muestra un uso incorrecto de Q_CHECK_PTR():
char *alloc(int size)
{
char *ptr;
Q_CHECK_PTR(ptr = new char[size]); // WRONG
return ptr;
}Si este código se compila con ` QT_NO_DEBUG ` definido, el código de la expresión ` Q_CHECK_PTR()` no se ejecuta y `alloc` devuelve un puntero no inicializado.
La biblioteca Qt contiene cientos de comprobaciones internas que mostrarán mensajes de advertencia cuando se detecte un error de programación. Por lo tanto, recomendamos utilizar una versión de depuración de Qt al desarrollar software basado en Qt.
El registro de eventos y « categorized logging » también son posibles en QML.
Errores comunes
Hay un error tan común que merece la pena mencionarlo aquí: si incluyes la macro « Q_OBJECT » en la declaración de una clase y ejecutas el Meta-Object Compiler (moc), pero olvidas enlazar el código objeto generado por « moc » con tu ejecutable, obtendrás mensajes de error muy confusos. Cualquier error de enlace que indique la falta de vtbl, _vtbl, __vtbl o similares probablemente se deba a este problema.
© 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.