Looking Glass: il debugger integrato di GNOME Shell

Contesto essenziale

#

Looking Glass è la console di debug integrata in GNOME Shell: una REPL JavaScript che gira dentro il processo della shell, affiancata da un ispettore di finestre, estensioni e attori grafici.

Serve a rispondere a domande come “qual è la wm_class di questa finestra?”, “questa applicazione gira nativa su Wayland o passa da XWayland?”, “quale estensione sta generando errori?”.

Non richiede installazione ed è disponibile anche in sessione Wayland. I contenuti di questo post sono verificati su GNOME Shell 50.

Prerequisiti

#

• Una sessione GNOME Shell
• Gli strumenti di sviluppo abilitati (lo sono di default)

Verifica rapida:

gsettings get org.gnome.shell development-tools

Output atteso: true. Se restituisce false:

gsettings set org.gnome.shell development-tools true

Procedura passo-passo

#

1. Aprire Looking Glass

#

1. Premere Alt+F2 per aprire la finestra “Esegui un comando”
2. Digitare lg
3. Premere Invio

Il pannello scende da sotto la barra superiore e occupa circa il 70% dello schermo principale.

2. Chiuderlo

#

Premere Esc.

Looking Glass è modale: finché è aperto, tastiera e mouse non raggiungono le finestre sottostanti.

3. Orientarsi nell’interfaccia

#

In alto a sinistra ci sono due pulsanti:

• Mirino: avvia il picker per selezionare un elemento dell’interfaccia con il mouse
• Cestino: forza un ciclo di garbage collection

In alto a destra le schede:

Per passare da una scheda all’altra: Ctrl+Pag↑ e Ctrl+Pag↓.

4. Usare l’Evaluator

#

Scrivere un’espressione JavaScript al prompt >>> e premere Invio. Il risultato viene numerato e resta nello storico.

Sono già disponibili senza import:

• Clutter, Gio, GLib, GObject, Meta, Shell, St
• Main: il modulo principale della shell
• global: l’oggetto globale della shell
• stage: scorciatoia per global.stage

Funzioni e variabili specifiche di Looking Glass:

Tasti utili:

• Tab: completamento automatico
• Tab due volte: elenco dei completamenti possibili
• Freccia su / giù: cronologia dei comandi (persistente tra una sessione e l’altra)

I risultati di tipo oggetto sono cliccabili: aprono un ispettore con tutte le proprietà, navigabile con Back e richiamabile nell’Evaluator con Insert.

5. Selezionare un elemento con il picker

#

1. Cliccare sul mirino
2. Muovere il mouse: l’attore sotto il puntatore viene evidenziato con un bordo rosso
3. Rotella su per salire all’attore genitore, rotella giù per ridiscendere
4. Click per confermare, Esc per annullare

L’attore scelto finisce nell’Evaluator come risultato inspect(<x>, <y>) ed è subito utilizzabile tramite it.

Esempi pratici

#

Tutti i comandi seguenti vanno digitati nell’Evaluator.

Classe della finestra che aveva il focus prima di aprire Looking Glass:

global.display.focus_window.get_wm_class()

La finestra è un client Wayland nativo? (false significa XWayland):

global.display.focus_window.get_client_type() === Meta.WindowClientType.WAYLAND

Titolo e classe di tutte le finestre aperte:

global.get_window_actors().map(a => `${a.metaWindow.get_wm_class()} | ${a.metaWindow.get_title()}`)

PID del processo proprietario della finestra:

global.display.focus_window.get_pid()

Posizione e dimensioni della finestra:

global.display.focus_window.get_frame_rect()

Numero di monitor e di spazi di lavoro:

global.display.get_n_monitors()
global.workspace_manager.get_n_workspaces()

UUID delle estensioni installate:

Main.extensionManager.getUuids()

Oggetto completo di una singola estensione (stato, percorso, metadati):

Main.extensionManager.lookup('<uuid>')

Indicatori presenti nella barra superiore:

Object.keys(Main.panel.statusArea)

Inviare una notifica di prova:

Main.notify('Looking Glass', 'Notifica di test')

Rallentare tutte le animazioni della shell di 5 volte, utile per osservare una transizione:

St.Settings.get().slow_down_factor = 5

Ripristino:

St.Settings.get().slow_down_factor = 1

Errori comuni

#

• Alt+F2 non apre nulla Controllare che la scorciatoia non sia stata cambiata con gsettings get org.gnome.desktop.wm.keybindings panel-run-dialog e che la riga di comando non sia bloccata: gsettings get org.gnome.desktop.lockdown disable-command-line deve restituire false

• lg viene trattato come un programma inesistente I comandi interni di Alt+F2 sono disattivati: succede se development-tools è false oppure se sull’account sono attivi i controlli parentali

• Una variabile dichiarata con const o let non esiste più al comando successivo Ogni riga viene eseguita in una funzione separata. Riutilizzare i risultati con it e r(<n>), oppure salvare il valore su globalThis.<nome>

• Il risultato è <exception ...> L’espressione ha sollevato un errore, mostrato nel testo dell’eccezione. Caso tipico: global.display.focus_window è null perché nessuna finestra aveva il focus

• Non si riesce a copiare testo da una finestra mentre Looking Glass è aperto È il comportamento previsto dalla modalità modale: chiudere con Esc, copiare, riaprire. La cronologia dei comandi viene mantenuta

Note operative

#

• Il codice dell’Evaluator gira nel processo di GNOME Shell. Su Wayland la shell è anche il compositor: un’istruzione che la blocca o la manda in crash chiude l’intera sessione e le applicazioni aperte
• Su Wayland non esiste il riavvio a caldo della shell: il comando r di Alt+F2 non è tra i comandi interni di GNOME Shell 50. Gli altri disponibili sono rt (ricarica il tema) e debugexit (termina la shell, quindi la sessione)
• La scheda Extensions offre per ogni estensione View Source, Web Page e Show Errors: è il punto più rapido per capire perché un’estensione risulta in stato Error
• La scheda Flags agisce a caldo sul compositor. unsafe-mode rimuove le restrizioni sulle API D-Bus riservate della shell: va disattivato a fine test
• L’output di log() e console.log() non compare in Looking Glass ma nel journal:

journalctl -f -o cat /usr/bin/gnome-shell

• Per sviluppare o provare un’estensione senza rischiare la sessione di lavoro conviene una shell annidata. Da GNOME 49:

dbus-run-session gnome-shell --devkit --wayland

Richiede il pacchetto mutter-devkit, non sempre installato di default. Fino a GNOME 48 l’equivalente era dbus-run-session gnome-shell --nested --wayland.

Riferimenti

#

• Sorgente di Looking Glass nel repository di GNOME Shell.
• Guida GJS al debug delle estensioni di GNOME Shell.