Project Octave multifile e debugger nativo
Con Octave Script Workspace si può organizzare un calcolo GNU Octave in più file, conservare un unico Project registrato e seguirne l’esecuzione con il debugger. Questo esempio collega un programma principale a due funzioni helper e verifica, in tempo reale, breakpoint, Step Into, Step Over, Step Out, Call Stack e variabili locali.
La procedura si riferisce a GX-TXT DEV112-P005, modulo Octave Script Workspace 1.8.3, con l’editor High Contrast Dark. Il progetto viene creato direttamente nello Workspace, tramite i menu Project: non è necessario aprire Script Library.
1. Obiettivo scientifico e struttura del Project
Utilizzeremo quattro valori di tensione sintetici, un guadagno numerico e un offset. Le operazioni sono soltanto didattiche: la somma non pretende di rappresentare un esperimento strumentale specifico.
La sequenza è:
- Il programma principale definisce [1, 2, 3, 4] V, gain = 2,5 e offset = 0,75 V.
- La prima funzione moltiplica i quattro valori per il guadagno, ottenendo [2,5, 5, 7,5, 10] V.
- La seconda funzione somma i valori corretti e aggiunge una volta l’offset, ottenendo 25,75 V.
La relazione di controllo è S = gain × sum(values) + offset = 25,75 V.
Il Project comprende tre file, ciascuno con una funzione specifica: main.m, helpers/w03_gain_helper.m e helpers/w03_sum_with_offset.m. Questi nomi sono importanti: per la normale risoluzione delle funzioni GNU Octave il nome del file helper deve corrispondere a quello della funzione contenuta.
2. Creare un Project senza aprire Script Library
Con una Session di lavoro attiva, aprire Octave Script Workspace e utilizzare Project → New Project…. Compare la scheda New project del Project Canvas, direttamente nello stesso Viewer.
Selezionare Scope: session, attribuire un identificativo come w03_voltage_project, indicare un nome descrittivo e mantenere Entry point: main.m. Confermare con Create project.

L’entrypoint è il file da cui parte il calcolo. Il nuovo Project è un oggetto del Registry, non un insieme di file copiati senza identità: conserva struttura, revisioni e sorgenti associati.
3. Aggiungere due helper al progetto
Dal menu Project → New file… creare il primo percorso relativo helpers/w03_gain_helper.m. Ripetere la stessa operazione per helpers/w03_sum_with_offset.m.
La finestra richiede un Normalized relative source path: una sottocartella come helpers/ è ammessa. Non inserire percorsi assoluti né riferimenti a cartelle esterne alla struttura del Project.

L’albero permette di selezionare un file e mostrarne il contenuto nell’editor. La presenza dei tre nomi nell’albero non significa ancora che i relativi sorgenti siano stati completati: ciascun file deve contenere il codice appropriato.
4. Scrivere il programma principale main.m
Selezionare main.m nell’albero Project e inserire il seguente programma, con commenti in lingua inglese:
% W03: multi-file synthetic voltage calibration in GNU Octave.
values_V = [1; 2; 3; 4];
gain = 2.5;
offset_V = 0.75;
scaled_V = w03_gain_helper(values_V, gain);
total_V = w03_sum_with_offset(scaled_V, offset_V);
fprintf('W03_MULTIFILE_TOTAL=%.2f\n', total_V);
assert(abs(total_V - 25.75) < 1e-12);
La chiamata w03_gain_helper produce il vettore dei valori moltiplicati; w03_sum_with_offset restituisce uno scalare. fprintf stampa il risultato nel flusso stdout del Job e assert verifica la differenza numerica rispetto a 25,75.

Il codice non usa API scientifiche GX-TXT: in questa lezione GX-TXT gestisce il Project, il Runner, il debugger e il Job; il calcolo rimane normale GNU Octave.
5. Completare la prima funzione helper
Nell’albero selezionare helpers/w03_gain_helper.m e inserire:
function scaled_V = w03_gain_helper(values_V, gain)
% Reusable Project helper: multiply a numeric voltage vector.
scaled_V = values_V .* gain;
endfunction
Il primo argomento è un vettore di tensioni, il secondo è uno scalare. L’operatore .* effettua una moltiplicazione elemento per elemento; scaled_V è il vettore restituito dalla funzione.
Per il nostro esempio il risultato atteso è [2,5, 5, 7,5, 10] V. L’helper riceve i suoi valori dal chiamante: non deve leggere variabili nascoste da un altro script.
6. Completare il secondo helper
Selezionare helpers/w03_sum_with_offset.m e inserire:
function total_V = w03_sum_with_offset(values_V, offset_V)
% Reusable Project helper: sum voltages and apply one offset.
total_V = sum(values_V) + offset_V;
endfunction
La funzione sum(values_V) calcola la somma dei quattro elementi, poi aggiunge offset_V una sola volta. Questo passaggio restituisce uno scalare e mantiene distinta la logica della somma dalla moltiplicazione precedente.
I due helper sono funzioni GNU Octave vere, non frammenti di testo richiamati tramite esecuzione di file arbitrari.
7. Salvare insieme i tre sorgenti con Save All
Dopo aver completato main.m e i due helper, scegliere File → Save All. Il comando salva l’intero contenuto ammesso del Project in una nuova revisione: i tre file vengono verificati e registrati insieme.

In questo esempio la revisione del Project passa alla 4 dopo la creazione dei due helper. La numerazione deriva dalle operazioni effettuate sul Registry; non indica tre esecuzioni scientifiche. Un salvataggio riuscito non crea un Job.
È utile distinguere la revisione complessiva del Project da quella dei singoli contenuti: il Project possiede un’identità composita che comprende entrypoint e file ammessi.
8. Impostare un breakpoint sulla chiamata principale
Tornare su main.m e spostare il cursore sulla riga 5, quella che richiama w03_gain_helper. Premere F9 per attivare un breakpoint sul punto eseguibile.

Nel Project il breakpoint è associato al file relativo e alla riga fisica: main.m, riga 5. Questo permette al debugger di distinguere la stessa riga numerica in file diversi.
Se il breakpoint non compare, verificare che il focus sia realmente nell’area di testo, che il Source sia aggiornato e che il cursore si trovi su un’istruzione eseguibile, non su un commento.
9. Avviare il debugger dal progetto registrato
Utilizzare Run → Debug Session script…. Il debugger si apre nello Workspace e mostra il controllo Start Debug. Il comando avvia un Job GX-TXT gestito, utilizzando la revisione salvata del Project e i breakpoint ammessi.
Dopo Start Debug il programma entra nello stato PAUSED sul file principale, prima di chiamare il primo helper.

Il pulsante Pause per un arresto asincrono non è disponibile in questa configurazione: per fermare l’esecuzione in una posizione riproducibile si utilizza invece un breakpoint oppure l’avanzamento controllato.
10. Entrare nella funzione con Step Into
Quando il debugger è fermo sulla chiamata w03_gain_helper, scegliere Step Into. Il controllo trasferisce l’esecuzione dentro la funzione effettiva, senza simulare l’apertura di un file.
L’editor passa a helpers/w03_gain_helper.m e il debugger si ferma sull’istruzione di moltiplicazione alla riga 3.

L’indicatore di esecuzione si sposta sul file helper. Il Project e lo snapshot del Job conservano comunque la stessa identità: non viene registrata una nuova revisione durante il debug.
11. Leggere Call Stack e variabili locali
Durante la pausa in w03_gain_helper, aprire dal menu View i pannelli Call Stack e Variables / Locals, se non sono già visibili.
Il Call Stack mostra la funzione attiva e il suo chiamante main. Possono comparire anche frame esterni della gestione GNU Octave; non sono altri file del Project creati dall’utente.

Il pannello delle variabili mostra gain = 2,5 (double, scalare) e il vettore values_V = [1, 2, 3, 4] (double, quattro elementi).

Le variabili visualizzate appartengono al frame selezionato. La loro consultazione è un’osservazione dello stato del Job, non un nuovo calcolo e non un cambiamento dei dati scientifici.
12. Avanzare con Step Over e ritornare con Step Out
Con il debugger fermo nella funzione helper, Step Over avanza oltre l’istruzione corrente senza entrare in altre eventuali funzioni chiamate da essa. Nell’esempio la posizione successiva osservata è endfunction, alla riga 4 dell’helper.

Scegliere quindi Step Out per tornare al chiamante. L’esecuzione prosegue fino a main.m, fermandosi sull’istruzione fprintf alla riga 7, dopo che è stata calcolata la somma con offset.

A questo punto lo stato numerico osservato è: scaled_V = [2,5; 5; 7,5; 10] e total_V = 25,75.

13. Completare il Job con Continue
Per terminare il programma scegliere Continue. Il debugger riprende l’esecuzione, stampa il risultato, verifica assert e chiude il Job. Lo stato finale è COMPLETED con exit code 0.
Aprendo Program output / diagnostics… si legge il risultato del programma:
W03_MULTIFILE_TOTAL=25.75

Durante il debug GNU Octave può produrre sul flusso Program stderr messaggi che indicano gli arresti sulle righe del sorgente, per esempio stopped in main o stopped in w03_gain_helper. Sono informazioni di traccia del debugger, non necessariamente errori del calcolo: interpretarle insieme allo stato del Job, all’exit code e al rapporto di esecuzione.
In questo caso il rapporto termina con PASS e il calcolo restituisce il valore previsto.
14. Chiudere e riaprire il Project con i suoi tre file
Terminata l’esecuzione, chiudere il debugger e poi lo Workspace tramite File → Close. Riaprire Octave Script Workspace nella stessa Session e utilizzare Registered scripts per selezionare il Project.
L’albero dei file permette di riaprire main.m e ciascuno dei due helper, ritrovando i contenuti salvati in precedenza.

Non occorre creare nuovamente il Project: la sua revisione e i file fanno parte del Registry della Session. Le schede possono essere chiuse e riaperte indipendentemente dal contenuto registrato.
15. Recuperare il Job storico senza un’altra esecuzione
Dallo Workspace riaperto scegliere Run → Script Jobs Manager…. Il Job già concluso compare ancora come COMPLETED.

Aprire Jobs → Open execution details e verificare nuovamente Program output: il valore rimane 25,75, senza eseguire il programma una seconda volta.

Questo conferma la distinzione tra Project registrato, revisione salvata, snapshot dei file eseguiti e Job storico. Il debug ha operato sulla copia verificata del Project e non ha alterato i sorgenti conservati nel Registry.
16. Problemi frequenti e riepilogo
Se Project → New Project… non compare, verificare di essere nell’Octave Script Workspace e non in un altro Viewer. Il Project può essere creato direttamente qui: non è necessario attraversare Script Library.
Se Octave non trova una funzione helper, verificare il nome del file .m, il nome della funzione e la presenza del file nell’albero del Project ammesso. Evitare di aggiungere percorsi arbitrari o caricare sorgenti esterni per aggirare una struttura incompleta.
Se Start Debug è disabilitato, controllare che il Project sia registrato, che i file siano stati salvati con Save All, che sia selezionata la Session corretta e che il breakpoint sia su una riga eseguibile. Se Step Into entra in un helper diverso da quello previsto, confrontare la riga e il Call Stack, anziché modificare subito il codice.
Il workflow svolto è: New Project → New file… → editare main/helper → Save All → F9 → Start Debug → Step Into → Call Stack/Locals → Step Over → Step Out → Continue → Close/Reopen. Tutti i passaggi rimangono nel Project GX-TXT e nella normale esecuzione GNU Octave, senza alcuna modifica del CORE.