Debugger GNU Octave in GX-TXT: breakpoint, variabili e API pubbliche

Come eseguire e controllare passo dopo passo gli script GNU Octave in GX-TXT: una guida pratica al debugger nativo, basata su due esperimenti realmente eseguiti e verificati nel framework. Impareremo a usare breakpoint, Step Into, Step Over, Step Out, Call Stack, variabili locali e Script Jobs; introdurremo inoltre le API pubbliche GX-TXT per il calcolo numerico.

Ambiente verificato: GX-TXT 0.9.8.10-dev-107, commit GitHub 2e4049774309 (18 ottobre 2026). Esempi con dati sintetici; nessun Dataset viene creato o modificato. Le prove descritte sono state effettuate nella Session tutorial_debug.

1. Dall’Octave Script Workspace al debugger

Apriamo una Session di prova in GX-TXT e il Viewer Viewers → Octave Script Workspace. Nella parte sinistra troviamo gli script registrati; al centro il sorgente Octave; a destra gli snippet del Bridge. Dal menu View → Debugger attiviamo il pannello di debug; si possono usare anche le voci del menu Run. Salvare lo script con Scope: Session e un ID stabile è essenziale: il debugger esegue una revisione registrata e immutabile del sorgente, non un buffer non salvato.

Un programma Octave può essere scritto anche prima di aprire una Session scegliendo la libreria User, ma la normale esecuzione scientifica e il Debug Job richiedono una Session reale. Per la prova useremo uno script Session.

2. Primo esperimento: funzioni, ciclo for e Call Stack

Il primo script contiene due funzioni. adjust(value) aumenta il valore ricevuto di uno; accumulate(count) ripete la chiamata nel ciclo for, sommando i risultati. Le cinque iterazioni producono 1 + 2 + 3 + 4 + 5 = 15. I commenti del file sorgente sono interamente in inglese, come previsto dal corso.

% Synthetic accumulation for native Into, Over and Out practice.
% SPDX-License-Identifier: GPL-3.0-or-later
1; % Keep this file an executable Octave script with local functions.
function increment = adjust(value)
  increment = value + 1;
endfunction
function total = accumulate(count)
  total = 0;
  for sample = 0:(count - 1)
    adjusted = adjust(sample);
    total = total + adjusted;
  endfor
endfunction
result = accumulate(5);
fprintf('NESTED_RESULT %d\n', result);
assert(result == 15);

Scarica il sorgente:

Lo stesso esempio è presente nel repository ufficiale.

Procedura: importa il file tramite File → Import, registralo come session:octave_debug_nested, salvalo e avvialo dal normale Script Runner. Il risultato atteso è NESTED_RESULT 15 e lo Script Job deve risultare COMPLETED.

Il primo breakpoint: fermare lo script prima di una chiamata

Nel codice, la riga 10 contiene adjusted = adjust(sample);. Un clic nella corsia dei breakpoint accanto al numero di riga aggiunge il punto rosso. Poi apriamo il debugger, avviamo Start Debug e selezioniamo Stack and variables. La freccia gialla mostra l’istruzione che deve ancora essere eseguita.

Con il debugger fermo, count = 5, sample = 0 e total = 0. L’istruzione corrente non è ancora stata eseguita. Invece di cercare gli errori leggendo soltanto il risultato finale, osserviamo lo stato effettivo dell’interprete.

Step Into, Step Out e Step Over

Step Into entra nella funzione chiamata: da accumulate() passiamo a adjust(). Il Call Stack mostra ora un nuovo frame e la variabile locale value = 0. Step Out ritorna alla funzione chiamante: alla riga 11 leggiamo adjusted = 1, mentre total vale ancora zero perché la somma non è stata eseguita. Step Over esegue l’istruzione corrente senza scendere dentro eventuali nuove chiamate.

Continue riprende il programma fino al breakpoint successivo o al termine. Poiché il nostro breakpoint è dentro un for, può essere raggiunto più volte: è normale dover premere Continue ripetutamente. In questa prova l’esecuzione termina correttamente.

3. Secondo esperimento: usare le API numeriche pubbliche

Il secondo script presenta cinque misure sintetiche di temperatura: 18, 20, 22, 21 e 19 °C. Vogliamo convertirle in kelvin e calcolarne la media. Invece di delegare il calcolo a funzioni scollegate dall’integrazione GX-TXT, utilizziamo il provider Numeric pubblico attraverso l’Octave Script Bridge.

Le API introdotte in questa lezione

Funzione / operazione	Scopo didattico
gxtxt_api_require(...)	Richiedere un’API e verificare identità/versione/provider richiesti, interrompendo l’esecuzione se indisponibile.
gxtxt_api_call(api_id, operation, args)	Invocare una operazione pubblica registrata attraverso lo Script Bridge.
NUMERIC_API_v1 / array_binary	Applicare un’operazione binaria a due operandi numerici tipizzati.
NUMERIC_API_v1 / array_reduce	Ridurre un vettore a una statistica, qui la media.

La riga gxtxt_api_require('NUMERIC_API_v1@1:math.numeric') non effettua alcun calcolo: dichiara e controlla il requisito. Le successive due chiamate al provider Numeric eseguono effettivamente le operazioni. Le struct Octave dei parametri descrivono gli operandi tipizzati (per esempio kind='vector' o kind='scalar', con il corrispondente campo value). Il risultato viene letto mediante il campo .values.

% Synthetic temperature measurements; no Dataset is published.
% SPDX-License-Identifier: GPL-3.0-or-later
gxtxt_api_require('NUMERIC_API_v1@1:math.numeric');
celsius = [18; 20; 22; 21; 19];
measurements = struct('kind', 'vector', 'value', celsius);
offset = struct('kind', 'scalar', 'value', 273.15);
converted = gxtxt_api_call('NUMERIC_API_v1', 'array_binary', ...
                           {'add', measurements, offset});
kelvin = converted.values;
average = gxtxt_api_call('NUMERIC_API_v1', 'array_reduce', ...
                         {'mean', struct('kind', 'vector', 'value', kelvin)});
fprintf('KELVIN\n'); disp(kelvin);
fprintf('MEAN_K %.12f\n', average.values);

Scarica il sorgente:

Si tratta dello script ufficiale verificato su GitHub, utilizzato senza modifiche. Per studiare la semantica dell’invocazione consulta Octave Script Bridge API v1 e il manuale del modulo.

Risultati numerici

L’operazione di conversione aggiunge 273,15 a ciascun valore. Il programma produce il vettore 291,15; 293,15; 295,15; 294,15; 292,15 K. L’operazione di riduzione restituisce 293,15 K. La conversione e la media coincidono con il calcolo teorico.

Leggere i valori restituiti dal framework

Impostando il breakpoint sulla riga 12 (fprintf('KELVIN\n');), possiamo esaminare le variabili prima della stampa. Il debugger mostra celsius e kelvin come vettori numerici 5×1, mentre measurements, offset, converted e average sono strutture. Questo è un passaggio importante: la visualizzazione di una struttura nel debugger è un riepilogo, non necessariamente l’espansione completa di tutti i campi.

4. Alcune regole pratiche del debugger Octave

• Save prima di Start Debug: GX-TXT esegue il sorgente registrato e ne conserva l’identità SHA-256 per la riproducibilità.
• Call Stack e Variables: selezionare il frame pertinente per vedere le sue variabili; i frame del CORE non coincidono con quelli del nostro script.
• Continue dentro un ciclo: è possibile incontrare lo stesso breakpoint più volte.
• Pause asincrono: nella dev-107 non è supportato dal debugger GNU Octave; usare breakpoint, Step e Stop, senza interpretare il pulsante disabilitato come un guasto.
• Program output e Debugger output: sono canali differenti. I risultati stampati sono conservati nei dettagli del Job, mentre il pannello Debugger output registra eventi e comandi del debugger.
• File e Dataset: i due esempi utilizzano soltanto misure sintetiche; nessun Dataset viene pubblicato.

5. Conclusioni e prossima tappa

Abbiamo verificato due funzionalità complementari: debug dell’esecuzione ordinaria GNU Octave (funzioni, cicli e Call Stack) e debug di uno script che invoca API pubbliche GX-TXT. Il prossimo approfondimento sarà la diagnosi di errori intenzionali, che sarà aggiunta a questa serie dopo un collaudo specifico della gestione delle eccezioni nel debugger.

Riferimento tecnico: GX-TXT dev-107, commit 2e4049774309. Script e immagini sono accompagnati nel pacchetto di distribuzione da informazioni per l’importazione in WordPress.