Anatomia di un progetto · Primi passi

Un programma, una cartella

Nella lezione precedente gleam new ha creato un’intera cartella solo per stampare una riga. Può sembrare esagerato, ma è una scelta precisa: in Gleam non esiste il “file singolo”. Anche il programma più piccolo è un progetto (Gleam lo chiama anche package, pacchetto), e ogni progetto ha la stessa struttura. Il vantaggio è enorme: apri il progetto di chiunque altro e sai già dove guardare.

Ecco cosa c’è nella cartella hello dopo il primo gleam run:

output

hello/
├── .github/workflows/test.yml
├── .gitignore
├── README.md
├── build/
├── gleam.toml
├── manifest.toml
├── src/
│   └── hello.gleam
└── test/
    └── hello_test.gleam

File o cartella	A cosa serve
`src/`	Il codice sorgente del programma. Ogni file `.gleam` qui dentro è un modulo.
`test/`	Il codice che verifica che il programma funzioni. Lo useremo più avanti nel corso.
`gleam.toml`	La configurazione del progetto: nome, versione, librerie da cui dipende.
`manifest.toml`	L’elenco esatto delle versioni delle librerie scaricate. Lo gestisce Gleam, non si tocca a mano.
`build/`	Tutto ciò che il compilatore produce: codice Erlang, bytecode, librerie compilate.
`README.md`	La presentazione del progetto, per chi lo scarica.
`.gitignore`, `.github/`	Configurazione per git e per GitHub. Se non li usi, ignorali pure.

Il file gleam.toml

Apri gleam.toml. Tolti i commenti, è così:

gleam.toml

name = "hello"
version = "1.0.0"

[dependencies]
gleam_stdlib = ">= 1.0.0 and < 2.0.0"

[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

È scritto in TOML, un formato per file di configurazione fatto di righe chiave = valore raggruppate in sezioni tra parentesi quadre. Le sezioni che contano:

name e version: il nome del progetto e la sua versione.
[dependencies]: le librerie che il programma usa. Anche la libreria standard, gleam_stdlib, è una libreria come le altre: per questo la prima volta gleam run l’ha scaricata.
[dev_dependencies]: le librerie che servono solo mentre sviluppi, non al programma finito. gleeunit è quella che esegue i test.

La scritta ">= 1.0.0 and < 2.0.0" è un vincolo di versione: “va bene qualsiasi versione dalla 1.0.0 in su, ma non la 2”. Le versioni esatte scelte finiscono in manifest.toml, così chiunque scarichi il progetto userà proprio quelle.

Dettagli nerd Perché proprio «sotto la 2»? (il versionamento semantico)

Le librerie di Gleam seguono il versionamento semantico: un numero di versione ha tre parti, MAGGIORE.MINORE.CORREZIONE, e ognuna ha un significato preciso. La correzione (1.0.5) cambia quando si sistemano bug; la minore (1.3.0) quando si aggiunge qualcosa senza rompere niente; la maggiore (2.0.0) quando si cambia qualcosa in modo incompatibile, e il codice di chi usa la libreria potrebbe smettere di compilare.

Per questo il vincolo dice “sotto la 2”: tutte le versioni 1.x sono compatibili tra loro, quindi Gleam può aggiornarle tranquillamente; la 2 potrebbe richiedere modifiche, e va scelta di proposito.

I comandi di tutti i giorni

Il programma gleam fa tutto. Questi sono i comandi che userai più spesso, sempre lanciati dall’interno della cartella del progetto:

Comando	Cosa fa
`gleam run`	Compila ed esegue `main` del modulo principale.
`gleam run -m nome`	Esegue `main` di un altro modulo.
`gleam build`	Compila e basta, senza eseguire.
`gleam check`	Controlla solo sintassi e tipi. Il più veloce per sapere “compila?“.
`gleam format`	Riformatta tutto il codice secondo lo stile ufficiale.
`gleam test`	Esegue i test nella cartella `test/`.
`gleam clean`	Cancella la cartella `build/` (verrà ricreata al prossimo `gleam run`).
`gleam help`	L’elenco di tutti i comandi, con la spiegazione.

Prova gleam test sul progetto hello: gleam new ha già scritto un piccolo test d’esempio in test/hello_test.gleam.

output

  Compiling hello
   Compiled in 0.41s
    Running hello_test.main
.
1 passed, no failures

Il puntino è un test superato. Scriverai i tuoi test più avanti nel corso; per ora ti basta sapere che esistono e dove stanno.

Quiz

Hai modificato il codice e vuoi solo sapere, il più in fretta possibile, se ci sono errori. Quale comando usi?

Più moduli nello stesso progetto

Ogni file .gleam dentro src/ è un modulo, e il nome del modulo è il nome del file senza estensione. Qualsiasi modulo che abbia una funzione pub fn main() si può eseguire con gleam run -m:

src/second.gleam

import gleam/io

pub fn main() -> Nil {
  io.println("Running a second module!")
}

terminale

gleam run -m second

output

  Compiling hello
   Compiled in 0.22s
    Running second.main
Running a second module!

Questo ti torna utile subito: invece di creare un progetto nuovo per ogni esercizio, puoi tenerne uno solo per tutto il corso e aggiungere un modulo per ogni esercizio. Ognuno ha il suo main, e lo lanci con gleam run -m seguito dal suo nome.

Dettagli nerd Cosa c'è dentro build/?

Dopo un gleam run, in build/dev/erlang/ trovi una cartella per ogni pacchetto: il tuo progetto e le librerie da cui dipende. Dentro ci sono i file .erl (il tuo codice tradotto in Erlang) e i file .beam, il bytecode: il formato compatto che la BEAM esegue davvero.

Gleam ricompila solo i moduli che sono cambiati dall’ultima volta: per questo il secondo gleam run è più veloce del primo. La cartella è rigenerabile in ogni momento, ed è per questo che .gitignore la esclude: non si salva nel controllo di versione, e gleam clean la può cancellare senza pietà.

Esercizio · sul tuo computer

Un progetto per tutto il corso

Nella cartella ~/learn-gleam crea un progetto chiamato exercises con gleam new exercises. Sarà la tua palestra per il resto del corso.
Dentro exercises/src/ crea un file second.gleam con il codice del modulo second visto qui sopra.
Dalla cartella exercises lancia gleam run -m second.
Già che ci sei, lancia anche gleam test e gleam format --check e guarda cosa rispondono.

Copia qui sotto la riga stampata dal tuo modulo.

Cosa ha stampato il programma?

Ricapitolando

Ogni programma Gleam è un progetto: src/ per il codice, test/ per i test, gleam.toml per la configurazione.
gleam.toml elenca le librerie in [dependencies] con un vincolo di versione; manifest.toml fissa le versioni esatte.
build/ contiene l’Erlang e il bytecode generati: si può sempre cancellare con gleam clean.
Ogni file in src/ è un modulo; gleam run -m nome esegue il main di un modulo qualsiasi.
gleam check per sapere se compila, gleam format per mettere in ordine, gleam test per i test.

Nella prossima lezione iniziamo a lavorare sui dati veri e propri: valori, variabili e i tipi fondamentali di Gleam.