Wprowadzenie
Wykonaj poniższe instrukcje, by dowiedzieć się, jak debugować pliki binarne swojej gry przeznaczonej na system Windows (działającej poprzez Protona) na zestawie deweloperskim Steam Deck. Podczas przesyłania gry do swojego zestawu deweloperskiego musisz załączyć biblioteki wykonawcze systemu Windows do swojej gry, a na twoim komputerze deweloperskim z systemem Windows musi być uruchomiony Visual Studio wraz z narzędziami zdalnego debugowania.
Konfiguracja
Be sure to see
Jak przesyłać gry i uruchamiać je na Steam Decku to upload and run your game on your developer kit. Upewnij się, że dołączysz do niej biblioteki wykonawcze systemu Windows (szczegóły poniżej).
Dołączanie bibliotek wykonawczych systemu Windows:
Biblioteki wykonawcze systemu Windows nie są rozprowadzane wraz z Protonem. Musisz je dołączyć do swojej kompilacji samodzielnie. Zobacz
https://docs.microsoft.com/en-us/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable?view=msvc-160 celem uzyskania szczegółów. Dla programu Visual Studio powinna działać konfiguracja wdrażania debugowania. Właściwości projektu posiadają zaawansowaną opcję „Copy c++ Runtime to OutDir”, która może okazać się pomocna w przypadku projektów C++.
Narzędzia zdalnego debugowania programu Visual Studio w Protonie:
Narzędzia zdalnego debugowania programu Visual Studio nie są rozprowadzane wraz z Protonem. Gdy przesyłasz grę z zaznaczonym polem „Steam Play”, to narzędzie zestawu deweloperskiego skopiuje narzędzia zdalnego debugowania z twojego hosta deweloperskiego w systemie Windows na system zestawu deweloperskiego.
Obecnie zestaw deweloperski będzie szukał zainstalowanych narzędzi debugowania z programów Visual Studio 2019 i Visual Studio 2017. Aby te narzędzia były dostępne, podczas instalacji Visual Studio musisz załączyć pakiet roboczy programowania, np. „Programowanie aplikacji klasycznych w języku C++”.
Użycie
Vulkan – przykłady
Projekt
Vulkan Examples stanowi dobry punkt startowy, by przyzwyczaić się do zdalnego debugowania gier przesłanych na zestaw deweloperski Steam Deck.
Sklonuj projekt i zmień obecny katalog:
git clone --recursive https://gitlab.steamos.cloud/jupiter/vulkan-examples.git
cd vulkan-examples
Projekt zawiera kilka różnych małych próbek Vulkana znajdujących się w katalogu „examples”. W tej dokumentacji skorzystamy z
imgui
w celach demonstracyjnych. Wygeneruj i skompiluj projekt:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows
cmake --build build/windows --config Debug --target imgui
Uwaga: proces kompilacji z użyciem Cmake pobiera dodatkowe zasoby poprzez uruchomienie niedużego skryptu; na twoim hoście z kompilacją będzie ci potrzebny Python.
Utworzy to katalog
build/windows/bin/Debug
zawierający plik wykonywalny
imgui
, wymagane biblioteki debugowania systemu Windows i zasoby danych.
W tym momencie możesz przesłać wynikowy katalog Debug.
Upewnij się, że zaznaczysz „This title requires Steam Play”, gdyż nie jest to natywna kompilacja Linuksa, oraz „Start Visual Studio C++ debugger service on launch”, by włączyć zdalnego debuggera.
Jeśli dołączenie po uruchomieniu twojej gry nie jest adekwatne do sytuacji i chcesz zdebugować uruchomienie oraz inicjalizację twojego tytułu, użyj opcji „Wait for a debug client to attach” i sprawdź sekcję dotyczącą wczesnego dołączenia (tzw. early attach) w tym dokumencie.
Jeżeli przykładowo wybrana przez ciebie nazwa to
vulkan_examples_debug
, to po zakończeniu transferu w bibliotece Steam powinna się znaleźć nowa gra o nazwie
Devkit Game: vulkan_examples_debug
.
Uruchamiając grę, automatycznie uruchomi się również serwer msvsmon do zdalnego debugowania.
Teraz będziesz w stanie dołączyć debugger do uruchomionej gry.
W programie Visual Studio wciśnij
Ctrl+Alt+P
, by otworzyć
Debugowanie > Dołącz do procesu. W polu „Adres docelowy połączenia” wpisz adres IP i port serwera msvsmon, a następnie wybierz proces
imgui.exe
.
Szczegółowe informacje krok po kroku znajdziesz również w
dokumentacji debugowania firmy Microsoft.
Unreal Engine 4 – przykłady
Utwórz konto Epic Games, jeśli go jeszcze nie posiadasz, a następnie
pobierz i zainstaluj Unreal Engine 4.
Wykorzystamy jeden z przykładowych projektów oferowanych przez Unreal Engine Editor. Utwórz nowy projekt i wybierz szablon „Puzzle”.
Wybierz nazwę i lokalizację projektu.
Przejdź do Edit -> Project settings -> Packaging i wybierz "Debug" lub "DebugGame" jako konfigurację kompilacji. Więcej informacji znajdziesz w
oficjalnej dokumentacji. Jeśli zaznaczysz „Include Debug Files”, to pliki debugowania zostaną dołączone do pakietu gry.
Jeżeli nie jesteś w stanie skompilować natywnej kompilacji Linuksa, np. w przypadku, gdy twoja gra posiada zewnętrzne zależności nieobsługujące Linuksa, to możesz rozpocząć kompilowanie dla systemu Windows, używając File -> Package Project -> Windows (64-bit). Utworzy to kompilację w nowym katalogu o nazwie „WindowsNoEditor”.
Prześlij swoją skompilowaną grę, używając programu
SteamOS Devkit Client
.
W bibliotece Steam powinna się znajdować nowa gra o nazwie podobnej do
Devkit Game: puzzle
. Uruchamiając grę, automatycznie uruchomi się również serwer msvsmon do zdalnego debugowania.
W ramach ostatniego kroku możesz teraz dołączyć debugger do uruchomionej gry.
W programie Visual Studio wciśnij
Ctrl+Alt+P
, by otworzyć
Debugowanie > Dołącz do procesu. W polu „Adres docelowy połączenia” wpisz adres IP i port serwera msvsmon, a następnie wybierz proces
puzzle.exe
.
Szczegółowe informacje krok po kroku znajdziesz również w
dokumentacji debugowania firmy Microsoft.
Rozpoczęcie procesu zdalnego debugowania: obsługa „early attach”:
Usługa zdalnego debugowania może zostać skonfigurowana tak, by czekać na dołączenie przez użytkownika przed uruchomieniem tytułu. Umożliwia to ustawienie punktu przerwania w WinMain lub innym kodzie inicjalizacyjnym.
Wymaga to od ciebie wcześniejszej instalacji rozszerzenia firmy Microsoft w programie Visual Studio na twoim hoście deweloperskim:
https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool.
Po zainstalowaniu rozszerzenia włącz debugowanie procesów podrzędnych zgodnie z dokumentacją (Debug > Other Debug Targets > Child Process Debugging Settings).
Zaznacz „Wait for a debug client to attach” w swoim narzędziu devkitowym i prześlij swój tytuł.
Uruchom swój tytuł w normalny sposób.
Podczas dołączania do zdalnego procesu dołącz do
steam.exe
– gdy już to zrobisz, Proton natychmiast uruchomi twój tytuł jako proces podrzędny, a rozszerzenie uruchomi się i zacznie debugować twój tytuł od uruchomienia z włączonymi punktami przerwania.