Configurare le sessioni di debug di CMake

  • Articolo

Il supporto nativo di CMake è disponibile in Visual Studio 2017 e versioni successive. Per visualizzare la documentazione per queste versioni, impostare il controllo selettore della versione di Visual Studio per questo articolo su Visual Studio 2017 o versione successiva. Si trova nella parte superiore del sommario in questa pagina.

Tutte le destinazioni CMake eseguibili vengono visualizzate nell'elenco a discesa Elemento di avvio sulla barra degli strumenti. Selezionare uno per avviare una sessione di debug e avviare il debugger.

Screenshot dell'elenco a discesa Elementi di avvio di CMake.

È anche possibile avviare una sessione di debug da Esplora soluzioni. Passare prima a Visualizzazione destinazioni CMake nella finestra Esplora soluzioni.

Screenshot del menu Visualizzazione destinazioni CMake.

Fare quindi clic con il pulsante destro del mouse su un eseguibile e scegliere Debug. Questo comando avvia automaticamente il debug della destinazione selezionata in base alla configurazione attiva.

Screenshot del menu dell'opzione Visualizza destinazioni CMake.

A partire da Visual Studio 2022 versione 17.6, è anche possibile avviare una sessione di debug nel file CMakeLists.txt. A tale scopo, è sufficiente impostare un punto di interruzione nel file CMakeLists.txt ed eseguire Configura progetto con il debugger CMake dall'elenco a discesa Progetto .

Screenshot dell'elenco a discesa Debugger CMake.

Personalizzare le impostazioni del debugger

È possibile personalizzare le impostazioni del debugger per qualsiasi destinazione CMake eseguibile nel progetto. Si trovano in un file di configurazione denominato launch.vs.json, che si trova in una .vs cartella nella radice del progetto. Un file di configurazione di avvio è utile nella maggior parte degli scenari di debug, perché è possibile configurare e salvare i dettagli dell'installazione del debug. Al file sono presenti tre punti di ingresso:

  • Menu Debug: selezionare Debug > debug e impostazioni di avvio per ${activeDebugTarget} dal menu principale per personalizzare la configurazione di debug specifica per la destinazione di debug attiva. Se non è selezionata una destinazione di debug, questa opzione è disattivata.

Screenshot del comando di menu Debug Impostazioni debug e avvio per il progetto.

  • Visualizzazione destinazioni: passare alla visualizzazione Destinazioni in Esplora soluzioni. Fare quindi clic con il pulsante destro del mouse su una destinazione di debug e selezionare Aggiungi configurazione di debug per personalizzare la configurazione di debug specifica della destinazione selezionata.

Screenshot del comando Aggiungi configurazione di debug nel menu di scelta rapida per la destinazione.

  • CMakeLists.txt radice: fare clic con il pulsante destro del mouse su un CMakeLists.txt radice e scegliere Aggiungi configurazione di debug per aprire la finestra di dialogo Seleziona debugger. La finestra di dialogo consente di aggiungere qualsiasi tipo di configurazione di debug, ma è necessario specificare manualmente la destinazione CMake da richiamare tramite la projectTarget proprietà .

Screenshot della finestra di dialogo Selezionare un debugger.

È possibile modificare il file launch.vs.json per creare configurazioni di debug per un numero qualsiasi di destinazioni CMake. Quando si salva il file, Visual Studio crea una voce per ogni nuova configurazione nell'elenco a discesa Elemento di avvio.

Chiavi di riferimento in CMakeSettings.json

Per fare riferimento a qualsiasi chiave in un file di CMakeSettings.json , anteporrla cmake. in launch.vs.json. Nell'esempio seguente viene illustrato un semplice file di launch.vs.json che esegue il pull del valore della remoteCopySources chiave nel file CMakeSettings.json per la configurazione attualmente selezionata:

{
  "version": "0.2.1",
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "name": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "args": ["${cmake.remoteCopySources}"]
    }
  ]
}

Le variabili di ambiente definite in CMakeSettings.json possono essere usate anche in launch.vs.json usando la sintassi ${env.VARIABLE_NAME}. In Visual Studio 2019 versione 16.4 e successive le destinazioni di debug vengono avviate automaticamente usando l'ambiente specificato in CMakeSettings.json. È possibile annullare l'impostazione di una variabile di ambiente impostandola su Null.

Informazioni di riferimento su Launch.vs.json

Esistono molte proprietà launch.vs.json per supportare tutti gli scenari di debug. Le proprietà seguenti sono comuni a tutte le configurazioni di debug, sia remote che locali:

  • projectTarget: specifica la destinazione CMake da richiamare durante la compilazione del progetto. Visual Studio popola automaticamente questa proprietà se si immette launch.vs.json dal menu Debug o dalla visualizzazione Destinazioni. Questo valore deve corrispondere al nome di una destinazione di debug esistente elencata nell'elenco a discesa Elemento di avvio.

  • env: variabili di ambiente aggiuntive da aggiungere usando la sintassi:

    "env": {
      "DEBUG_LOGGING_LEVEL": "trace;info",
      "ENABLE_TRACING": "true"
    }

  • args: argomenti della riga di comando passati al programma per il debug.

Launch.vs.json informazioni di riferimento per progetti remoti e WSL

In Visual Studio 2019 versione 16.6 è stata aggiunta una nuova configurazione di debug di type: cppgdb per semplificare il debug nei sistemi remoti e WSL. Le configurazioni di debug precedenti di type: cppdbg sono ancora supportate.

Tipo di configurazione cppgdb

  • name: nome descrittivo per identificare la configurazione nell'elenco a discesa Elemento di avvio.
  • project: specifica il percorso relativo del file di progetto. In genere, non è necessario modificare questo percorso durante il debug di un progetto CMake.
  • projectTarget: specifica la destinazione CMake da richiamare durante la compilazione del progetto. Visual Studio popola automaticamente questa proprietà se si immette launch.vs.json dal menu Debug o dalla visualizzazione Destinazioni. Questo valore di destinazione deve corrispondere al nome di una destinazione di debug esistente elencata nell'elenco a discesa Elemento di avvio.
  • debuggerConfiguration: indica quale set di valori predefiniti di debug usare. In Visual Studio 2019 versione 16.6 l'unica opzione valida è gdb. Visual Studio 2019 versione 16.7 o successiva supporta gdbserveranche .
  • args: argomenti della riga di comando passati all'avvio al programma sottoposto a debug.
  • env: variabili di ambiente aggiuntive passate al programma sottoposto a debug. Ad esempio: {"DISPLAY": "0.0"}.
  • processID: ID processo Linux a cui connettersi. Utilizzato solo per il collegamento a un processo remoto. Per altre informazioni, vedere Risolvere i problemi di collegamento ai processi tramite GDB.

Opzioni aggiuntive per la gdb configurazione

  • program: il valore predefinito è "${debugInfo.fullTargetPath}". Percorso Unix dell'applicazione di cui eseguire il debug. Obbligatorio solo se diverso dall'eseguibile di destinazione nel percorso di compilazione o distribuzione.
  • remoteMachineName: il valore predefinito è "${debugInfo.remoteMachineName}". Nome del sistema remoto che ospita il programma di cui eseguire il debug. Obbligatorio solo se diverso dal sistema di compilazione. Deve avere una voce esistente nella Gestione connessioni. Premere CTRL+SPAZIO per visualizzare un elenco di tutte le connessioni remote esistenti.
  • cwd: il valore predefinito è "${debugInfo.defaultWorkingDirectory}". Percorso Unix della directory nel sistema remoto in cui program viene eseguito. La directory deve esistere.
  • gdbpath: il valore predefinito è /usr/bin/gdb. Percorso Unix completo dell'oggetto gdb utilizzato per il debug. Obbligatorio solo se si usa una versione personalizzata di gdb.
  • preDebugCommand: comando Linux da eseguire immediatamente prima di richiamare gdb. gdb non viene avviato fino al completamento del comando. È possibile usare l'opzione per eseguire uno script prima dell'esecuzione di gdb.

Opzioni aggiuntive consentite con la gdbserver configurazione (16.7 o versione successiva)

  • program: il valore predefinito è "${debugInfo.fullTargetPath}". Percorso Unix dell'applicazione di cui eseguire il debug. Obbligatorio solo se diverso dall'eseguibile di destinazione nel percorso di compilazione o distribuzione.

    Suggerimento

    La distribuzione non è ancora supportata per scenari di compilazione incrociata locale. Se si esegue la compilazione incrociata in Windows (ad esempio, usando un compilatore incrociato in Windows per compilare un eseguibile arm Linux), sarà necessario copiare manualmente il file binario nel percorso specificato da program nel computer ARM remoto prima del debug.

  • remoteMachineName: il valore predefinito è "${debugInfo.remoteMachineName}". Nome del sistema remoto che ospita il programma di cui eseguire il debug. Obbligatorio solo se diverso dal sistema di compilazione. Deve avere una voce esistente nella Gestione connessioni. Premere CTRL+SPAZIO per visualizzare un elenco di tutte le connessioni remote esistenti.

  • cwd: il valore predefinito è "${debugInfo.defaultWorkingDirectory}". Percorso Unix completo della directory nel sistema remoto in cui program viene eseguito. La directory deve esistere.

  • gdbPath: il valore predefinito è ${debugInfo.vsInstalledGdb}. Percorso completo di Windows per l'oggetto gdb utilizzato per il debug. Il valore predefinito è quello gdb installato con il carico di lavoro Sviluppo Linux con C/C++.

  • gdbserverPath: il valore predefinito è usr/bin/gdbserver. Percorso Unix completo dell'oggetto gdbserver utilizzato per il debug.

  • preDebugCommand: comando Linux da eseguire immediatamente prima di avviare gdbserver. gdbserver non viene avviato fino al completamento del comando.

Opzioni di distribuzione

Usare le opzioni seguenti per separare il computer di compilazione (definito in CMakeSettings.json) dal computer di debug remoto.

  • remoteMachineName: computer di debug remoto. Obbligatorio solo se diverso dal computer di compilazione. Deve avere una voce esistente nella Gestione connessioni. Premere CTRL+SPAZIO per visualizzare un elenco di tutte le connessioni remote esistenti.
  • disableDeploy: il valore predefinito è false. Indica se la separazione di compilazione/debug è disabilitata. Quando false, questa opzione consente la compilazione e il debug in due computer separati.
  • deployDirectory: percorso Unix completo della directory in remoteMachineName cui viene copiato l'eseguibile.
  • deploy: matrice di impostazioni di distribuzione avanzate. È sufficiente configurare queste impostazioni quando si vuole un controllo più granulare sul processo di distribuzione. Per impostazione predefinita, solo i file necessari per il processo di debug vengono distribuiti nel computer di debug remoto.
    • sourceMachine: computer da cui viene copiato il file o la directory. Premere CTRL+SPAZIO per visualizzare un elenco di tutte le connessioni remote archiviate nella Gestione connessioni. Quando si compila in modo nativo in WSL, questa opzione viene ignorata.
    • targetMachine: computer in cui viene copiato il file o la directory. Premere CTRL+SPAZIO per visualizzare un elenco di tutte le connessioni remote archiviate nella Gestione connessioni.
    • sourcePath: percorso del file o della directory in sourceMachine.
    • targetPath: percorso del file o della directory in targetMachine.
    • deploymentType: descrizione del tipo di distribuzione. LocalRemote e RemoteRemote sono supportati. LocalRemote significa copiare dal file system locale al sistema remoto specificato da remoteMachineName in launch.vs.json. RemoteRemote significa copiare dal sistema di compilazione remoto specificato in CMakeSettings.json nel sistema remoto diverso specificato in launch.vs.json.
    • executable: indica se il file distribuito è un eseguibile.

Eseguire comandi personalizzati gdb

Visual Studio supporta l'esecuzione di comandi personalizzati gdb per interagire direttamente con il debugger sottostante. Per altre informazioni, vedere Esecuzione di comandi lldb personalizzatigdb.

Abilitazione della registrazione

Abilitare la registrazione di MIEngine per visualizzare i comandi inviati a gdb, l'output gdb restituito e il tempo necessario per ogni comando. Ulteriori informazioni

Tipo di configurazione cppdbg

Durante il debug in un sistema remoto o WSL è possibile usare le opzioni seguenti usando il cppdbg tipo di configurazione. In Visual Studio 2019 versione 16.6 o successiva è consigliabile usare il tipo di cppgdb configurazione.

  • name: nome descrittivo per identificare la configurazione nell'elenco a discesa Elemento di avvio.

  • project: specifica il percorso relativo del file di progetto. In genere, non è necessario modificare questo valore durante il debug di un progetto CMake.

  • projectTarget: specifica la destinazione CMake da richiamare durante la compilazione del progetto. Visual Studio popola automaticamente questa proprietà se si immette launch.vs.json dal menu Debug o dalla visualizzazione Destinazioni. Questo valore deve corrispondere al nome di una destinazione di debug esistente elencata nell'elenco a discesa Elemento di avvio.

  • args: argomenti della riga di comando passati all'avvio al programma sottoposto a debug.

  • processID: ID processo Linux a cui connettersi. Utilizzato solo per il collegamento a un processo remoto. Per altre informazioni, vedere Risolvere i problemi di collegamento ai processi tramite GDB.

  • program: il valore predefinito è "${debugInfo.fullTargetPath}". Percorso Unix dell'applicazione di cui eseguire il debug. Obbligatorio solo se diverso dall'eseguibile di destinazione nel percorso di compilazione o distribuzione.

  • remoteMachineName: il valore predefinito è "${debugInfo.remoteMachineName}". Nome del sistema remoto che ospita il programma di cui eseguire il debug. Obbligatorio solo se diverso dal sistema di compilazione. Deve avere una voce esistente nella Gestione connessioni. Premere CTRL+SPAZIO per visualizzare un elenco di tutte le connessioni remote esistenti.

  • cwd: il valore predefinito è "${debugInfo.defaultWorkingDirectory}". Percorso Unix completo della directory nel sistema remoto in cui program viene eseguito. La directory deve esistere.

  • environment: variabili di ambiente aggiuntive passate al programma sottoposto a debug. ad esempio:

      "environment": [
      {
        "name": "ENV1",
        "value": "envvalue1"
      },
      {
        "name": "ENV2",
        "value": "envvalue2"
      }
    ]

  • pipeArgs: matrice di argomenti della riga di comando passati al programma pipe per configurare la connessione. Il programma pipe viene usato per inoltrare input/output standard tra Visual Studio e gdb. La maggior parte di questa matrice non deve essere personalizzata durante il debug di progetti CMake. L'eccezione è , ${debuggerCommand}che viene avviata gdb nel sistema remoto. Può essere modificato in:

    • Esportare il valore della variabile di ambiente DISPLAY nel sistema Linux. Nell'esempio seguente questo valore è :1.

      "pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "export DISPLAY=:1;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],

    • Eseguire uno script prima dell'esecuzione di gdb. Assicurarsi che le autorizzazioni di esecuzione siano impostate sullo script.

      "pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "/path/to/script.sh;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],

  • stopOnEntry: valore booleano che specifica se interrompere non appena viene avviato il processo. L'impostazione predefinita è false.

  • visualizerFile: file natvis da usare durante il debug di questo processo. Questa opzione non è compatibile con gdb la stampa. Impostare showDisplayString anche quando si imposta questa proprietà.

  • showDisplayString: valore booleano che abilita la stringa di visualizzazione quando viene specificato un oggetto visualizerFile . L'impostazione di questa opzione su true può causare prestazioni più lente durante il debug.

  • setupCommands: uno o più gdb comandi da eseguire per configurare il debugger sottostante.

  • miDebuggerPath: percorso completo di gdb. Se non specificato, Visual Studio cerca prima path per il debugger.

  • Infine, tutte le opzioni di distribuzione definite per il cppgdb tipo di configurazione possono essere usate anche dal cppdbg tipo di configurazione.

Eseguire il debug con gdbserver

È possibile configurare la configurazione per il cppdbg debug usando gdbserver. Per altri dettagli e una configurazione di avvio di esempio, vedere il post di blog del team di Microsoft C++ Debug di progetti CMake Linux con gdbserver.