En esta página

Opciones de configuración de Qt

configure es una herramienta de línea de comandos que te ayuda a compilar una versión personalizada de Qt a partir del código fuente. Forma parte del directorio principal de fuentes de Qt.

Desde Qt 6, `configure` es una envoltura de CMake. CMake también se puede invocar directamente. `configure` proporciona comprobaciones de errores adicionales y compatibilidad con Qt 5.

En esta página se describen algunas de las opciones de `configure`. Para ver la lista completa de opciones, introduce el comando ` configure -h`.

Nota: A menos que se indique lo contrario, los comandos de esta página son para plataformas Linux. En macOS y Windows, el comando ` PATH ` y la estructura de directorios son diferentes, por lo que los comandos variarán. Además, en los sistemas Windows, el script `configure` se llama ` configure.bat`.

Flujo de trabajo de «configure»

«configure» debe ejecutarse en un entorno de compilación operativo en el que CMake, los compiladores y las herramientas de compilación necesarias estén disponibles. La sección «Compilación de los fuentes de Qt » enumera dichas dependencias por plataforma.

Una vez configurado dicho entorno, el flujo de trabajo habitual consiste en crear un directorio de compilación independiente y, a continuación, ejecutar primero «configure», después compilar Qt y, por último, instalar Qt:

~/qt-source/configure
cmake --build . --parallel
cmake --install .

Es posible que quieras probar con diferentes opciones de `configure` y, por lo tanto, ejecutar `configure` varias veces. Ten en cuenta que CMake almacena en caché las opciones de `configure` y la información sobre el entorno en un archivo llamado `CMakeCache.txt`. Elimina este archivo cuando quieras empezar de cero sin la información almacenada en caché.

Directorios de código fuente, compilación e instalación

El directorio de código fuente contiene el código fuente obtenido del paquete fuente o del repositorio de Git. El directorio de compilación es donde se almacenan los archivos relacionados con la compilación, como los archivos del sistema de compilación, los archivos objeto y otros archivos intermedios. El directorio de instalación es donde se instalan los binarios y las bibliotecas, para su uso por parte del sistema o de la aplicación.

Se recomienda mantener estos directorios separados mediante la compilación en segundo plano y el uso de la opción -prefix. Esto te permite mantener el árbol de fuentes de Qt limpio de los artefactos de compilación y los binarios, que se almacenan en un directorio independiente. Este método resulta muy práctico si deseas realizar varias compilaciones a partir del mismo árbol de fuentes, pero con configuraciones diferentes. Para realizar una compilación en segundo plano, ejecute `configure` desde un directorio independiente:

mkdir ~/qt-build
cd ~/qt-build
~/qt-source/configure -prefix /opt/Qt6

Configurar con la opción -prefix significa que los binarios y las bibliotecas de Qt se instalan en otro directorio, que en este caso es /opt/Qt6.

Ejemplos, pruebas y herramientas

Por defecto, `configure` solo configura las bibliotecas y herramientas de Qt. Puedes utilizar ` -make examples ` o ` -make tests ` para compilar también los ejemplos o las pruebas que vienen con Qt:

~/qt-source/configure -make examples -make tests

También puedes configurar Qt de modo que los ejemplos, las pruebas y las herramientas se configuren, pero no se compilen de forma predeterminada. Si estableces las variables de CMake QT_BUILD_EXAMPLES_BY_DEFAULT, QT_BUILD_TESTS_BY_DEFAULT y QT_BUILD_TOOLS_BY_DEFAULT en OFF, las partes respectivas no se compilarán con cmake --build .. En su lugar, CMake generará objetivos individuales que podrás compilar por separado.

Aquí compilamos las bibliotecas y herramientas de Qt, pero también el ejemplo NotePad:

~/qt-source/configure -make examples -- -D QT_BUILD_EXAMPLES_BY_DEFAULT=OFF
cmake --build . --parallel
cmake --build . --parallel --target notepad

Nota: La opción « -developer-build » compila las pruebas de forma predeterminada. Véase también «Compilaciones para desarrolladores» más abajo.

Configuraciones de compilación

Puedes compilar las bibliotecas y herramientas de Qt en diversas variantes, cada una de ellas optimizada para un caso de uso diferente.

Las compilaciones de depuración y de lanzamiento

-release indica al compilador que optimice el código y que no proporcione símbolos de depuración adicionales junto con Qt y sus herramientas.

-debug Omite algunas optimizaciones para facilitar la depuración de Qt y sus herramientas. Esta opción también habilita la generación de símbolos de depuración que permiten inspeccionar el código y el estado de las bibliotecas compiladas en un depurador.

Por último, la opción « -debug-and-release » permite compilar tanto la variante de depuración como la de lanzamiento de las bibliotecas de Qt de una sola vez. Esto solo es compatible si se configura una compilación para Windows.

Existen otras opciones para ajustar las configuraciones:

  • -force-debug-info: Crea una compilación de lanzamiento con información de depuración.
  • -separate-debug-info: Extrae la información de depuración a un archivo independiente.
  • -optimize-size: Optimiza las compilaciones de versión final en cuanto a tamaño, en lugar de velocidad.

Compilaciones estáticas y compartidas

Los módulos de Qt se pueden compilar como bibliotecas independientes a las que un ejecutable se vincula y carga en el momento del inicio (en el caso de las bibliotecas de Qt) o en tiempo de ejecución (en el caso de los complementos de Qt). Esto se denomina compilación compartida y es la configuración predeterminada en la mayoría de las plataformas. La opción de configuración correspondiente es -shared.

También puedes compilar Qt de tal forma que un binario ejecutable incluya todos los módulos de Qt a los que se vincula y todos los complementos de Qt que necesita. Esto se denomina compilación estática y se puede seleccionar al configurar con la opción -static.

Generadores de CMake

Al configurar, puedes seleccionar un generador de CMake. Ten en cuenta que CMake admite generadores que no se pueden utilizar con Qt. Por lo tanto, configure selecciona automáticamente un generador por ti.

«configure» siempre utiliza el generador y la herramienta de compilación « Ninja » si hay un ejecutable de Ninja disponible. Ninja es multiplataforma, cuenta con numerosas funciones y ofrece un buen rendimiento, por lo que se recomienda en todas las plataformas. El uso de otros generadores podría funcionar, pero no está oficialmente soportado.

Módulos y características

El código fuente de Qt está organizado en varios directorios de nivel superior denominados submódulos, por ejemplo, qtbase, qtdeclarative o qtmultimedia. Dentro de estos submódulos se encuentra el código fuente de los diferentes módulos de Qt. Qt Core, Qt Quick, y Qt Multimedia son ejemplos de dichos módulos de Qt.

Nota: Muchos submódulos (directorios de código fuente de nivel superior) tienen el mismo nombre que los módulos de Qt que implementan, pero no siempre es así. Por ejemplo, qtdeclarative contiene Qt Quick y Qt Qml, así como varios módulos relacionados. Consulta el archivo README.md en los respectivos directorios para obtener una visión general.

Los submódulos se pueden incluir o excluir explícitamente para reducir los tiempos de compilación. Además, cada módulo de Qt puede tener características que también se pueden activar o desactivar explícitamente.

Inclusión y exclusión de submódulos de Qt

La opción « -skip » de «configure» se utiliza para excluir submódulos (directorios de código fuente de nivel superior) de la compilación de Qt. Al excluir un submódulo, se excluyen todos los módulos de Qt que contiene dicho submódulo. El submódulo « qtwayland » contiene tanto el Qt Wayland Compositor el complemento Qt Wayland QPA. Por lo tanto, al especificar « -skip qtwayland » como opción de `configure` se excluirán ambos módulos de Qt.

~/qt-source/configure -skip qtwayland

La opción « -submodules » de «configure» se puede utilizar para configurar una compilación que solo compile los submódulos indicados y sus dependencias. Por ejemplo, al especificar el submódulo « qtmultimedia », Qt Multimedia se incluirán en la compilación tanto este como todas sus dependencias. Se pueden separar varios submódulos mediante comas.

~/qt-source/configure -submodules qtmultimedia,qtactiveqt

Inclusión o exclusión de características

Las opciones « -feature-<característica> » y « -no-feature-<característica>» incluyen y excluyen características específicas, respectivamente.

Por ejemplo, puedes utilizar la opción de configuración -no-feature-accessibility para desactivar la compatibilidad con la accesibilidad en Qt:

~/qt-source/configure -no-feature-accessibility

Utilice configure -list-features para mostrar una lista de todas las características disponibles en la línea de comandos. Tenga en cuenta que las características pueden depender de otras, por lo que desactivar una característica podría tener efectos secundarios en otras.

Bibliotecas de terceros

Los paquetes fuente de Qt incluyen bibliotecas de terceros. Para establecer si Qt debe utilizar las versiones de las bibliotecas del sistema o la versión incluida en el paquete, introduce « -system » o « -qt » antes del nombre de la biblioteca que desees configurar.

La siguiente tabla resume algunas opciones de terceros:

Nombre de la bibliotecaIncluida en QtIncluida en Qt
zlib-qt-zlib-system-zlib
libjpeg-qt-libjpeg-system-libjpeg
libpng-qt-libpng-system-libpng
freetype-qt-freetype-system-freetype
PCRE-qt-pcre-system-pcre
HarfBuzz-NG-qt-harfbuzz-system-harfbuzz

También es posible desactivar la compatibilidad con la mayoría de estas bibliotecas utilizando -no en lugar de -qt.

La herramienta «configure» de Qt 6 utiliza CMake para localizar las bibliotecas de terceros. Para ello, comprueba diversas rutas del sistema. Si has instalado las bibliotecas en otra ubicación, puedes indicárselo a CMake configurando o ampliando la variable CMAKE_PREFIX_PATH.

Para obtener una lista completa de opciones, consulta la ayuda de configure -help.

SSL

Qt Network se puede configurar para admitir la comunicación mediante Secure Sockets Layer (SSL), pero no implementa los algoritmos propiamente dichos. En su lugar, necesita recurrir a otras bibliotecas.

En Windows, Qt puede utilizar la biblioteca Secure Channel del sistema para este fin (opción de configuración ` -schannel`). En macOS e iOS, Qt se puede configurar para utilizar la API SecureTransport (opción de configuración ` -securetransport`).

El soporte más completo, que además funciona en casi todas las plataformas de destino, lo proporciona el kit de herramientas OpenSSL (opción -openssl). Qt requiere OpenSSL 1.1.1 o posterior.

Qt se puede configurar para utilizar OpenSSL de tres maneras:

  • Qt Network carga las bibliotecas de OpenSSL (DLL) cuando se necesitan por primera vez, en tiempo de ejecución. Si no se encuentran, la aplicación sigue ejecutándose, pero no puede gestionar la comunicación SSL. Esto se habilita utilizando la opción de configuración -openssl-runtime.
  • Qt Network se enlaza con las bibliotecas de OpenSSL. Si no se encuentran en el momento de la carga, la aplicación no se inicia. Esto se habilita utilizando la opción de configuración ` -openssl-linked`.
  • Qt Network Se compila con una versión estática de las bibliotecas de OpenSSL, y OpenSSL pasa a formar parte de la biblioteca « Qt Network ». Esto se habilita utilizando la opción de configuración « openssl-linked » y estableciendo la variable « OPENSSL_USE_STATIC_LIBS » en « ON ».

Establezca la variable de CMake ` OPENSSL_ROOT_DIR ` si OpenSSL no está instalado en una ubicación estándar y, por lo tanto, `configure` no lo encuentra.

Consulte Clases de Secure Sockets Layer (SSL) para obtener más instrucciones sobre Qt con soporte para SSL.

Opciones de compilación cruzada

Para configurar Qt para el desarrollo y la implementación multiplataforma, primero debe disponer de una versión de Qt compatible con la máquina host. Además, es necesario configurar la cadena de herramientas de desarrollo para la plataforma de destino. Esta configuración varía según las plataformas compatibles.

Las opciones habituales son:

  • -external-hostbindir - Ruta a las herramientas de Qt compiladas para esta máquina.
  • -device - Selecciona dispositivos/mkspec para los archivos complementarios de qmake.
  • -device-option - Establece variables qmake adicionales.

Nota: Las cadenas de herramientas para destinos que no sean de escritorio suelen incluir lo que se conoce como «sysroot», con el que hay que configurar Qt.

Compilaciones para desarrolladores

La opción de configuración « -developer-build » es una opción práctica que optimiza la compilación para el desarrollo del propio Qt. No debe utilizarse para compilar variantes de Qt destinadas a los clientes.

Las bibliotecas de una compilación para desarrolladores contienen más símbolos exportados que una compilación estándar, y todo el código de Qt se compila con un nivel de advertencias más alto. También cambia el prefijo predeterminado al directorio de compilación, lo que evita la necesidad de instalar Qt antes de realizar pruebas, y, por último, habilita de forma predeterminada la compilación de las pruebas automáticas de Qt.

Reconfiguración de compilaciones existentes

El sistema de compilación de Qt ofrece soporte básico para reconfigurar compilaciones existentes de Qt con un conjunto diferente de opciones de configuración, pero no es muy robusto debido al funcionamiento interno de CMake.

La forma más segura de reconfigurar una compilación existente es pasar la opción « -redo » a «configure». Esto eliminará el archivo «CMakeCache.txt» de la compilación, lo que garantiza un estado relativamente seguro para la reconfiguración. Las opciones iniciales de «configure» seguirán aplicándose a la compilación reconfigurada.

Instalación del resumen y las opciones de «configure»

Desde Qt 6.9, los archivos de resumen de «configure», así como las opciones pasadas a « configure », pueden incluirse automáticamente como parte de la instalación.

Esta función se habilita estableciendo la variable de CMake ` QT_INSTALL_CONFIG_INFO_FILES ` en ` ON`:

~/qt-source/configure -prefix /opt/Qt6 -- -D QT_INSTALL_CONFIG_INFO_FILES=ON

Durante la instalación, los archivos de texto con el resumen de «configure» y las opciones (para cada parte del repositorio de la compilación) se copian en ` architecture-independent Qt data directory`.

Por ejemplo,

/opt/Qt6/config_qtbase.opt
/opt/Qt6/config_qtbase.summary
/opt/Qt6/config_qtdeclarative.opt
/opt/Qt6/config_qtdeclarative.summary
...

Opciones específicas para plataformas

Las siguientes páginas ofrecen directrices sobre cómo configurar Qt para el desarrollo en plataformas específicas:

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