Démarrer avec CMake

CMake est un groupe d'outils qui permet de construire, tester et empaqueter des applications. Tout comme Qt, il est disponible sur toutes les principales plateformes de développement. Il est également pris en charge par plusieurs IDE, notamment Qt Creator.

Dans cette section, nous allons montrer la manière la plus basique d'utiliser Qt dans un projet CMake. Tout d'abord, nous créons une application console de base. Ensuite, nous étendons le projet en une application GUI qui utilise Qt Widgets.

Si vous voulez savoir comment construire un projet CMake existant avec Qt, consultez la documentation sur la façon de construire des projets avec CMake en ligne de commande.

Pour apprendre les bases de CMake, suivez le cours Building with Cmake : Getting Started with CMake and Qt dans le cours de la Qt Academy.

Construire une application console C

Un projet CMake est défini par des fichiers écrits en langage CMake. Le fichier principal s'appelle CMakeLists.txt et est généralement placé dans le même répertoire que les sources du programme.

Voici un fichier CMakeLists.txt typique pour une application console écrite en C++ avec 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)

Passons en revue son contenu.

cmake_minimum_required(VERSION 3.16)

cmake_minimum_required() spécifie la version minimale de CMake requise pour configurer le projet avec succès. Voir Versions CMake supportées pour connaître la version minimale requise par Qt.

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

project() définit un nom de projet et la version par défaut du projet. L'argument LANGUAGES indique à CMake que le programme est écrit en C++.

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Qt 6 nécessite un compilateur supportant la version 17 ou plus récente de C++. Renforcer cette exigence en définissant les variables CMAKE_CXX_STANDARD, CMAKE_CXX_STANDARD_REQUIRED permettra à CMake d'afficher une erreur si le compilateur est trop ancien.

find_package(Qt6 REQUIRED COMPONENTS Core)

Cela indique à CMake de rechercher Qt 6 et de rendre le module Core disponible. Il est inutile de continuer si CMake ne peut pas localiser le module, c'est pourquoi nous définissons le drapeau REQUIRED pour permettre à CMake d'abandonner dans ce cas. Pour plus d'informations, voir Rendre Qt disponible dans les projets CMake.

S'il réussit, le module définira certaines variables CMake documentées dans Variables du module. Il importe en outre la cible Qt6::Core que nous utilisons ci-dessous.

qt_standard_project_setup()

La commande qt_standard_project_setup définit les valeurs par défaut de l'ensemble du projet pour une application Qt typique.

Entre autres choses, cette commande définit la variable CMAKE_AUTOMOC à ON, ce qui indique à CMake de mettre en place automatiquement des règles pour que Meta-Object Compiler (moc ) de Qt soit appelé de manière transparente, lorsque cela est nécessaire.

Voir la référence de qt_standard_project_setup pour plus de détails.

qt_add_executable(helloworld
    main.cpp
)

qt_add_executable() indique à CMake que nous voulons construire un exécutable (donc pas une bibliothèque) appelé helloworld comme cible. C'est une enveloppe autour de la commande intégrée add_executable(), et fournit une logique supplémentaire pour gérer automatiquement des choses comme la liaison des plugins Qt dans les constructions statiques de Qt, la personnalisation des noms de bibliothèques en fonction de la plate-forme, et ainsi de suite.

La cible doit être construite à partir du fichier source C++ main.cpp.

Généralement, vous ne listez pas les fichiers d'en-tête ici. Ceci est différent de qmake, où les fichiers d'en-tête doivent être explicitement listés afin qu'ils soient traités par Meta-Object Compiler (moc).

Pour créer des bibliothèques, voir qt_add_library.

target_link_libraries(helloworld PRIVATE Qt6::Core)

Enfin, target_link_libraries indique à CMake que l'exécutable helloworld fait usage de Qt Core en référençant la cible Qt6::Core importée par l'appel find_package() ci-dessus. Cela permet non seulement d'ajouter les bons arguments à l'éditeur de liens, mais aussi de s'assurer que les bons répertoires d'inclusion et les définitions du compilateur sont transmis au compilateur C++. Le mot-clé PRIVATE n'est pas strictement nécessaire pour une cible exécutable, mais c'est une bonne pratique de le spécifier. Si helloworld est une bibliothèque plutôt qu'un exécutable, alors PRIVATE ou PUBLIC doit être spécifié (PUBLIC si la bibliothèque mentionne quelque chose de Qt6::Core dans ses en-têtes, PRIVATE sinon).

Création d'une application GUI C++

Dans la dernière section, nous avons montré le fichier CMakeLists.txt pour une simple application console. Nous allons maintenant créer une application GUI qui utilise le module Qt Widgets module.

Voici le fichier de projet complet :

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
)

Passons en revue les changements que nous avons apportés.

find_package(Qt6 REQUIRED COMPONENTS Widgets)

Dans l'appel find_package, nous remplaçons Core par Widgets. Cela permettra de localiser le module Qt6Widgets et de fournir les cibles Qt6::Widgets avec lesquelles nous établirons des liens par la suite.

qt_standard_project_setup()

En plus de CMAKE_AUTOMOC, qt_standard_project_setup met la variable CMAKE_AUTOUIC à ON. Cela créera automatiquement des règles pour invoquer User Interface Compiler (uic ) de Qt sur les fichiers sources .ui.

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

Nous ajoutons un fichier Qt Widgets Designer (mainwindow.ui) et son fichier source C++ correspondant (mainwindow.cpp) aux sources de l'application cible.

target_link_libraries(helloworld PRIVATE Qt6::Widgets)

Dans la commande target_link_libraries, nous établissons un lien avec Qt6::Widgets au lieu de Qt6::Core. Notez que l'application sera toujours liée à Qt6::Core, car Qt6::Widgets en dépend.

set_target_properties(helloworld PROPERTIES
    WIN32_EXECUTABLE ON
    MACOSX_BUNDLE ON
)

Enfin, nous définissons des propriétés sur la cible de notre application avec les effets suivants :

• Empêcher la création d'une fenêtre de console sous Windows.
• Créer un bundle d'application sur macOS.

Voir la documentation CMake pour plus d'informations sur ces propriétés de cible.

Structurer les projets

Les projets qui contiennent plus d'une cible bénéficieront d'une structure de fichier claire. Nous utiliserons la fonction de sous-répertoire de CMake.

Comme nous prévoyons d'étendre le projet à d'autres cibles, nous déplaçons les fichiers sources de l'application dans un sous-répertoire et nous y créons un nouveau CMakeLists.txt.

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

Le niveau supérieur CMakeLists.txt contient la configuration générale du projet, les appels find_package et 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)

Les variables définies dans ce fichier sont visibles dans les fichiers de projet des sous-répertoires.

Le fichier de projet de l'application src/app/CMakeLists.txt contient la cible exécutable :

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
)

Une telle structure permet d'ajouter facilement d'autres cibles au projet, telles que des bibliothèques ou des tests unitaires.

Construction des bibliothèques

Au fur et à mesure que le projet se développe, il se peut que vous souhaitiez transformer certaines parties du code de votre application en une bibliothèque utilisée par l'application et, éventuellement, par les tests unitaires. Cette section montre comment créer une telle bibliothèque.

Notre application contient actuellement une logique commerciale directement dans main.cpp. Nous extrayons le code dans une nouvelle bibliothèque statique appelée businesslogic dans le sous-répertoire "src/businesslogic" comme expliqué dans la section précédente.

Pour des raisons de simplicité, la bibliothèque se compose d'un seul fichier source C++ et de son fichier d'en-tête correspondant qui est inclus dans l'application main.cpp:

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

Examinons le fichier de projet de la bibliothèque (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})

Passons en revue le contenu.

qt_add_library(businesslogic STATIC
    businesslogic.cpp
)

La commande add_library crée la bibliothèque businesslogic. Plus tard, nous laisserons l'application établir un lien avec cette cible.

Le mot-clé STATIC désigne une bibliothèque statique. Si nous voulions créer une bibliothèque partagée ou dynamique, nous utiliserions le mot-clé SHARED.

target_link_libraries(businesslogic PRIVATE Qt6::Core)

Nous avons une bibliothèque statique et nous n'avons pas besoin de lier d'autres bibliothèques. Mais comme notre bibliothèque utilise des classes de QtCore, nous ajoutons une dépendance de liaison à Qt6::Core, ce qui permet d'obtenir les chemins d'inclusion et les définitions du préprocesseur nécessaires à QtCore.

target_include_directories(businesslogic INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})

L'API de la bibliothèque est définie dans le fichier d'en-tête businesslogic/businesslogic.h. En appelant target_include_directories, nous nous assurons que le chemin absolu du répertoire businesslogic est automatiquement ajouté comme chemin d'inclusion à toutes les cibles utilisant notre bibliothèque.

Dans main.cpp, cela nous évite d'utiliser des chemins relatifs pour localiser businesslogic.h. Au lieu de cela, nous pouvons simplement écrire

#include <businesslogic.h>

Enfin, nous devons ajouter le sous-répertoire de la bibliothèque au fichier de projet de premier niveau :

add_subdirectory(src/app)
add_subdirectory(src/businesslogic)

Utilisation des bibliothèques

Pour utiliser la bibliothèque que nous avons créée dans la section précédente, nous demandons à CMake d'établir un lien avec elle :

target_link_libraries(helloworld PRIVATE
    businesslogic
    Qt6::Widgets
)

Cela garantit que businesslogic.h est trouvé lorsque main.cpp est compilé. En outre, la bibliothèque statique businesslogic fera partie de l'exécutable helloworld.

En termes de CMake, la bibliothèque businesslogic spécifie les exigences d'utilisation (le chemin d'inclusion) que chaque consommateur de notre bibliothèque (l'application) doit satisfaire. La commande target_link_libraries s'en charge.

Ajout de ressources

Nous voulons afficher des images dans notre application, nous les ajoutons donc en utilisant le système de ressources de Qt.

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

La commande qt_add_resources crée automatiquement une ressource Qt contenant les images référencées. À partir du code source C++, vous pouvez accéder aux images en ajoutant le préfixe de ressource spécifié :

logoLabel->setPixmap(QPixmap(":/images/logo.png"));

La commande qt_add_resources prend comme premier argument soit un nom de variable, soit un nom de cible. Nous recommandons d'utiliser la variante de cette commande basée sur la cible, comme le montre l'exemple ci-dessus.

Ajouter des traductions

Les traductions des chaînes de caractères dans un projet Qt XML sont encodées dans des fichiers .ts. Ces fichiers .ts sont compilés en fichiers binaires .qm, qui sont ensuite chargés par l'application Qt au moment de l'exécution. Voir Internationalisation avec Qt pour plus de détails.

Cette section décrit comment ajouter une traduction allemande et française à l'application helloworld.

Spécifiez les deux langues avec qt_standard_project_setup:

qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

Puis appeler qt_add_translations sur la cible qui doit charger les fichiers .qm:

qt_add_translations(helloworld)

Lors de la première configuration, cette commande crée les fichiers helloworld_de.ts et helloworld_fr.ts dans le répertoire source du projet. Ces fichiers contiendront les chaînes traduites et sont censés être placés sous contrôle de version.

La commande crée également des règles de compilation pour générer automatiquement les fichiers .qm à partir des fichiers .ts. Par défaut, les fichiers .qm sont intégrés dans une ressource et sont accessibles sous le préfixe de ressource "/i18n".

Pour mettre à jour les entrées du fichier .ts, construisez la cible update_translations:

$ cmake --build . --target update_translations

Pour déclencher manuellement la génération des fichiers .qm, créez la cible release_translations:

$ cmake --build . --target release_translations

Pour plus d'informations sur la manière d'influencer le traitement des fichiers .ts et l'intégration dans une ressource, voir la documentation qt_add_translations.

La commande qt_add_translations est une enveloppe de commodité. Pour un contrôle plus fin de la manière dont les fichiers .ts et .qm sont traités, utilisez les commandes sous-jacentes qt_add_lupdate et qt_add_lrelease.

Pour en savoir plus

La documentation officielle de CMake est une source inestimable pour travailler avec CMake.

Le didacticiel officiel de CMake couvre les tâches courantes du système de compilation.

Le livre Professional CMake : A Practical Guide fournit une excellente introduction aux fonctionnalités les plus pertinentes de CMake.