1 Introduction

Ce document donne des précisions sur l’utilisation de différents outils utilisés durant CSC4526 :

• Analyse des soucis d’utilisation de la mémoire (et en particulier les fuites mémoire)
• cmake
  • Construire un projet C++ avec cmake
  • Ajouter des fichiers source dans un projet géré avec cmake
• Débogueur
• Génération d’une version Release d’un programme
• GoogleTest
• Profileur de performances
• SonarQube

2 Analyse des fuites mémoire (et autres mauvaises utilisations de la mémoire)

Pour analyser les fuites mémoire (et autres mauvaises utilisations de la mémoire), vous disposez de différents outils présentés dans cette section. Pour tester ces outils, vous pouvez vous appuyer sur votre propre projet ou bien utiliser l’archive SoucisMemoire.zip (à exploiter selon la procédure Construire un projet C++ avec cmake).

Le tableau suivant recense, pour chaque analyse souhaitée et pour chaque environnement de développement souhaité (OS et IDE), l’outil recommandé en priorité et, le cas échéant, le (ou les) autre(s) outil(s) que vous pouvez aussi utiliser. Par exemple, si vous êtes sous Windows avec Visual Studio, le tableau ci-dessous vous recommande d’utiliser en priorité l’outil Memory Profiler ou bien d’Autres outils. Cliquez sur le lien pour avoir des explications.

2.1 Sanitizers

Les sanitizers permettent d’ajouter du code à vos sources au moment de leur compilation/édition de liens, grâce à des instructions ajoutées dans votre CMakeLists.txt principal.

• Analyse des fuites mémoire (sanitizer leak, uniquement avec compilateurs gcc et clang, uniquement sous Linux et macOS ; si vous le pouvez, votez ici pour demander l’ajout de cette fonctionnalité à MSVC en environnement Windows).
  Dans votre CMakeLists.txt principal, ajoutez les instructions suivantes entre les lignes set (BUILD_SHARED_LIBS FALSE) et set(CMAKE_CXX_STANDARD 23). Puis, dans votre projet, prenez en compte les changements de CMakeLists.txt, et régénérez complètement votre projet. Ensuite, exécutez votre programme : quand il s’arrête, il affiche les soucis détectés. Si vous exécutez votre programme via CLion :
  • En bas à gauche de votre écran, à droite de l’onglet Console, il y a un onglet Sanitizers qui vous signale des problèmes repérés dans votre code (cf. copie écran CLion ci-dessous).
  • Si vous choisissez d’exécuter la cible All CTests, les tests qui causent la fuite mémoire sont signalés comme ne passant pas (alors que, pourtant, les différents EXPECT ou ASSERT sont corrects). L’onglet Sanitizers permet de comprendre les problèmes.

add_compile_options(-fsanitize=leak)
add_link_options(-fsanitize=leak)

• Analyse des accès illicites (sanitizer address, tous compilateurs et plateformes). NB : Ce sanitizer est sensé permettre de détecter les fuites mémoire sous Linux et macOS, mais les tests que nous avons effectués ont montré que ce n’était pas le cas.
  Procédure identique au sanitizer leak évoqué ci-dessus sauf que les lignes à ajouter dans votre CMakeLists.txt principal sont :

add_compile_options(-fsanitize=address)
add_link_options(-fsanitize=address)

• Analyse de mémoire non initialisée (sanitizer memory, uniquement avec compilateurs gcc et clang, uniquement sous Linux et macOS).
  Procédure identique au sanitizer leak évoqué ci-dessus sauf que les lignes à ajouter dans votre CMakeLists.txt principal sont :

add_compile_options(-fsanitize=memory)
add_link_options(-fsanitize=memory)

• Analyse de comportement indéfini, comme par exemple Signed integer overflow (sanitizer undefined, uniquement avec compilateurs gcc et clang, uniquement sous Linux et macOS).
  Procédure identique au sanitizer leak évoqué ci-dessus sauf que les lignes à ajouter dans votre CMakeLists.txt principal sont :

add_compile_options(-fsanitize=undefined`)
add_link_options(-fsanitize=undefined`)

2.2 Autres outils sous Linux

2.2.1 Valgrind

Installez Valgrind qui est un outil qui permet notamment de détecter beaucoup de problèmes liés à la mémoire. Par exemple, sous Ubuntu : sudo apt install valgrind

Vous pouvez ensuite :

1. Soit ouvrir un terminal, aller dans le répertoire racine de votre projet, taper valgrind repertoire_ou_cmake_travaille/src/main/nom_executable et observer les affichages.
2. Soit, si vous utilisez CLion :
   1. Dans CLion, menu Run > Run ‘unitTests’ with Valgrind Memcheck : la fenêtre Console indique que valgrind a été lancé.
   2. Au bout de quelques secondes, la fenêtre en bas à droite de l’écran indique que les “Tests Results” sont OK. En fait, ceci ne concerne que les tests unitaires qui sont tous OK. SI vous cliquez sur l’onglet “Valgrind” (à côté de l’onglet “Console” actuellement affiché), vous voyez un message Leak-DefinitelyLost 3 Warnings. Si vous dépliez ce message, vous accédez au détail de ces fuites mémoire. En dépliant l’une de ces fuites, vous avez accès à la pile d’appel qui a amené à l’allocation mémoire sans libération associée. En double-cliquant sur l’une des lignes de la pile d’appel (par exemple, dans la figure 1, sur la ligne Group::Group(pugi::xml_node) Group.cpp:15)), vous accédez au code de la ligne qui a fait le new.
3. Soit, si vous utilisez VSCode, cette extension vous permet de lancer Valgrind et d’analyser ses sorties à partir de VSCode.

2.3 Autres outils sous macOS

2.3.1 Leaks

Sous macOS, vous pouvez aussi vous appuyer sur l’outil leaks fourni en standard (cf. cet article).

Dans un terminal, compiler votre programme avec l’option -g (NB: Clion compile votre programme directement avec cette option). Par exemple:

cc -g -Wall -Werror nomFichier.c -o nomFichier

• Tapez la commande :

leaks --atExit --list -- ./nomFichier
# ==> Détection des leaks sans voir leur emplacement précis dans le code

• Tapez la commande :

export MallocStackLogging=1
# Rien ne se passe

• Tapez la commande :

leaks --atExit --list -- ./nomFichier
# ==> Affichage des emplacements précis dans le code

2.4 Autres outils sous Windows

2.4.1 Visual Studio

2.4.1.1 Memory profiler

Par rapport à Valgrind sous Linux, le Visual Studio Profiler est un peu plus compliqué à mettre en oeuvre, mais présente l’avantage de ne pas du tout ralentir l’application profilée.

Cet outil étant disponible en standard dans Visual Studio, il n’y a aucune installation à faire.

Commencez par poser un point d’arrêt au niveau de l’appel à la fonction que vous souhaitez tester. Par exemple, dans le cas d’une application CSC4526, l’appel à la fonction myMain().

Si vous souhaitez voir si vos tests unitaires révèlent des fuites mémoire :

• Posez un point d’arrêt au niveau de la première ligne de votre premier test unitaire (NB : Le point d’arrêt ne dois pas être mis au niveau du nom de votre test unitaire, par exemple TEST(TestAnalyseXML, TestCircle)), mais au niveau de la première ligne de ce test, par exemple std::string s = R"(<?xml version = "1.0"?>),
• Cliquez sur le bouton “Débogueur Windows Local”
• Quand vous êtes arrêté·e au niveau de votre ligne, dans la fenêtre en bas à droite, sélectionnez l’onglet “Pile des appels”. NB : Si Visual Studio n’affiche pas cet onglet, menu Déboguer > Fenêtres > Pile des Appels.
• Recherchez dans cette pile la ligne unitTests.exe!testing::UnitTest::Run() (cf. figure ci-dessous dans laquelle, dans la fenêtre “Pile des appels” en bas à droite, la ligne où est arrêté le débugueur est signalée par une flèche dans un rond rouge, tandis que la ligne sur laquelle on a double-cliqué est signalée par une flèche courbe bleue) et double-cliquez dessus : le code de gtest.cc s’affiche.

• Remontez (par exemple avec la molette de votre souris) dans le code source de gtest.cc jusqu’au début de la fonction dans laquelle le débugueur se trouve (c’est-à-dire int UnitTest::Run()) et posez un point d’arrêt au niveau du début de la définition de cette fonction (cf. figure suivante).

• Dans la fenêtre en bas à droite, sélectionnez l’onglet “Points d’arrêt” et désactivez ou effacez le point d’arrêt de la première ligne de votre test unitaire.
• Cliquez sur l’icône “Redémarrez votre session de debug” (Ctrl+Maj+F5)
• Dans la fenêtre “Outils de diagnostic” à droite (si elle n’est pas affichée, menu Déboguer > Fenêtres > Afficher les outils de diagnostic ou bien Ctrl+Alt+F2)
  • Onglet “Utilisation de la mémoire”
  • Cliquez sur le bouton “Profilage du tas” s’il est grisé.
  • Cliquez sur le lien “activer les instantanés pour commencer le profilage du tas” : le bouton “Prendre un instantané” n’est plus grisé.
  • Cliquez sur le bouton “Prendre un instantané”
• Exécutez maintenant la fonction int UnitTest::Run() (au début de laquelle se trouve le débugueur) en cliquant sur l’icône “Flèche vers le haut” (“Pas à pas sortant”, cf. figure suivante) ou bien Maj+F11.

• Cliquez sur le bouton “Prendre un instantané” : une deuxième ligne d’instantané apparaît dans la fenêtre “Outils de diagnostic” avec des flèches rouge.
• Cliquez sur le lien à gauche de la première flèche rouge : un onglet “Instantané n°2” apparaît (cf. figure suivante)

• Pour chaque type d’objet correspondant à votre code (par exemple, unitTests.exe!Circle) :
  • Double-cliquez sur ce type : vous voyez les différentes instances qui ont été perdues (cf. figure ci-dessous).
  • En dessous, la “Pile des appels d’allocation” vous montre l’endroit où le new a été fait dans le code. Par exemple, dans la figure suivante, les deux premières lignes de la “Pile des appels d’allocation” montrent que :
    • L’allocation mémoire s’est faite au niveau de Group::Group() à la ligne 20 du fichier contenant ce constructeur.
    • Ce constructeur avait été appelé dans TestAnalyseXML_TestGroup_Test::TestBody() à la ligne 38 du fichier contenant ce test.
  • Doublez-cliquez sur l’une de ces lignes visualiser le code source.

2.4.1.2 Autres outils

Voici deux autres outils qui sont disponibles sous Windows et qui peuvent être utilisés par les utilisateurs·trices de Visual Studio, mais aussi de VSCode :

• L’outil Dr. Memory est sensé être un équivalent gratuit de Valgrind sous Windows. Mais nous n’avons pas réussi à le faire fonctionner correctement (message Dr. Memory failed to start the target application, perhaps due to interference from invasive security software. peut-être due à l’outil de sécurité installé sur les machines du campus Télécom SudParis). Nous le mentionnons ici seulement pour que vous ayez l’information et que vous puissiez faire vos propres tests.
• L’outil Deleaker semble être un équivalent commercial de Valgrind sous Windows. Nous ne l’avons pas ni acheté, ni testé, mais le citons ici pour information.

2.4.2 Visual Studio Code (VSCode)

2.4.2.1 Procédure spéciale

A notre connaissance, sous Windows, VSCode ne dispose pas d’outils permettant d’analyser les fuites mémoire (ou autres). Aussi, notre propùosition est de faire que votre VSCode Windows travaille sur un environnement Linux. Deux cas se présentent :

1. Votre Windows héberge une WSL.
2. Votre Windows n’héberge pas de WSM et vous ne voulez pas de WSL.

2.4.2.1.1 Vous disposez de WSL (Windows Subsystem Linux*)

• Si ce n’est déjà fait, suivez la procédure Developing in WSL de manière à avoir une instance de votre VSCode connectée à votre WSL (en bas à gauche de VSCode, “WSL: Ubuntu 24.04” est affiché en bleu).
• Installez les extensions que vous aviez installées pour votre VSCode Windows.
• Allez dans l’onglet terminal.
• Allez dans le répertoire qui vous convient dans votre WSL.
• Récupérez vos fichiers disponibles sous environnement Windows dans votre environnement WSL. Par exemple : commande cp -r /mnt/c/Users/simatic/Cours/CSC4526/MonProjet . ou encore git clone leDepotSSHDeVotreProjet
• Suivez la procédure Visual Studio Code et cmake.
• Utilisez les outils d’analyse recommandés pour Linux.

2.4.2.1.2 Vous n’avez pas de WSL (et vous ne voulez vraiment pas installer WSL)

2.4.2.1.2.1 A faire une seule fois

• Installez vcxsrv (en prenant une version release dans le github vcxsrv
• Sous Windows, ajoutez au fichier .ssh/config (à créer s’il n’existe pas) les lignes suivantes :

Host ssh-tsp
    HostName ssh.imtbs-tsp.eu
    User votreUsernameSurLesMachinesDeSalleTP
    ForwardX11 yes
    ForwardX11Trusted yes

• Suivez la procédure Remote Development using SSH pour vous connecter à l’hôte ssh-tsp.
• Installez les extensions que vous aviez installées pour votre VSCode Windows.
• Allez dans l’onglet terminal.
• Allez dans le répertoire qui vous convient dans votre WSL.
• Récupérez vos fichiers disponibles sous environnement Windows dans votre environnement WSL. Par exemple, commande git clone leDepotSSHDeVotreProjet
• Dans le fichier source qui contient la définition de la fenêtre d’affichage (exemple de code : sf::RenderWindow window{sf::VideoMode({300, 300}), "SFML works!"};), ajoutez derrière cette ligne l’instruction window.setPosition(sf::Vector2i{0, 0}); (ainsi, votre fenêtre s’affichera bien sur votre écran Windows).

2.4.2.1.2.2 A faire à chaque fois que vous voulez faire des tests

• Sous Windows, exécutez vcxsrv.exe (vous le trouverez dans le répertoire C:\Program Files\VcXsrv) : Une grande fenêtre noire s’affiche.
• Lancez un PowerShell
  1. Tapez-y la commande echo $env:DISPLAY. Si cette commande ne vous renvoie rien, tapez la commande $env:DISPLAY = "localhost:0"
  2. Tapez maintenant la commande ssh ssh-tsp : Le prompt change pour vous dire que vous êtes sur une machine de l’école.
  3. Tapez xeyes pour vérifier que des yeux se sont affichés dans votre grande fenêtre noire.
  4. Appuyez sur Ctrl + C pour arrêter xeyes.
  5. Tapez la commande echo $DISPLAY. Une réponse semblable à localhost:10.0 s’affiche. Notez la.
• Dans l’onglet terminal de votre VSCode connecté à ssh-tsp, tapez la commande export DISPLAY=localhost:10.0 (adaptez la commande en fonction du résultat que vous avez eu ci-dessus).
• Suivez la procédure Visual Studio Code et cmake : Votre application devrait s’afficher.
• Utilisez les outils d’analyse recommandés pour Linux.

3 cmake

Tous les canevas de projet C++ fournis dans le cadre de CSC4526 s’appuient sur cmake. cmake permet de configurer l’environnement du projet, ce qui dispense de configurer l’IDE (concernant les dépendances, la version du standard C++ compilateur, etc.).

Nous décrivons ici :

• Construire un projet C++ avec cmake
• Ajouter des fichiers source dans un projet généré par cmake

3.1 Construire un projet C++ avec cmake

3.1.1 Instructions et informations communes à tous les IDE/OS

• Décompressez l’archive fournie (par exemple, SampleSFML.zip dans l’exercice d’introduction) dans le répertoire de votre choix.
  • Attention : Le chemin qui mène à votre répertoire ne doit pas contenir de nom contenant le caractère espace ou bien un accent. Par exemple, sous Windows, C:\Users\Barnabé\Mes Documents\CPP est à bannir à cause du é dans Barnabé et de l’espace dans Mes Documents ; il vaut mieux que le chemin soit C:\CPP. Si vous ne respectez pas ce conseil, votre IDE risque de recompiler systématiquement l’ensemble de votre projet.
• Renommez le répertoire racine du répertoire que vous venez d’extraire (par exemple, SampleSFML)
• Dans le fichier nouveau_nom_du_répertoire_racine\CMakeLists.txt, au niveau de la ligne project(nom_projet VERSION 1.0.0 LANGUAGES CXX), remplacez nom_projet par un nom (sans espace) qui correspond à votre projet.
• Passez maintenant à la section correspondant à votre IDE/OS :
  • CLion (Linux) et cmake
  • CLion (MacOS) et cmake
  • Visual Studio (Windows) et cmake
  • Visual Studio Code et cmake

A titre d’information, voici les temps de chargement du dossier (génération de la structure du projet) et de compilation/édition de lien du projet observés en 2024-2025 avec SampleSFML.zip, donc SFML 3.0.0 :

3.1.2 CLion (Linux) et cmake

• Dans CLion, Menu File > Open et sélectionnez chemin_absolu_vers_votre_projet/CMakeLists.txt. Cliquez sur “OK” : Une fenêtre “Open Project” apparaît. Cliquez sur “Open as Project”
• Etape intermédiaire requise à partir de CLion 2022.1
  • Une fenêtre “Open Project Wizard” s’affiche. Notez que son champ Generator vous dit, par défaut, Use default Ninja
  • Ninja est un système de build, comme make. a priori, CLion l’a installé pour son usage personnel. Si ce n’est pas le cas :
    • Si vous avez besoin de l’installer, tapez sudo apt-get install -y ninja-build (cf. ce site).
    • Si vous ne souhaitez pas l’installer, sélectionnez dans le champ Generator : Unix Makefiles ou Let CMake decide
  • Cliquez ensuite sur le bouton “OK”.
• Le chargement de votre projet devrait s’effectuer correctement dans CLion, sauf si c’est la première fois que vous effectuez cette opération dans le contexte de CSC4526 et que votre projet utilise la bibliothèque SFML. Dans ce cas, dans un terminal :

cd chemin_absolu_vers_votreRépertoireProjet
rm -Rf .idea build cmake-build-debug
cmake -B build
#
# Si cmake affiche l'une des messages suivants:
#    - "cmake not found"
#    - "Error during cmake"
#    - "No CMAKE_CXX_COMPILER"
#    - "Could NOT find X11"
# Alors tapez la commande suivante (qui est sur plusieurs lignes) :
#
sudo apt update && sudo apt install -y \
    g++ \
    cmake \
    libxrandr-dev \
    libxcursor-dev \
    libxi-dev \
    libudev-dev \
    libflac-dev \
    libvorbis-dev \
    libgl1-mesa-dev \
    libegl1-mesa-dev \
    libdrm-dev \
    libgbm-dev \
    libfreetype-dev
# Au final, vous devriez obtenir le message "-- Build files have been written to: absolute_path_to_your_project". Cela signifie que toutes les installations préalables pour Linux sont OK.
#
# Il vous reste à nettoyer votre répertoire de votre test cmake:
rm -Rf build

• Si vous avez dû faire toutes ces manipulations dans un terminal, dans CLion, menu Build > Rebuild Project
• Menu Build > Build Project : Cette opération peut prendre un certain temps, notamment si votre projet utilise SFML et que donc CLion doit télécharger le projet SFML. Enfin, CLion affiche “Build finished” : tout s’est bien passé.
• Menu Run > Run ‘sample’ : la fenêtre de message affiche des informations de compilation (cette première compilation peut prendre du temps car CLion doit recompiler des fichiers de bibliothèques). Notamment, dans le cas de l’exemple SampleSFML), une fenêtre “SFML works !” semblable à la fenêtre ci-dessous s’ouvre:

• Cliquez sur la croix à droite de cette fenêtre pour terminer votre programme.

3.1.3 CLion (MacOS) et cmake

3.1.3.1 Démarche préliminaire pour les utilisateurs·trices de Mac avec processeur M1 (ARM)

Dans un terminal, tapez la commande which brew pour vous assurer d’avoir la version de Homebrew adaptée à l’architecture ARM de votre processeur : Si la version de Homebrew est adaptée à ARM, le chemin affiché devrait commencer par /opt/homebrew/. Si le chemin affiché commence par /usr/local/, votre version de Homebrew est adaptée à un processeur Intel (ce qui vous posera des soucis lorsque CLion fera des éditions de liens) : Il vous faut installer un Homebrew adapté à ARM (cf. procédure un peu modifiée de la 1ère réponse ici) :

• brew bundle dump pour créer un Brewfile des packages déjà installés.
• (facultatif) Désinstallez Homebrew
• Installez Homebrew pour ARM

cd /opt
sudo mkdir -p homebrew
sudo chown -R $(whoami) homebrew
curl -L https://github.com/Homebrew/brew/tarball/master |\
    tar xz --strip 1 -C homebrew
#+end_src
- Modifiez *PATH*
#+begin_src bash
PATH=/opt/homebrew/bin:$PATH

• Réinstallez les packages (en tout cas, ceux qui sont disponibles) avec le Brewfile

hash -d brew
brew bundle install --file /path/to/Brewfile

3.1.3.2 Démarche pour tous les utilisateurs·trices de MacOS

• Dans CLion, Menu File > Open et sélectionner chemin_absolu_vers_votre_projet/CMakeLists.txt. Cliquez sur “OK” : Une fenêtre “Open Project” apparaît. Cliquez sur “Open as Project” :
  • Etape intermédiaire requise à partir de CLion 2022.1
    • Une fenêtre “Open Project Wizard” s’affiche. Notez que son champ Generator vous dit, par défaut, Use default Ninja
    • Ninja est un système de build, comme make. a priori, CLion l’a installé pour son usage personnel. Si ce n’est pas le cas :
      • Si vous avez besoin de l’installer, tapez brew install ninja (cf. ce site).
      • Si vous ne souhaitez pas l’installer, sélectionnez dans le champ Generator : Unix Makefiles ou Let CMake decide
    • Cliquez ensuite sur le bouton “OK”.
  • Le chargement de votre projet devrait maintenant s’effectuer correctement dans CLion. Si ce n’est pas le cas, c’est que vous êtes dans le contexte d’une première utilisation de cmake dans le contexte CSC4526 :
    • Dans un terminal, tapez la commande brew install sfml
    • Dans CLion, menu Build > Rebuild Project
• Pour exécuter une application :
  • Menu Run > Run ‘sample’ : la fenêtre de message affiche des informations de compilation (cette première compilation peut prendre du temps car CLion doit recompiler des fichiers de bibliothèques). Notamment, dans le cas de l’exemple SampleSFML), une fenêtre “SFML works !” semblable à la fenêtre ci-dessous s’ouvre:

3.1.4 Visual Studio (Windows) et cmake

• Dans Visual Studio, menu Fichier > Ouvrir > Dossier : une fenêtre “Sélectionner un dossier” s’ouvre.
• Sélectionner le répertoire de votre projet et cliquez sur “Sélectionner un dossier” : la fenêtre de sortie de Visual Studio que l’IDE travaille et vous affiche à la fin “Fin de la génération de CMake.”. NB :
  • Cette opération peut prendre un certain temps, notamment si votre projet utilise SFML et que donc Visual Studio doit télécharger le projet SFML
  • Si jamais cmake vous affiche – Configuring incomplete, errors occurred! et que, parmi les messages que cmake vous affiche, vous voyez error: could not find git for clone of sfml-populate ou bien qu’il y a eu des soucis avec un git clone, c’est que git n’est pas installé sur votre machine ou bien qu’il n’est pas assez récent.
    • Installez la dernière version de Git for windows.
    • Arrêtez et redémarrez Visual Studio
    • Recommencez cette procédure
  • cmake vous affiche éventuellement un warning concernant pugixml : ce warning est normal.
• Menu Générer > Tout générer
• Quand la génération est terminée, cliquez gauche sur la droite du bouton “Sélectionner un élément de démarrage” (2ème ligne de la barre de menu) et sélectionnez “sample.exe”, “mainLauncher.exe” ou “unitTests.exe”
• Cliquez sur ce bouton (ou Ctrl-F5) pour lancer l’application choisie : votre programme s’exécute. Notamment, dans le cas de l’exemple SampleSFML, la fenêtre suivante s’affiche pour vous signifier que SFML fonctionne.

• Cliquez sur la croix à droite de cette fenêtre pour terminer votre programme.
• Dans la “Console de débogage Microsoft Visual Studio”, appuyez sur une touche pour fermer cette console.

Pour information, cette procédure crée les répertoires .vs et out dans le répertoire de votre projet.

3.1.5 Visual Studio Code et cmake

Nous déroulons la procédure expliquée ici :

• Si ce n’est déjà fait, installez git, un compilateur, un debugger, make et cmake (cf. la section “Installations préliminaires” de la documentation de l’installation de Visual Studio Code).
• Dans Visual Studio Code, menu File > Open Folder.
• Sélectionnez le dossier de votre projet : Votre projet s’affiche et une fenêtre No Kit Selected apparaît.
• Sélectionnez le compilateur avec lequel vous souhaitez travailler : La fenêtre “Output” indique que *Visual Studio Code” est en train d’exécuter cmake.
• Quand il a fini, cliquez sur “Build” dans la barre d’état en bas OU BIEN appuyer sur la touche F7.
• Quand la génération de votre programme est terminée, vous pouvez cliquer sur le bouton “Run” ou Shift+F5 (Pour débugger votre programme, cliquez sur le bouton “Bug” ou Ctrl+F5 ; pour information, cela prend plusieurs secondes sous Windows). Selon le projet cmake que vous avez ouvert, il se peut que vous ayez à choisir l’exécutable à exécuter. Le cas échéant, choisissez l’exécutable qui ne s’appelle pas unitTests : La fenêtre suivante s’affiche pour vous signifier que SFML fonctionne.

3.2 Ajouter des fichiers source dans un projet géré avec cmake

Pour les premiers canevas de projet que vous utiliserez dans CSC4526, vous aurez juste à modifier des fichiers source déjà fournis dans le canevas.

Puis, vous serez amené·e à ajouter des fichiers sources, ce qui requiert une procédure particulière décrite ci-dessous :

• Pour CLion, vous pouvez utiliser les menus de création de .h et de .cpp. NB : CLion modifie src/core/CMakeLists.txt pour y ajouter le nom des fichiers ajoutés.
• Pour Visual Studio, nous supposons que votre projet est un projet à base de CMakeLists.txt :
  • Dans l’explorateur de solutions, cliquez droit sur src/core, puis cliquez gauche sur Ajouter > Ajouter un nouvel élément… : une fenêtre “Ajouter un nouvel élément src” s’ouvre.
  • Dans le cadre de gauche, sélectionnez “Visual C++”, puis le type de fichier que vous voulez créer. Enfin, cliquez sur le bouton “Ouvrir” : votre fichier est créé dans le répertoire src/code
  • Indiquez son nom : Une fenêtre “Aperçu des changements - CMake” apparaît
  • Cliquez sur le bouton “OK” pour ajouter votre nouveau source à votre fichier src/core/CMakeLists.txt.
• Pour Visual Studio Code :
  • Dans la colonne des extensions, cliquez sur l’icône “Explorateur de fichier” (ou Ctrl+Shift+E) : L’explorateur s’ouvre.
  • Dans la section correspondant à votre projet cmake, dépliez le dossier dans lequel vous souhaitez créer votre fichier, cliquez droit et choisissez “New file…”. Une fenêtre apparaît pour que vous donniez un nom à votre fichier.
  • Indiquez le nom et appuyez sur “Entrée” : Le fichier est créé.
  • Ouvrez le fichier CMakeLists.txt du dossier où a été créé le fichier. Ajoutez-y le nom du fichier créé au niveau des autres noms de fichiers mentionnés dans le CMakeLists.txt.
  • Sauvez votre fichier CMakeLists.txt : Cela déclenche une nouvelle exécution de cmake pour prendre en compte vos modifications.

4 Débogueur

Cette section retranscrit le contenu des vidéos de tutoriel sur le débogage :

• Initiation au débogage de programme avec Visual Studio
• Initiation au débogage de programme avec CLion

Ces vidéos utilisent le fichier ExempleDeDebugDeProgramme.cpp

4.1 Initiation au débogage de programme avec CLion

• Vidéo des manipulations ici.
• Fichier exemple ici

Les manipulations ont été effectuées en s’appuyant sur le scénario Visual Studio ci-dessous. Pour information, CLion ne permet pas de mettre en place un arrêt quand la valeur d’une variable change (il faut taper manuellement la commande gdb watch dans la console gdb fournie par CLion).

4.2 Initiation au débogage de programme avec Visual Studio

• Vidéo des manipulations ici.
• Fichier exemple ici

4.2.1 Introduction au débogage

Dans ce tutoriel vidéo, je vous propose une initiation aux principales fonctions de débogage offertes par Visual Studio. Vous pourrez ainsi gagner en efficacité et en rapidité dans la mise au point de vos programmes, qu’ils soient écrits en C++ ou dans d’autres langages. En effet, les notions présentées ici sont génériques à tous les langages de programmation.

Notez que, pour ce tutoriel, nous nous appuierons sur le fichier ExempleDeDebugDeProgramme.cpp que je vous invite à télécharger maintenant, si vous ne l’avez pas déjà fait.

4.2.2 Mise en place de l’environnement

1. Création d’un projet console
2. Recopie du code pour debugging

4.2.3 Déboguer un plantage qui ne semble pas dans notre code

1. Menu Déboguer > Exécuter sans débogage
2. La fenêtre affiche Expression: vector subscript out of range
3. Vu que la fenêtre dit Please retry to debug the application, clic sur Recommencer
4. Expliquer affichage “Windows recherche une solution au problème” (pour info, MacOS a le même comportement). Le pb ne vient pas de votre OS ou de votre IDE (VisualStudio), mais bien de votre application !
5. Cliquer sur “Déboguer” : patienter (environ 20 secondes).
6. Choisir l’instance courante : vous arrivez dans le menu de debug.
7. Nous pourrions commencer le débogage. Mais, pour vous montrer qu’on peut s’économiser le temps d’attente qu’on vient de vivre, voyons ce qui se passe si on lance notre programme directement en débogage.
8. Faisons le ménage et démarrons maintenant en mode debug, par exemple en cliquant sur le bouton “Débogueur Windows Local” ou bien en appuyant sur la touche F5
9. La fenêtre affiche toujours Expression: vector subscript out of range.
10. Vu que la fenêtre dit Please retry to debug the application, clic sur Recommencer
11. On arrive directement dans VisualStudio, dans le code du module vector qui affiche vector subscript out of range
12. Dans le cadre en bas à droite, sélectionner l’onglet “Pile des appels” (NB : Si Visual Studio n’affiche pas cet onglet, menu Déboguer > Fenêtres > Pile des Appels) : la flèche montre où est arrêté votre programme.
13. Double-cliquez sur la ligne juste en dessous : vous êtes à votre ligne de code qui a appelé vector et qui a généré le souci.
14. Sélectionnez v.size : VS vous affiche 4.
15. Sélectionnez v et cliquez sur la flèche pour voir le contenu de v : il y a 4 éléments. NB : on peut aussi voir le contenu de v dans le cadre des variables locales en bas à gauche (si Visual Studio n’affiche pas cet onglet, menu Déboguer > Fenêtres > Automatique).
16. OK, nous comprenons le bug : ajoutons le -1 et cliquons sur le bouton “Redémarrer”

4.2.4 Pas à pas

1. Nous obtenons une erreur, plus loin : division par zéro. Effectivement c vaut 0 (qui ne fait pas bon ménage avec l’opérateur modulo).
2. Pour comprendre comment c s’est retrouvé avec la valeur 0, mettons un point d’arrêt au niveau de la définition de c, puis exécutons pas à pas le programme.
3. Arrêter le programme
4. Clic droit, Exécuter jusqu’au curseur
5. Bouton “Pas à pas principal” (y compris au-dessus de l’appel à unCalcul()) ==> Zut, la valeur de c a changé.
6. Exécuter jusqu’au curseur de l’appel à unCalcul()
7. Bouton “Pas à pas détaillé” ==> Vous rentrez dans unCalcul()
8. Faire “Aperçu de la définition” ==> On voit l’origine du problème.

4.2.5 Pose d’un point d’arrêt conditionnel

1. Insérer un point d’arrêt au niveau du return resultat
2. Dans le cadre en bas à droite, clic sur l’onglet “Points d’arrêt”
3. Clic-droit sur le point d’arrêt, Paramètres
4. Clic sur Conditions, resultat == 0
5. Redémarrez
6. Désactivez ce point d’arrêt

4.2.6 Arrêter l’exécution quand la valeur d’une variable change

1. Exécutez jusqu’à ce que la variable c soit définie.
2. Dans le cadre des variables locales (si Visual Studio n’affiche pas cet onglet, menu Déboguer > Fenêtres > Automatique), clic-droit sur c et “Arrêtez quand la valeur change”. Notez que la variable a change aussi de couleur (vu que c est une référence vers a).
3. Cliquez sur “Continuer” ==> Arrêt quand a (et donc c) change.
4. Hélas, si vous cliquez sur “Redémarrez”, le programme ne s’arrête pas sur le changement de c : il faut programmer un nouveau point d’arrêt pour cette variable.

4.2.7 Nettoyage de tous les points d’arrêt

1. Menu Déboguer > Supprimer tous les points d’arrêt

4.2.8 Conclusion

Nous voici arrivés à la fin de cette initiation au débogage sous Visual Studio : n’hésitez pas à faire vos propres expériences pour vous familiariser avec cet outil et ainsi gagner en efficacité et en rapidité dans la mise au point de vos programmes.

4.3 Initiation au débogage de programme avec Visual Studio Code

TODO : A compléter.

5 Génération d’une version Release d’un programme

La version Release d’un programme est une version sans information de debug, donc plus rapide à l’exécution. Cette section décrit comment la générer :

• Sous CLion
  • Menu File > Setting : Une fenêtre de “Settings” s’ouvre.
  • Sélectionnez Build, Execution, Deployment > CMake : Le sous-menu CMake s’ouvre.
  • Dans la colonne de gauche des profils, là où il n’y a que la mention Debug, cliquez sur le bouton “+” : Un item Release est créé.
  • Patientez un peu le temps que le projet se génère en mode Release.
  • Dans la liste déroulante des exécutables, vous pouvez maintenant sélectionner Release, puis sélectionner main | Release.
• Sous Visual Studio
  • Dans la barre de menu, cliquez sur la flèche à droite de x64-Debug et sélectionnez Gérer les configurations : Un onglet CMakeSettings.json s’ouvre.
  • Dans cet onglet, dans Configurations, cliquer sur le bouton “+” et sélectionnez x64-Release/
  • Fermez l’onglet CMakeSettings.json (et enregistrez-le).
  • Dans la barre de menu, sélectionnez x64-Release à la place de x64-Debug : Votre projet est généré en mode Release/
• Sous Visual Studio Code
  • Dans la colonne des extensions, cliquez sur l’icône “CMake” : Un onglet “CMake” s’ouvre. Il contient 3 arborescences :
    • PROJECT STATUS
    • PROJECT OUTLINE
    • PINNED COMMANDS
  • Dépliez l’arborescence “PROJECT STATUS”. Dans la sous-arborescence “Configure”, allez sur “Debug” et cliquez sur le crayon qui vient d’apparaître : En haut et au milieu de l’écran, apparaissent les “Build variant”.
  • Sélectionnez “Release” : cmake régénère votre projet.

6 GoogleTest au sein de votre IDE

GoogleTest est un environnement facilitant l’écriture et le passage de tests unitaires. Cette section présente l’utilisation de GoogleTest selon l’IDE que vous utilisez. Nous supposons ici que vous avez déjà appliqué cmake sur un canevas de projet contenant des tests unitaires.

6.1 CLion (Linux ou MacOS) et GoogleTest

• Menu Build > Build Project : la fenêtre de sortie montre le travail de CLion, puis affiche “Build finished”
• Dans la 2^ème ligne de menu, cliquez sur la flèche vers le bas à droite de la petite fenêtre contenant main | Debug : une fenêtre avec de nombreuses configuration s’affiche.
• Sélectionnez unitTests : l’icône Google suivie de unitTest | Debug s’affiche désormais dans la petite fenêtre de la 2^ème ligne de menu.
• clic sur le triangle vert à droite de cette petite fenêtre OU BIEN Menu Run > Run ‘unitTests’ : en bas de l’écran, le résultat du test est affiché avec une synthèse (que vous pouvez déplier) dans le cadre gauche.
• Si le test révèle une erreur, dans le cadre à droite, cliquez sur le lien bleu signalant la ligne en erreur : CLion ouvre le fichier unitTests.cpp au niveau du test unitaire en erreur.

6.2 Visual Studio (Windows) et GoogleTest

• Menu Test > Exécuter tous les tests : une fenêtre “Explorateur de tests” apparaît.

  • Si cette fenêtre ne vous affiche aucun test, mais le message “Générez votre solution pour découvrir tous les tests disponibles”, vérifiez que votre CMakeLists.txt racine contient les trois dernières lignes suivantes :

    include(GoogleTest)
    enable_testing()
    add_subdirectory(src/tests)

  • Si la ligne include(GoogleTest) manque, ajoutez-la et supprimez-la du fichier unitTests/CMakeLists.txt où elle doit encore apparaître.

  • Si elle ne manque pas, régénérez tout votre projet (Menu Projet > Supprimer le cache et reconfigurer) avec la fenêtre “Explorateur de test” ouverte.

  • Si cette fenêtre “Explorateur de tests” n’affiche toujours pas vos tests, prévenez Michel Simatic pour qu’il voit ce qui peut être fait (Ce ticket ne serait pas corrigé).

• Menu Test > Exécuter tous les tests (ou clic sur l’icône en haut à gauche de l’explorateur de tests) : une fenêtre “Explorateur de tests” apparaît. Au bout de quelques secondes, une croix rouge apparaît devant la ligne unitTests (1) : vous avez passé votre premier test unitaire sur votre application.
• Si un test révèle une erreur, dans l’explorateur de tests, dépliez la ligne unitTest (1) et double-cliquez sur la ligne terminale TestName : Visual Studio ouvre le fichier unitTests.cpp au niveau du test unitaire en erreur (et l’explorateur de tests explicite l’erreur dans la sous-fenêtre à droite “Récapitulatif des détails du test”)
• Très important : Si, après avoir fait une séance de tests, vous modifiez le nom/sous-nom d’un test ou bien que vous ajoutez de nouveaux tests, il faut penser à faire menu > Tout générer, pour que vos mises à jour soient prises dans l’explorateur de tests.

6.3 Visual Studio Code et GoogleTest

• Si vous ne l’avez pas déjà fait, installez l’extension “GoogleTest Adapter”.
• Dans la colonne des extensions, cliquez sur l’icône “Testing” (une sorte de bécher) correspondant à l’extension “GoogleTest Adapter” : Un onglet “TESTING” s’ouvre.
• Au niveau du titre “TESTING” de cet onglet, cliquez sur l’icône “Run Tests” ou “Debug Tests” à votre convenance : Vos tests unitaires s’exécutent et leur résultat s’affiche.
• La fenêtre “OUTPUT” vous donne plus de précisions sur les tests exécutés : la ligne du test dans le code source et la raison de l’échec pour les tests échoués. Par exemple :

[ctest] [ RUN      ] choisir_carte.strategie_kCarte_la_plus_petite
[ctest] C:\temp\CSC4526\SixQuiPrend\src\test\unitTests.cpp:20: Failure
[ctest] Expected equality of these values:
[ctest]   cartes_t({4, 6})
[ctest]     Which is: { 4, 6 }
[ctest]   j.main
[ctest]     Which is: { 2, 4, 6 }

• Pour information, si jamais vous voulez lancer manuellement l’exécutable correspondant à vos tests unitaires :
  • Dans la colonne des extensions, cliquez sur l’icône “CMake” : Un onglet “CMake” s’ouvre. Il contient 3 arborescences :
    • PROJECT STATUS
    • PROJECT OUTLINE
    • PINNED COMMANDS
  • Dépliez l’arborescence “PROJECT STATUS”.
    • Dans la sous-arborescence “Configure”, vérifiez que vous êtes bien en “Debug”
      • Si ce n’est pas le cas (vous êtes en “Release”), allez sur “Release” et cliquez sur le crayon qui vient d’apparaître : En haut et au milieu de l’écran, apparaissent les “Build variant” : Sélectionnez “Debug” : cmake régénère votre projet.
    • Pour chacune des sous-arborescences “Debug” et “Launch”
      • Vérifiez que c’est “uniTests” qui est mentionné. Si ce n’est pas le cas, avec votre souris, allez sur le nom de l’exécutable mentionné et cliquez sur le crayon qui vient d’apparaître : En haut et au milieu de l’écran, apparaissent les “launch target” disponibles.
      • Sélectionnez “unitTests”
  • Ainsi, désormais, quand vous cliquez sur le bouton “Run” ou Shift+F5 (ou alors le bouton “Bug” ou Ctrl+Shift+F5), vous exécutez vos tests unitaires dont les résultats apparaissent dans la fenêtre “TERMINAL” de VSCode.

7 Profileur de performances

Le profileur de performances permet de repérer les sections de code où votre programme passe du temps.

• Sous CLion
  • TODO A compléter en s’inspirant de la documentation Profiler CLion.
• Sous Visual Studio
  • Menu Déboguer > Profileur de performances… : Une fenêtre “Session de diagnostic” s’ouvre.
  • Cliquez sur le bouton “Changer la cible” et sélectionner “Exécutable”.
  • Choisissez le chemin DossierDeVotreProjet > out > build > x64-Release > src > main, puis votre exécutable (par exemple, main_optimise.exe) et OK.
  • Cliquez sur l’option “Utilisation de l’UC”.
  • Cliquez sur le bouton “Démarrer”
  • Pour plus d’informations, voir la documentation Profiler Visual Studio
• Sous Visual Studio Code
  • TODO A compléter

8 SonarQube

• Une fois que SonarQube est installé dans votre IDE (cf. procédure d’installation), à chaque fois que vous ouvrez ou sauvegardez un fichier source, ce fichier sera analysé par SonarQube. Les problèmes détectés sont listés dans la fenêtre d’erreur de l’IDE, sous la forme de warnings.
• Si vous souhaitez désactivez certains warnings SonarQube (par exemple, le warning S106: Replace this usage of std::cout by a logger qui est trop complexe à résoudre pour nos applications “jouet”), cliquez droit sur la règle (pour VisualStudio dans la fenêtre d’erreur, pour CLion dans la sous-fenêtre SonarQube, pour VSCode dans la fenêtre “PROBLEMS”) et sélectionnez “Disable SonarQube rule”.
• Si vous souhaitez réactiver une règle :
  • Pour CLion
    • Menu Window > Editor Tabs > Configure Editor Tabs: Une fenêtre Settings s’ouvre.
    • Cherchez SonarQube et sélectionnez celui qui est dans le sous-menu Tools.
    • Cliquez sur l’onglet Rules, puis C++. Cliquez sur le bouton Filter et sélectionnez Show only Changed.
    • Réactivez la règle souhaitée.
  • Pour VisualStudio
    • Menu Outils > Options: Une fenêtre Options s’ouvre.
    • Dans le champ de recherche, tapez SonarQube: Un sous-menu SonarQube apparaît.
    • Sélectionnez Général et cliquez sur le bouton Edit rules settings: Un fichier settings.json s’ouvre dans l’explorateur de fichier.
    • Remplacez “Off” par “On” sur la règle que vous souhaitez réactiver et sauvegardez le fichier.
  • Pour Visual Studio Code
    • Dans la colonne des extensions, cliquez sur l’icône “SonarQube”: Un onglet “SONARQUBE” s’ouvre.
    • Dépliez l’arborescence “RULES” de cet onglet. Retrouvez-y la règle désactivée et réactivez-la.

8.1 Session CSC4526 2023-2024 : Résoudre un bug lié à la combinaison Visual Studio version 17.9.6 / cmake / SonarQube

Pour la session CSC4526 2023-2024, un bug lié à la combinaison Visual Studio version 17.9.6 / cmake / SonarQube est apparu quelques jours avant le début de ce cours. Il empêche que SonarQube affiche ses messages dans Visual Studio.

8.1.1 Constatation du bug

Voyons tout d’abord si vous êtes concerné·e par ce bug :

• Dans Visual Studio, Outils > Ligne de commande > PowerShell développeur : Une fenêtre PowerShell s’ouvre.

• Tapez la commande cmake --version : La version de cmake s’affiche.

• Si la version affichée est cmake version 3.28.0-msvc1, vous êtes concerné·e par le bug, ce qui explique que vous avez peut-être vu le message SonarQube: Failed to analyze <nomFichier>. See the Output Window for more information (en bas à gauche).

  

• D’ailleurs, dans l’onglet “Sortie” en bas de l’écran, si vous sélectionnez “SonarQube” à la place de “CMake” dans la combo box “Afficher la sortie à partir de :”, vous voyez le message :

  [CLangAnalyzer] Analyzing C:\temp\CSC4526\SampleGoogleTest\unitTests\unitTests.cpp
  [CFamily Analysis] Unsupported configuration: Unexpanded response file is not supported:@unitTests\CMakeFiles\unitTests.dir\unitTests.cpp.obj.modmap.
  [CLangAnalyzer] Failed to analyze C:\temp\CSC4526\SampleGoogleTest\unitTests\unitTests.cpp: See above for more information.

8.1.2 Correction du bug

Cet article indique la démarche pour résoudre ce bug :

• Installez la dernière version de cmake (3.29.2) à partir d’ici.
  • Installez cette version dans le répertoire par défaut qui est proposé (C:\Program Files\CMake\bin).
  • Pensez à indiquer que vous souhaitez que le PATH de l’utilisateur (vous pouvez aussi indiquer “tous les utilisateurs”) soit modifié pour inclure le chemin vers ce cmake.
• Dans Visual Studio, Outils > Options > CMake > Général : La fenêtre des options générales de “Cmake” s’affiche.
• Descendez un peu dans cette fenêtre, cochez “Activer l’exécutable CMake personnalisé”, indiquez le chemin “C:Files” et cliquez sur “OK”.
• Attendez que votre projet soit régénéré.
• Redémarrez Visual Studio pour que soit prise ne compte la nouvelle valeur de la variable d’environnement PATH avec le chemin vers cmake installé : Le bug ne devrait plus se manifester.
• NB Si vous aviez un projet sur lequel vous aviez déjà appliqué la procédure de prise en compte de CMakeLists.txt, vous devez faire régénérer votre projet ==> menu “Projet > Supprimer le cache et reconfigurer” pour que VisualStudio applique le CMakeLists.txt avec le nouveau cmake.