Introduzione
Le seguenti istruzioni ti insegneranno come effettuare il debug dei binari Windows del tuo gioco (in esecuzione tramite Proton) su un dev kit di Steam Deck. Il runtime di debug di Windows dovrà essere associato al tuo gioco quando lo carichi sul dev kit, mentre Visual Studio e gli strumenti di debugging remoto dovranno essere in esecuzione sul tuo ambiente di sviluppo Windows.
Questa funzionalità è ancora in fase di sviluppo. Per qualsiasi commento o problema, ti invitiamo a usare il
forum degli sviluppatori di Steam Deck.
NOTA: le funzionalità di debugging remoto sono compatibili esclusivamente con Proton Experimental.
Configurazione
Per caricare ed eseguire il tuo gioco sul dev kit, consulta il seguente articolo:
Come caricare ed eseguire i giochi su Steam Deck. Assicurati di associare il runtime di debug di Windows (ulteriori dettagli in basso).
Associare il runtime di debug di Windows
Il runtime di debug di Windows non viene distribuito con Proton. Dovrai associare i file DLL del runtime di debug alla tua build. Per ulteriori dettagli, visita questo link:
https://docs.microsoft.com/it-it/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable. Per Visual Studio, dovrebbe funzionare una configurazione di distribuzione delle versioni di debug. Le proprietà dei progetti contengono l'opzione avanzata "Copiare il runtime C++ in OutDir" che può essere utile per i progetti in C++.
Strumenti di debugging remoto di Visual Studio su Proton
Gli strumenti di debugging remoto di Visual Studio non sono inclusi con Proton. Quando carichi un titolo per cui è stata selezionata la casella "Steam Play", lo strumento del dev kit copierà gli strumenti di debugging remoto dal tuo ambiente di sviluppo Windows al sistema dev kit.
Al momento, il dev kit cercherà gli strumenti di debugging installati da Visual Studio 2019 e Visual Studio 2017. Per avere a disposizione gli strumenti di debugging remoto, assicurati di includere un carico di lavoro al momento dell'installazione di Visual Studio (ad esempio: "Sviluppo di applicazioni desktop con C++").
Utilizzo
Esempi su Vulkan
Il progetto
Vulkan Examples è un buon punto di partenza per abituarsi ad effettuare il debugging remoto per i giochi caricati sul dev kit di Steam Deck.
Clona il progetto e cambia la directory corrente:
git clone --recursive git@gitlab.steamos.cloud:jupiter/vulkan-examples.git
cd vulkan-examples
La directory "examples" del progetto contiene diversi piccoli esempi su Vulkan. Qui ci limiteremo a usare
imgui
. Genera e compila il progetto:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows
cmake --build build/windows --config Debug --target imgui
Nota: CMake scaricherà alcune risorse aggiuntive tramite un piccolo script, la cui esecuzione richiede l'installazione di Python sul computer della build.
Verrà creata la directory
build/windows/bin/Debug
contenente l'eseguibile
imgui
, i file DLL di Windows richiesti per il debug e tutti i dati.
A questo punto potrai caricare la directory "Debug" risultante.
Assicurati di selezionare "Questo titolo richiede Steam Play" (poiché non si tratta di una build nativa di Linux) e "Avvia il debugger di Visual Studio C++ all'avvio" per abilitare il debugger remoto.
Se non è sufficiente collegarsi quando il gioco è già in esecuzione e se desideri effettuare il debug delle fasi di avvio e inizializzazione del tuo titolo, usa "Wait for a debug client to attach" (Attendi il collegamento di un client di debug) e consulta la sezione relativa al collegamento anticipato (early attach) in questo documento.
Una volta completato il trasferimento, se ad esempio hai scelto il nome
vulkan_examples_debug
, dovresti trovare un nuovo gioco chiamato
Devkit Game: vulkan_examples_debug
nella Libreria dei giochi di Steam.
Lanciando quel gioco, si avvierà automaticamente anche un server msvsmon per il debugging remoto.
Ora potrai finalmente collegare un debugger al gioco in esecuzione.
Su Visual Studio, premi
Ctrl+Alt+P
per aprire la finestra
Esegui debug > Collega a processo. Imposta l'IP e la porta del server msvsmon come connessione di destinazione e poi seleziona il processo
imgui.exe
.
Per una lista di istruzioni dettagliate, consulta la
documentazione di Microsoft sul debugging.
Esempi su Unreal Engine 4
Crea un account Epic Games, se non ne hai già uno, quindi
scarica e installa Unreal Engine 4.
Come esempio, useremo uno dei progetti di prova offerti da Unreal Editor. Crea un nuovo progetto e seleziona il modello"Puzzle".
Seleziona un nome e un percorso per il progetto.
Vai su Edit->Project settings->Packaging e seleziona "Debug" o "DebugGame" come configurazione della build. Ulteriori informazioni sono disponibili nella
documentazione ufficiale. Selezionando "Include Debug Files", i file di debug saranno inclusi nel pacchetto del gioco.
Se non riesci a compilare una build nativa su Linux (ad esempio se il tuo gioco ha delle dipendenze esterne che non supportano Linux), puoi creare una build Windows utilizzando File->Package Project->Windows (64-bit). In questo modo verrà creata una build in una nuova directory chiamata "WindowsNoEditor".
Carica il tuo gioco compilato usando lo strumento
SteamOS Devkit Client
.
Ora la tua Libreria di Steam dovrebbe contenere un nuovo titolo dal nome
Devkit Game: puzzle
(o simile). Lanciando il gioco, si avvierà automaticamente anche un server msvsmon per il debugging remoto.
Ora potrai collegare il debugger al gioco in esecuzione.
Su Visual Studio, premi
Ctrl+Alt+P
per aprire la finestra
Esegui debug > Collega a processo. Imposta l'IP e la porta del server msvsmon come connessione di destinazione e poi seleziona il processo
puzzle.exe
.
Per una lista di istruzioni dettagliate, consulta la
documentazione di Microsoft sul debugging.
Avvio del processo di debugging remoto: supporto "early attach" (collegamento anticipato):
Il servizio di debug remoto può essere configurato in modo da attendere che l'utente ne effettui il collegamento prima di avviare il titolo. È così possibile impostare un punto di interruzione in WinMain o altri codici di inizializzazione.
Per prima cosa, installa sul PC di sviluppo questa estensione di Microsoft per Visual Studio:
https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerToolUna volta installata l'estensione, abilita il debug dei processi figlio come spiegato nella documentazione: Debug > Other Debug Targets > Child Process Debugging Settings.
Spunta la casella "Wait for a debug client to attach" (Attendi il collegamento di un client di debug) nel dev kit, dopodiché carica il tuo titolo.
Avvia il tuo titolo normalmente.
Quando ti colleghi al processo remoto, collegati a
steam.exe
. Una volta effettuato il collegamento, Proton avvierà immediatamente il tuo titolo come processo figlio e l'estensione si attiverà, iniziando il debug del tuo gioco dal momento dell'avvio con i punti di interruzione attivati.