Getting started

Cuarzo compiles to C, and GCC turns that C into a native program. The only thing you need installed is GCC, available as gcc on your PATH. Programs that use std/http also need curl, which Windows 10 and later, macOS and most Linux systems already include.

Build the compiler

The repository carries the compiler already translated to C, in bootstrap/cuarzo.c. Clone it and build that file once:

git clone https://github.com/cuarzolang/cuarzo
cd cuarzo
gcc bootstrap/cuarzo.c -o cuarzo -lm

Adding -O2 -fno-strict-aliasing gives a faster compiler. Put the directory on your PATH, or call the compiler as ./cuarzo (in Windows PowerShell, .\cuarzo).

Your first program

Save this as hello.cz:

str name = "world"
print(f"Hello, {name}!")

And run it:

cuarzo run hello.cz
Hello, world!

cuarzo run builds the program and runs it. The generated files go to a build/ directory beside the source, so hello.cz builds build/hello.

The commands

cuarzo <file.cz> [arguments...]        build and run a program
cuarzo run <file.cz> [arguments...]    the same
cuarzo build <file.cz> [-o <program>]  build a native program
cuarzo c <file.cz> [-o <file.c>]       translate a program to C
cuarzo check <file.cz>                 report errors without building
cuarzo fmt [--check] [paths...]        lay out code in the canonical way
cuarzo lint <file.cz>                  warn of likely mistakes
cuarzo test [paths...]                 run the tests of *_test.cz files
cuarzo lsp                             the language server for editors
cuarzo dap                             the debug adapter for editors
cuarzo help                            show the commands

Options before the file tune the build. --optimize lets GCC optimize, and --release also strips the symbols. --gui builds a program with windows. -D NAME=value sets a build constant. --no-gc turns the garbage collector off, --max-memory <n> caps the heap (with the suffixes k, m and g), and --mem-stats prints memory use at exit. --check-overflow stops the program when integer arithmetic overflows.

cuarzo build --release -D DEBUG=false report.cz

When something is wrong

Errors point at the exact place in the source, up to ten at a time, each with a code that Diagnostics explains:

[ERROR E0236] report.cz:3:7: Unknown variable 'totl'; did you mean 'total'?
[ERROR E0167] report.cz:9:12: Cannot initialize 'int' with 'str'

A runtime error says where it happened and through which calls:

Cuarzo runtime error: array index out of bounds
    at report.cz:14 in average
    at report.cz:20

Next steps

  • A tour of Cuarzo shows the language in a few examples.
  • Projects explains cuarzo.toml, for programs with more than one file.
  • Editors sets up the language server in your editor.
  • The examples in the repository are programs with their expected output.