Vue d'ensemble

Suivez les instructions ci-dessous pour apprendre à déboguer les binaires Windows de votre jeu (exécuté sur Proton) sur un kit de développement Steam Deck. Vous devez associer le runtime de débogage Windows à votre jeu lorsque vous chargez ce dernier sur votre kit de développement. Le débogueur distant de Visual Studio doit être en cours d'exécution dans la fenêtre de développement Windows.

Configuration

Pour savoir comment charger et exécuter des jeux sur votre kit de développement Steam Deck, consultez cet article. Assurez-vous d'associer à votre jeu le runtime de débogage Windows (plus de détails à ce sujet plus loin).

Associer le runtime de débogage Windows

Le runtime de débogage Windows n'est pas fourni avec Proton. Vous devez associer les DLL du runtime de débogage au build de votre application. Pour plus de détails, veuillez consulter la documentation de Microsoft : https://docs.microsoft.com/fr-fr/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable. Pour Visual Studio, un déploiement de débogage effectué depuis le gestionnaire de configuration devrait fonctionner. Les propriétés du projet comportent une option avancée permettant de copier le runtime C++ dans OutDir, qui peut être utile pour les projets C++.

Débogueur distant de Visual Studio dans Proton

Les outils de débogage à distance de Visual Studio ne sont pas fournis avec Proton. Lorsque vous chargez un titre et que Steam Play est activé, l'outil du kit de développement copie les outils de débogage distant depuis l'hôte de développement Windows vers le système du kit de développement.

Actuellement, le kit de développement recherche les outils de débogage installés de Visual Studio 2019 et Visual Studio 2017. Afin d'avoir accès aux outils de débogage distant, assurez-vous d'inclure une charge de travail de développement telle que « Développement Desktop en C++ » lors de l'installation de Visual Studio.

Utilisation

Exemples avec Vulkan

Le projet Vulkan Examples est un bon point de départ pour vous habituer à déboguer à distance les jeux téléchargés sur le kit de développement Steam Deck.

Clonez le projet, puis modifiez le répertoire actuel :

Dans le répertoire « examples » du projet, vous trouverez plusieurs petits échantillons sur Vulkan. Pour les besoins de la documentation, nous utiliserons simplement imgui. Générez le projet :

Remarque : le build Cmake télécharge des ressources complémentaires en exécutant un petit script, vous aurez donc besoin de Python sur l'hôte de votre build.

Un répertoire build/windows/bin/Debug est ainsi créé. Il contient l'exécutable imgui, les DLL de débogage Windows requises et les ressources de données.

Vous pouvez maintenant charger le répertoire « Debug ».

Assurez-vous de sélectionner les options « This title requires Steam Play » (car il ne s'agit pas d'un build Linux natif) et « Start Visual Studio C++ debugger service on launch » pour activer un débogueur distant.

Si vous souhaitez que le débogueur soit associé avant que votre jeu soit lancé, sélectionnez l'option « Wait for a debug client to attach » et consultez la section « Association prématurée » en bas de cet article.



Une fois le transfert terminé, si vous avez par exemple choisi le nom vulkan_examples_debug, vous devriez trouver un nouveau jeu intitulé Devkit Game: vulkan_examples_debug dans votre bibliothèque Steam.

Quand vous lancerez le jeu, un serveur msvsmon de débogage à distance démarrera automatiquement.



Vous êtes enfin en mesure d'associer un débogueur au jeu en cours d'exécution.

Dans Visual Studio, appuyez sur CTRL + ALT + P, ou cliquez sur Déboguer → Attacher au processus. Dans le champ « Cible de la connexion », définissez l'adresse IP et le port du serveur msvsmon, puis sélectionnez le processus imgui.exe.



Pour un guide détaillé étape par étape, vous pouvez suivre la documentation de débogage de Microsoft.

Exemples avec Unreal Engine 4

Créez un compte Epic Games si vous n'en possédez pas déjà un, puis téléchargez et installez Unreal Engine 4.

Comme exercice, nous allons utiliser l'un des exemples de projets proposés par Unreal Editor. Créez un nouveau projet et choisissez le modèle « Puzzle ».



Choisissez un nom et un emplacement pour votre projet.



Rendez-vous dans Edit → Project Settings → Packaging, puis choisissez « Debug » ou « DebugGame », en fonction de la configuration de votre build. Vous trouverez plus d'informations dans la documentation officielle (en anglais). Si vous cochez « Include Debug Files », les fichiers de débogage seront inclus dans le package du jeu.



Si vous ne pouvez pas compiler un build Linux natif (par exemple, si votre jeu a des dépendances externes qui ne prennent pas en charge Linux), vous pouvez lancer un build Windows depuis File → Package Project → Windows (64-bit). Un nouveau répertoire intitulé « WindowsNoEditor » sera ainsi créé, contenant un nouveau build du jeu.

Chargez votre jeu compilé en utilisant SteamOS Devkit Client.



Vous devriez trouver une nouvelle entrée dans la bibliothèque Steam qui devrait ressembler à Devkit Game: puzzle. Un serveur msvsmon de débogage à distance démarrera automatiquement une fois le jeu lancé.

Vous êtes enfin en mesure d'associer un débogueur au jeu en cours d'exécution.

Dans Visual Studio, appuyez sur CTRL + ALT + P, ou cliquez sur Déboguer → Attacher au processus. Dans le champ « Cible de la connexion », définissez l'adresse IP et le port du serveur msvsmon, puis sélectionnez le processus puzzle.exe.

Pour un guide détaillé étape par étape, vous pouvez suivre la documentation de débogage de Microsoft.

Association prématurée du processus de débogage à distance

Vous pouvez faire en sorte que le service de débogage à distance s'associe à votre titre avant qu'il ne soit lancé. Ainsi, vous pourrez définir un point d'arrêt dans WinMain ou tout autre code d'initialisation.

Pour ce faire, vous devez d'abord installer l'extension Visual Studio Microsoft Child Process Debugging Power Tool sur l'hôte de développement.



Une fois l'extension installée, activez le débogage de processus enfant comme indiqué dans la documentation (Débogage → Autres cibles de débogage → Child Process Debugging Settings…).

Dans SteamOS Devkit Client, sélectionnez « Wait for a debug client to attach » et chargez votre titre.

Lancez votre titre normalement.

Au moment d'associer le débogueur au processus distant, choisissez steam.exe. Proton lancera alors immédiatement votre titre sous forme de processus enfant, puis l'extension se chargera et commencera à déboguer votre titre dès son lancement, en prenant en compte vos points d'arrêt.