Inizia

Per compilare Heroes serve clang 18 o una versione più recente. Non c’è ancora un installer.

Quattro comandi

$ git clone https://github.com/heroes-lang/heroes
$ cd heroes
$ clang -I runtime seed/heroes.c runtime/runtime.c -o heroes
$ ./heroes run examples/gallery/03-fallible.hero
read 42
failed: not_a_digit (expected 0-9)
20

La terza riga richiede meno di quattro secondi su un MacBook Air, la macchina da cui viene ogni misura di questo sito. Costruisce il compilatore da un solo file C generato da Heroes, ed è per questo che ti basta clang.

La riga con failed è un risultato previsto dell’esempio: il programma segnala un carattere che non riesce a convertire in numero. La compilazione è riuscita.

Se non hai clang

clang è un compilatore C, cioè il programma che trasforma il C in qualcosa che il tuo computer esegue. A Heroes serve la versione 18 o più recente, perché è la più vecchia su cui è misurato. Chiedi al tuo quale sia:

$ clang --version

Il prefisso del fornitore non conta, quindi vanno bene sia Apple clang version 21 sia Debian clang version 22: conta solo il primo numero. Se hai già compilato Heroes, ./heroes doctor risponde alla stessa domanda e dice cosa manca quando manca qualcosa.

macOS. I Command Line Tools portano il clang di Apple:

$ xcode-select --install

Se ti dà un numero sotto il 18, cosa che succede su un macOS più vecchio, installa un clang aggiornato accanto a quello con Homebrew e usa quello:

$ brew install llvm
$ "$(brew --prefix llvm)/bin/clang" -I runtime seed/heroes.c runtime/runtime.c -o heroes

Debian e Ubuntu.

$ sudo apt install clang

Se il clang della tua distribuzione è più vecchio del 18, su apt.llvm.org ci sono i pacchetti aggiornati.

Windows.

$ winget install LLVM.LLVM

Su Windows la riga di compilazione vuole un flag in più, e non è una preferenza:

$ clang -I runtime seed/heroes.c runtime/runtime.c -Wl,/STACK:67108864 -o heroes

Windows dà al primo thread di un programma 1 MB di spazio per le chiamate di funzione, dove macOS e Linux ne danno 8, e questo compilatore si richiama in profondità mentre legge un programma. Senza quel flag si compila, parte e compila un programma piccolo, poi muore senza dire niente la prima volta che lo punti su uno dei suoi moduli.

Eseguilo dalla cartella del repository

heroes run cerca il runtime, cioè il codice di supporto che finisce dentro ogni binario, in ./runtime. Quindi eseguilo dalla cartella in cui hai clonato. Da qualunque altro posto, digli dov’è:

$ HEROES_RUNTIME=~/heroes/runtime heroes run hello.hero

Se il runtime manca, heroes run lo segnala e nomina la variabile da impostare. Per controllare gli altri requisiti, esegui ./heroes doctor.

Il tuo programma

Per questo programma basta un file con una funzione main, da cui inizia l’esecuzione. Non servono dichiarazioni import né un file di progetto.

$ printf 'function main()\n    print("we can be heroes")\n' > hello.hero
$ ./heroes run hello.hero
we can be heroes

heroes run compila il file e lo lancia, lasciando i suoi file di lavoro in una cartella build/ nella directory in cui ti trovi. La seconda esecuzione di un file non modificato riusa quello che c’è dentro.

Un comando, tredici verbi

Tutti gli strumenti si usano tramite heroes: lex, parse, check, build, run, test, fmt, doctor, mutate, probe, measure, grammar, this. Non c’è un secondo binario, non c’è un file di build e non ci sono plugin.

heroes fmt formatta il codice secondo regole fisse per indentazione, ritorni a capo e ordine. I sorgenti del progetto, compilatore compreso, seguono già queste regole: il formattatore li restituisce identici, byte per byte. Questo riduce le differenze dovute alla formattazione quando confronti due versioni. I file di test che contengono errori intenzionali vengono conservati così come sono.

Ogni esempio di questo sito è un file in examples/, con il comando che lo esegue e l’output che stampa.

Se qualcosa va storto

./heroes doctor segnala cosa manca sul tuo computer. I messaggi d’errore indicano cosa si aspettava il compilatore e in quale punto del codice. La guida spiega come leggerli. Se qualcosa non torna e questi non lo spiegano, segnalalo sull’issue tracker, il sistema per segnalare problemi: un programma che dovrebbe compilare e non compila, o che compila e dà la risposta sbagliata, è la cosa più utile che questo progetto possa ricevere. Un problema di sicurezza, soprattutto un programma Heroes che va in crash su un accesso sbagliato alla memoria o la corrompe, non va in una segnalazione pubblica: si manda con il modulo privato della scheda Security del repository, e SECURITY.md spiega come.

Poi: scrivi il tuo primo programma, un’idea alla volta. Oppure leggi tutto il linguaggio in un file e chiedi un programma al tuo modello.