Primeros pasos con CMake
CMake es un conjunto de herramientas que permiten compilar, probar y empaquetar aplicaciones. Al igual que Qt, está disponible en todas las principales plataformas de desarrollo. Además, es compatible con diversos entornos de desarrollo integrado (IDE), entre los que se incluyen Qt Creator y Visual Studio Code.
En esta sección mostraremos la forma más básica de utilizar Qt en un proyecto de CMake. En primer lugar, crearemos una aplicación básica de consola. A continuación, ampliaremos el proyecto para convertirlo en una aplicación con interfaz gráfica de usuario que utilice Qt Widgets.
Si quieres saber cómo compilar un proyecto CMake existente con Qt, consulta la documentación sobre cómo compilar proyectos con CMake desde la línea de comandos.
Para aprender los conceptos básicos sobre cómo empezar a utilizar CMake, realiza el curso «Compilación con CMake: Introducción a CMake y Qt» en Qt Academy.
Compilación de una aplicación de consola en C++
Un proyecto de « CMake » se define mediante archivos escritos en el lenguaje CMake. El archivo principal se denomina « CMakeLists.txt » y suele ubicarse en el mismo directorio que los archivos fuente del programa.
A continuación se muestra un archivo típico de CMakeLists.txt para una aplicación de consola escrita en C++ utilizando Qt:
cmake_minimum_required(VERSION 3.16)
project(helloworld VERSION 1.0.0 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()
qt_add_executable(helloworld
main.cpp
)
target_link_libraries(helloworld PRIVATE Qt6::Core)Repasemos su contenido.
cmake_minimum_required(VERSION 3.16)cmake_minimum_required() especifica la versión mínima de CMake necesaria para configurar correctamente el proyecto. Consulta «Versiones de CMake compatibles» para conocer la versión mínima requerida por Qt.
project(helloworld VERSION 1.0.0 LANGUAGES CXX)project() establece el nombre del proyecto y la versión predeterminada del mismo. El argumento « LANGUAGES » indica a CMake que el programa está escrito en C++.
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)Qt 6 requiere un compilador compatible con la versión 17 de C++ o posterior. Al aplicar este requisito configurando las variables CMAKE_CXX_STANDARD y CMAKE_CXX_STANDARD_REQUIRED, CMake mostrará un error si el compilador es demasiado antiguo.
find_package(Qt6 REQUIRED COMPONENTS Core)Esto indica a CMake que busque Qt 6 y que el módulo Core esté disponible. No tiene sentido continuar si CMake no puede localizar el módulo, por lo que establecemos el indicador REQUIRED para que CMake se detenga en este caso. Para obtener más información, consulta «Hacer que Qt esté disponible en proyectos de CMake».
Si se realiza correctamente, el módulo establecerá algunas variables de CMake documentadas en «Variables del módulo». Además, importa el objetivo « Qt6::Core » que utilizaremos a continuación.
qt_standard_project_setup()El comando ` qt_standard_project_setup()` establece los valores predeterminados para todo el proyecto en una aplicación Qt típica.
Entre otras cosas, este comando establece la variable « CMAKE_AUTOMOC » en « ON », lo que indica a CMake que configure automáticamente las reglas para que el generador de código de Qt (Meta-Object Compiler, moc) se ejecute de forma transparente cuando sea necesario.
Consulte la referencia de qt_standard_project_setup() para obtener más detalles.
qt_add_executable(helloworld
main.cpp
)qt_add_executable() indica a CMake que queremos compilar un ejecutable (es decir, no una biblioteca) llamado helloworld como objetivo. Se trata de un envoltorio del comando integrado « add_executable() » y proporciona lógica adicional para gestionar automáticamente aspectos como la vinculación de complementos de Qt en compilaciones estáticas de Qt, la personalización de los nombres de las bibliotecas según la plataforma, etc.
El objetivo debe compilarse a partir del archivo fuente de C++ main.cpp.
Normalmente, aquí no se enumeran los archivos de cabecera. Esto difiere de qmake, donde los archivos de cabecera deben enumerarse explícitamente para que sean procesados por el generador de código (Meta-Object Compiler, moc).
Para crear bibliotecas, consulta qt_add_library().
target_link_libraries(helloworld PRIVATE Qt6::Core)Por último, target_link_libraries indica a CMake que el ejecutable helloworld utiliza Qt Core haciendo referencia al objetivo « Qt6::Core » importado por la llamada « find_package() » anterior. Esto no solo añadirá los argumentos correctos al enlazador, sino que también garantiza que se pasen al compilador de C++ los directorios de inclusión y las definiciones de compilador adecuados. La palabra clave « PRIVATE » no es estrictamente necesaria para un objetivo ejecutable, pero es una buena práctica especificarla. Si « helloworld » fuera una biblioteca en lugar de un ejecutable, entonces debería especificarse « PRIVATE » o « PUBLIC » (PUBLIC si la biblioteca menciona algo de Qt6::Core en sus encabezados; PRIVATE en caso contrario).
Compilación de una aplicación GUI en C++
En la última sección mostramos el archivo CMakeLists.txt para una sencilla aplicación de consola. Ahora crearemos una aplicación con interfaz gráfica de usuario que utilice el Qt Widgets módulo.
Este es el archivo completo del proyecto:
cmake_minimum_required(VERSION 3.16)
project(helloworld VERSION 1.0.0 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()
qt_add_executable(helloworld
mainwindow.ui
mainwindow.cpp
main.cpp
)
target_link_libraries(helloworld PRIVATE Qt6::Widgets)
set_target_properties(helloworld PROPERTIES
WIN32_EXECUTABLE ON
MACOSX_BUNDLE ON
)Repasemos los cambios que hemos realizado.
find_package(Qt6 REQUIRED COMPONENTS Widgets)En la llamada a ` find_package `, sustituimos ` Core ` por ` Widgets`. Esto localizará el módulo ` Qt6Widgets ` y proporcionará los objetivos ` Qt6::Widgets ` con los que posteriormente realizaremos el enlace.
qt_standard_project_setup()Además de CMAKE_AUTOMOC, qt_standard_project_setup() establece la variable CMAKE_AUTOUIC en ON. Esto creará automáticamente reglas para invocar elUser Interface Compiler (uic) de Qt en los archivos fuente .ui.
qt_add_executable(helloworld
mainwindow.ui
mainwindow.cpp
main.cpp
)Añadimos un Qt Widgets Designer archivo (mainwindow.ui) y su correspondiente archivo fuente en C++ (mainwindow.cpp) a las fuentes del destino de la aplicación.
Nota: Otra forma de añadir archivos .ui a tu proyecto es utilizar el comando qt_add_ui() en lugar de AUTOUIC.
target_link_libraries(helloworld PRIVATE Qt6::Widgets)En el comando target_link_libraries, se realiza el enlace con Qt6::Widgets en lugar de Qt6::Core. Ten en cuenta que la aplicación seguirá enlazándose con Qt6::Core, ya que Qt6::Widgets depende de él.
set_target_properties(helloworld PROPERTIES
WIN32_EXECUTABLE ON
MACOSX_BUNDLE ON
)Por último, configuramos las propiedades de nuestro objetivo de aplicación con los siguientes efectos:
- Evitar la creación de una ventana de consola en Windows.
- Crear un paquete de aplicación en macOS.
Consulta la documentación de CMake para obtener más información sobre estas propiedades del destino.
Estructuración de proyectos
Los proyectos que contengan más de un objetivo se beneficiarán de una estructura clara de archivos de proyecto. Utilizaremos la función de subdirectorios de CMake.
Como tenemos previsto ampliar el proyecto con más objetivos, trasladamos los archivos fuente de la aplicación a un subdirectorio y creamos allí un nuevo archivo « CMakeLists.txt ».
<project root>
├── CMakeLists.txt
└── src
└── app
├── CMakeLists.txt
├── main.cpp
├── mainwindow.cpp
├── mainwindow.h
└── mainwindow.uiEl archivo ` CMakeLists.txt ` de nivel superior contiene la configuración general del proyecto, así como las llamadas ` find_package ` y ` add_subdirectory `:
cmake_minimum_required(VERSION 3.16)
project(helloworld VERSION 1.0.0 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()
add_subdirectory(src/app)Las variables definidas en este archivo son visibles en los archivos de los subdirectorios del proyecto.
El archivo de proyecto de la aplicación, src/app/CMakeLists.txt, contiene el objetivo ejecutable:
qt_add_executable(helloworld
mainwindow.ui
mainwindow.cpp
main.cpp
)
target_link_libraries(helloworld PRIVATE Qt6::Widgets)
set_target_properties(helloworld PROPERTIES
WIN32_EXECUTABLE ON
MACOSX_BUNDLE ON
)Esta estructura facilitará la incorporación de nuevos objetivos al proyecto, como bibliotecas o pruebas unitarias.
Nota: Añade el directorio de compilación de tu proyecto a la lista de directorios excluidos de cualquier aplicación antivirus que se ejecute en tu sistema.
Compilación de bibliotecas
A medida que el proyecto crezca, es posible que quieras convertir partes del código de tu aplicación en una biblioteca que sea utilizada por la aplicación y, posiblemente, por las pruebas unitarias. En esta sección se explica cómo crear dicha biblioteca.
Actualmente, nuestra aplicación contiene la lógica de negocio directamente en main.cpp. Extraemos el código a una nueva biblioteca estática llamada businesslogic, situada en el subdirectorio "src/businesslogic", tal y como se explicó en la sección anterior.
Para simplificar, la biblioteca consta únicamente de un archivo fuente de C++ y su correspondiente archivo de cabecera, que se incluye en el archivo « main.cpp » de la aplicación:
<project root>
├── CMakeLists.txt
└── src
├── app
│ ├── ...
│ └── main.cpp
└── businesslogic
├── CMakeLists.txt
├── businesslogic.cpp
└── businesslogic.hEchemos un vistazo al archivo de proyecto de la biblioteca (src/businesslogic/CMakeLists.txt).
qt_add_library(businesslogic STATIC
businesslogic.cpp
)
target_link_libraries(businesslogic PRIVATE Qt6::Core)
target_include_directories(businesslogic INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})Repasemos el contenido.
qt_add_library(businesslogic STATIC
businesslogic.cpp
)El comando `add_library ` crea la biblioteca ` businesslogic`. Más adelante, haremos que la aplicación se enlace con este objetivo.
La palabra clave « STATIC » indica que se trata de una biblioteca estática. Si quisiéramos crear una biblioteca compartida o dinámica, utilizaríamos la palabra clave « SHARED ».
target_link_libraries(businesslogic PRIVATE Qt6::Core)Tenemos una biblioteca estática y, en realidad, no tenemos que vincular otras bibliotecas. Pero, como nuestra biblioteca utiliza clases de QtCore, añadimos una dependencia de enlace a Qt6::Core. Esto incorpora las rutas de inclusión de QtCore y las definiciones del preprocesador necesarias.
target_include_directories(businesslogic INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})La API de la biblioteca se define en el archivo de cabecera businesslogic/businesslogic.h. Al llamar a target_include_directories, nos aseguramos de que la ruta absoluta al directorio businesslogic se añada automáticamente como ruta de inclusión a todos los objetivos que utilicen nuestra biblioteca.
Esto nos permite, en main.cpp, prescindir del uso de rutas relativas para localizar businesslogic.h. En su lugar, basta con escribir
#include <businesslogic.h>Por último, debemos añadir el subdirectorio de la biblioteca al archivo de proyecto de nivel superior:
add_subdirectory(src/app)
add_subdirectory(src/businesslogic)Uso de bibliotecas
Para utilizar la biblioteca que hemos creado en la sección anterior, indicamos a CMake que la vincule:
target_link_libraries(helloworld PRIVATE
businesslogic
Qt6::Widgets
)Esto garantiza que se encuentre « businesslogic.h » al compilar «main.cpp». Además, la biblioteca estática «businesslogic» pasará a formar parte del ejecutable « helloworld ».
En términos de CMake, la biblioteca businesslogic especifica los requisitos de uso (la ruta de inclusión) que debe cumplir todo usuario de nuestra biblioteca (la aplicación). El comando target_link_libraries se encarga de ello.
Añadir recursos
Queremos mostrar algunas imágenes en nuestra aplicación, así que las añadimos utilizando el sistema de recursos de Qt.
qt_add_resources(helloworld imageresources
PREFIX "/images"
FILES logo.png splashscreen.png
)El comando qt_add_resources() crea automáticamente un recurso de Qt que contiene las imágenes a las que se hace referencia. Desde el código fuente de C++, puedes acceder a las imágenes anteponiendo el prefijo de recurso especificado:
logoLabel->setPixmap(QPixmap(":/images/logo.png"));El comando qt_add_resources() toma como primer argumento un nombre de variable o un nombre de destino. Recomendamos utilizar la variante basada en el destino de este comando, tal y como se muestra en el ejemplo anterior.
Añadir traducciones
Las traducciones de las cadenas de un proyecto Qt se codifican en archivos « .ts ». Estos archivos « .ts » se compilan en archivos binarios « .qm », que posteriormente son cargados por la aplicación Qt en tiempo de ejecución. Consulte «Internacionalización con Qt» para obtener más detalles.
En esta sección se describe cómo añadir una traducción al alemán y al francés a la aplicación helloworld.
Especifica ambos idiomas con qt_standard_project_setup():
qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)A continuación, llama a qt_add_translations() en el objetivo que debe cargar los archivos « .qm »:
qt_add_translations(helloworld)En la primera configuración, este comando crea los archivos helloworld_de.ts y helloworld_fr.ts en el directorio de código fuente del proyecto. Estos archivos contendrán las cadenas traducidas y deben incluirse en el control de versiones.
El comando también crea reglas del sistema de compilación para generar automáticamente los archivos « .qm » a partir de los archivos « .ts ». Por defecto, los archivos « .qm » se integran en un recurso y se puede acceder a ellos mediante el prefijo de recurso « "/i18n" ».
Para actualizar las entradas del archivo .ts, compila el objetivo update_translations:
$ cmake --build . --target update_translationsPara activar manualmente la generación de los archivos .qm, compila el objetivo release_translations:
$ cmake --build . --target release_translationsPara obtener más información sobre cómo influir en la gestión de los archivos .ts y su integración en un recurso, consulta la documentación de qt_add_translations.
El comando qt_add_translations() es una envoltura de conveniencia. Para un control más detallado sobre cómo se gestionan los archivos .ts y .qm, utilice los comandos subyacentes qt_add_lupdate() y qt_add_lrelease().
Más información
La documentación oficial de CMake es una fuente inestimable para trabajar con CMake.
El tutorial oficial de CMake aborda las tareas habituales del sistema de compilación.
El libro «Professional CMake: A Practical Guide» ofrece una excelente introducción a las características más relevantes de CMake.
© 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.