Start

To build Heroes, you need clang 18 or newer. There is no installer yet.

Four commands

$ 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

The third line takes under four seconds on a MacBook Air, the machine every measurement here comes from. It builds the compiler from one C file generated by Heroes, which is why clang is all you need.

The line containing failed is expected output: the example reports a character it cannot convert to a number. Compilation succeeded.

If you do not have clang

clang is a C compiler, the program that turns C into something your computer runs. Heroes needs version 18 or newer, because that is the oldest one it is measured on. Ask yours what it is:

$ clang --version

Any vendor prefix is fine, so Apple clang version 21 and Debian clang version 22 both count. Only the first number matters. If you already have Heroes built, ./heroes doctor answers the same question and says what is missing when something is.

macOS. The Command Line Tools bring Apple’s clang:

$ xcode-select --install

If that gives you a number below 18, which happens on an older macOS, install a current clang beside it with Homebrew and use that one:

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

Debian and Ubuntu.

$ sudo apt install clang

If your distribution’s clang is older than 18, apt.llvm.org publishes current packages for it.

Windows.

$ winget install LLVM.LLVM

On Windows the build line takes one more flag, and it is not a preference:

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

Windows gives a program’s first thread 1 MB of room for function calls where macOS and Linux give 8, and this compiler calls itself deeply while reading a program. Without the flag it builds, runs and compiles a small program, then dies without a word the first time you point it at one of its own modules.

Run it from the repository

heroes run looks for the runtime, the support code that goes into every binary, in ./runtime. So run it from the directory you cloned into. From anywhere else, say where the runtime is:

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

When heroes run cannot find the runtime it says so and names the variable to set. If something else is missing, ./heroes doctor names it.

Your own program

This program needs only one file with a main function, where execution starts. No import statements or project file are required.

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

heroes run compiles the file and launches it, leaving its working files in a build/ folder in the current directory. The second run of an unchanged file reuses what is in there.

One command, thirteen verbs

All the tools are available through heroes: lex, parse, check, build, run, test, fmt, doctor, mutate, probe, measure, grammar, this. There is no second binary, no build file and no plugin.

heroes fmt formats code using fixed rules for indentation, line breaks and order. The project’s source files, including the compiler, already follow those rules: the formatter returns them unchanged, byte for byte. This reduces formatting differences when you compare versions. Test files containing deliberate errors are preserved as written.

Every example on this site is a file in examples/, with the command that runs it and the output it prints.

If something goes wrong

./heroes doctor reports what is missing on your computer. Error messages say what the compiler expected and where in the code. The guide explains how to read them. If something is wrong that these do not explain, report it on the issue tracker: a program that should compile and does not, or one that compiles and gives the wrong answer, is the most useful thing this project can receive. A security problem, above all a Heroes program that crashes on a bad memory access or corrupts memory, does not go into a public report: send it with the private form on the repository’s Security tab, and SECURITY.md says how.

Next: write your first program, one idea at a time. Or take the whole language in one file and ask your model for a program.