Introducción a CMake

CMake es un grupo de herramientas que permiten construir, probar y empaquetar aplicaciones. Al igual que Qt, está disponible en las principales plataformas de desarrollo. También está soportado por varios IDE, incluyendo Qt Creator.

En esta sección mostraremos la forma más básica de utilizar Qt en un proyecto CMake. Primero, creamos una aplicación de consola básica. Luego, extendemos el proyecto a una aplicación GUI que usa . Qt Widgets.

Si desea saber cómo construir un proyecto CMake existente con Qt, consulte la documentación sobre cómo construir proyectos con CMake en la línea de comandos.

Para aprender los conceptos básicos de cómo empezar con CMake, tome el curso Building with Cmake: Getting Started with CMake and Qt en Qt Academy.

Construyendo una aplicación de consola C

Un proyecto CMake está definido por archivos escritos en el lenguaje CMake. El archivo principal se llama CMakeLists.txt, y normalmente se coloca en el mismo directorio que las fuentes reales del programa.

A continuación se muestra un archivo CMakeLists.txt típico 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 el contenido.

cmake_minimum_required(VERSION 3.16)

cmake_minimum_required() especifica la versión mínima de CMake necesaria para configurar correctamente el proyecto. Ver Versiones CMake soportadas para la versión mínima requerida por Qt.

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

project() establece un nombre de proyecto y la versión por defecto del proyecto. 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 que soporte C++ versión 17 o superior. Hacer cumplir esto estableciendo las variables CMAKE_CXX_STANDARD, CMAKE_CXX_STANDARD_REQUIRED permitirá a CMake imprimir un error si el compilador es demasiado antiguo.

find_package(Qt6 REQUIRED COMPONENTS Core)

Esto le dice a CMake que busque Qt 6 y haga que el módulo Core esté disponible. No tiene sentido continuar si CMake no puede localizar el módulo, por lo que establecemos la bandera REQUIRED para que CMake aborte en este caso. Para más información, ver Hacer Qt disponible en proyectos CMake.

Si tiene éxito, el módulo establecerá algunas variables CMake documentadas en Module variables. Además importa el target Qt6::Core que usamos a continuación.

qt_standard_project_setup()

El comando qt_standard_project_setup establece los valores por defecto de todo el proyecto para una aplicación Qt típica.

Entre otras cosas, este comando establece la variable CMAKE_AUTOMOC en ON, lo que indica a CMake que establezca automáticamente reglas para que Meta-Object Compiler (moc) de Qt sea llamado de forma transparente, cuando sea necesario.

Ver la referencia de qt_standard_project_setup para más detalles.

qt_add_executable(helloworld
    main.cpp
)

qt_add_executable() le dice a CMake que queremos construir un ejecutable (no una librería) llamado helloworld como objetivo. Es una envoltura alrededor del comando incorporado add_executable(), y proporciona lógica adicional para manejar automáticamente cosas como la vinculación de los plugins de Qt en las construcciones estáticas de Qt, la personalización específica de la plataforma de los nombres de las bibliotecas, y así sucesivamente.

El objetivo debe construirse a partir del archivo fuente C++ main.cpp.

Normalmente, no se listan los archivos de cabecera aquí. Esto es diferente de qmake, donde los archivos de cabecera necesitan ser explícitamente listados para que sean procesados por Meta-Object Compiler (moc).

Para crear bibliotecas, ver qt_add_library.

target_link_libraries(helloworld PRIVATE Qt6::Core)

Por último, target_link_libraries indica a CMake que el ejecutable helloworld hace uso de Qt Core haciendo referencia al objetivo Qt6::Core importado por la llamada find_package() anterior. Esto no sólo agregará los argumentos correctos al enlazador, sino que también se asegura de que los directorios de inclusión correctos, las definiciones del compilador se pasen al compilador C++. 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 cabeceras, PRIVATE en caso contrario).

Creación de una aplicación GUI en C

En la última sección mostramos el archivo CMakeLists.txt para una simple aplicación de consola. Ahora crearemos una aplicación GUI que utilice el módulo Qt Widgets módulo.

Este es el archivo de proyecto completo:

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
)

Vamos a recorrer los cambios que hemos hecho.

find_package(Qt6 REQUIRED COMPONENTS Widgets)

En la llamada a find_package, reemplazamos Core por Widgets. Esto localizará el módulo Qt6Widgets y proporcionará los objetivos Qt6::Widgets con los que enlazaremos más tarde.

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 User Interface Compiler (uic) de Qt en los archivos fuente .ui.

qt_add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
)

Añadimos un archivo Qt Widgets Designer (mainwindow.ui) y su correspondiente archivo fuente C++ (mainwindow.cpp) a los fuentes del destino de la aplicación.

target_link_libraries(helloworld PRIVATE Qt6::Widgets)

En el comando target_link_libraries, enlazamos con Qt6::Widgets en lugar de Qt6::Core. Tenga en cuenta que la aplicación seguirá enlazada con Qt6::Core, porque Qt6::Widgets depende de ella.

set_target_properties(helloworld PROPERTIES
    WIN32_EXECUTABLE ON
    MACOSX_BUNDLE ON
)

Por último, establecemos propiedades en nuestro objetivo de aplicación con los siguientes efectos:

• Evitar la creación de una ventana de consola en Windows.
• Crear un paquete de aplicaciones en macOS.

Consulte la documentación de CMake para obtener más información sobre estas propiedades de destino.

Estructurar proyectos

Los proyectos que contienen más de un objetivo se beneficiarán de una estructura clara de archivos de proyecto. Vamos a utilizar la función de subdirectorio de CMake.

Como planeamos ampliar el proyecto con más objetivos, movemos los archivos fuente de la aplicación a un subdirectorio y creamos un nuevo CMakeLists.txt allí.

<project root>
├── CMakeLists.txt
└── src
    └── app
        ├── CMakeLists.txt
        ├── main.cpp
        ├── mainwindow.cpp
        ├── mainwindow.h
        └── mainwindow.ui

El nivel superior CMakeLists.txt contiene la configuración general del proyecto, find_package y add_subdirectory llamadas:

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 que se establecen en este archivo son visibles en los archivos de proyecto de subdirectorio.

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 adición de más objetivos al proyecto, como bibliotecas o pruebas unitarias.

Creación de bibliotecas

A medida que el proyecto crece, es posible que desee convertir partes del código de su aplicación en una biblioteca que sea utilizada por la aplicación y, posiblemente, pruebas unitarias. Esta sección muestra cómo crear una biblioteca de este tipo.

Nuestra aplicación actualmente contiene lógica de negocio directamente en main.cpp. Extraemos el código en una nueva biblioteca estática llamada businesslogic en el subdirectorio "src/businesslogic" como se explica en la sección anterior.

En aras de la simplicidad, la biblioteca consta de un único archivo fuente C++ y su correspondiente archivo de cabecera que se incluye en la aplicación main.cpp:

<project root>
├── CMakeLists.txt
└── src
    ├── app
    │   ├── ...
    │   └── main.cpp
    └── businesslogic
        ├── CMakeLists.txt
        ├── businesslogic.cpp
        └── businesslogic.h

Veamos el fichero de proyecto de la librería (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})

Veamos el contenido.

qt_add_library(businesslogic STATIC
    businesslogic.cpp
)

El comando add_library crea la librería businesslogic. Más tarde, dejaremos que la aplicación enlace contra este objetivo.

La palabra clave STATIC denota 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 no tenemos que enlazar otras bibliotecas. Pero como nuestra biblioteca utiliza clases de QtCore, añadimos una dependencia de enlace a Qt6::Core. Esto trae las rutas de inclusión necesarias de QtCore y las definiciones del preprocesador.

target_include_directories(businesslogic INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})

La API de la biblioteca se define en el archivo de cabecera businesslogic/businesslogic.h. Llamando 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 libera en main.cpp de usar rutas relativas para localizar businesslogic.h. En su lugar, podemos 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 las bibliotecas

Para utilizar la biblioteca que creamos en la sección anterior, le indicamos a CMake que enlace con ella:

target_link_libraries(helloworld PRIVATE
    businesslogic
    Qt6::Widgets
)

Esto asegura que businesslogic.h se encuentre cuando se compile main.cpp. Además, la biblioteca estática businesslogic formará parte del ejecutable helloworld.

En términos de CMake, la biblioteca businesslogic especifica los requisitos de uso (la ruta de inclusión) que cada consumidor de nuestra biblioteca (la aplicación) tiene que satisfacer. 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 usando el Sistema de Recursos Qt.

qt_add_resources(helloworld imageresources
    PREFIX "/images"
    FILES logo.png splashscreen.png
)

El comando qt_add_resources crea automáticamente un recurso Qt que contiene las imágenes referenciadas. Desde el código fuente C++, se puede acceder a las imágenes anteponiendo el prefijo del 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 objetivo de este comando, como se muestra en el ejemplo anterior.

Añadir traducciones

Las traducciones de cadenas en un proyecto Qt se codifican en archivos .ts. Estos archivos .ts se compilan en archivos binarios .qm, que luego son cargados por la aplicación Qt en tiempo de ejecución. Ver Internacionalización con Qt para más detalles.

Esta sección describe cómo añadir una traducción al alemán y al francés a la aplicación helloworld.

Especifique 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 destino que 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 fuente del proyecto. Estos archivos contendrán las cadenas traducidas y se supone que se pondrán bajo control de versiones.

El comando también crea reglas del sistema de compilación para generar automáticamente archivos .qm a partir de los archivos .ts. Por defecto, los archivos .qm se incrustan en un recurso y son accesibles bajo el prefijo de recurso "/i18n".

Para actualizar las entradas en el archivo .ts, construya el objetivo update_translations:

$ cmake --build . --target update_translations

Para activar manualmente la generación de los archivos .qm, cree el objetivo release_translations:

$ cmake --build . --target release_translations

Para obtener más información sobre cómo influir en el manejo de los archivos .ts y la incrustación en un recurso, consulte la documentación qt_add_translations.

El comando qt_add_translations es una envoltura de conveniencia. Para un control más preciso de 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 cubre tareas comunes del sistema de compilación.

El libro Professional CMake: A Practical Guide proporciona una gran introducción a las características más relevantes de CMake.