Q+ Quick Start (10 minutes)

This guide takes you from a source checkout to a running Q+ program, including a native ELF build, on a Linux x86-64 machine with gcc and bash. It takes about ten minutes, most of which is reading.

The commands below are for Q+ Language 1.1.0-dev (language specification v4.36). Run them from the repository root (the directory that contains tools/ and src/), or set QPLUS_ROOT to the repository root if you run from elsewhere.

1. Get the source

Use the release source archive:

tar xzf qplus-language-1.1.0-dev-release.tar.gz
cd qplus-language-1.1.0-dev

or a Git clone of the repository:

git clone <repository-url> qplus
cd qplus

The directory name does not matter; everything below uses paths relative to the repository root.

2. Build the toolchain

tools/build.sh

The script builds the bytecode VM from C sources, self-hosts the compiler with a two-step bootstrap, and rebuilds the AOT toolchain. It takes about 20–30 seconds on a typical machine and prints the SHA-256 checksums of the artifacts:

On the reference Linux x86-64 toolchain a clean build produces:

build/bqvm        c94042851edc62bb04d30bbf2cee32fa4b650a6816806991ed3a910459321fe0
build/qboot.qbc   378f5f858d8553760ae4b55aecac7773cdbec6386a6a986dd34a51d722175b34
build/cgtest.qbc  f2f24e897891cb48159d784bce282909820c2f7974eeee574f2e3d431cd6eec1
build/cgtest_aot  7ca041362c45bd8759077595abdc68429e8961ef3cc0ca01ddbf147e0ebdb316

build/qboot.qbc is deterministic and is the reproducibility anchor; if it does not match, see BUILDING.en.md. The checksum of build/bqvm can legitimately differ with a different host C toolchain.

3. Write your first program

Create a file named hello.q in the repository root:

fn main() -> i32 {
    print("Hello, Q+!\n")
    return 0
}

Execution starts at fn main. By convention the entry point is declared fn main() -> i32; the integer it returns becomes the process exit status. print is a language builtin: it writes its argument without adding a newline, which is why the example includes the "\n" explicitly.

4. Compile it

build/bqvm --timeout-ms 0 build/qboot.qbc hello.q -o hello.qbc

The compiler prints its phases (lexer, parser, code generation) and exits with status 0. A non-zero status means compilation failed; see common errors.

• The first argument is the compiler bytecode (build/qboot.qbc).
• The second argument is your source file.
• -o hello.qbc names the output file. If you omit it, the compiler writes output.qbc in the current directory.
• --timeout-ms 0 disables the VM execution limit for this compile. The default limit is 60000 ms; compilation is normally much faster.

5. Run it

build/bqvm hello.qbc

Output:

Hello, Q+!

The compiled program is an ordinary file; you can copy hello.qbc to another machine and run it with the same build/bqvm binary.

Check the exit status of main:

cat > status.q <<'EOF'
fn main() -> i32 {
    return 42
}
EOF
build/bqvm --timeout-ms 0 build/qboot.qbc status.q -o status.qbc
build/bqvm status.qbc
echo $?          # 42

Two details that surprise new users:

• print does not append a newline. Add "\n" yourself, or use the println_* helpers from std.io when running on the VM.
• On Linux, bqvm currently writes printed lines with CRLF (\r\n) endings. If you compare output in a script, tolerate or strip \r. The specification records this as an observed behavior.

6. Build a native ELF

build/cgtest_aot hello.qbc hello.elf
chmod +x hello.elf      # the AOT tool writes the file, not its executable bit
./hello.elf

The ELF backend is independent of the VM and produces a standalone native binary for the same QBC. Its stdout and exit status match the VM's for supported features; runtime errors also print a stderr traceback with real source lines.

The AOT backend is deliberately loud about unsupported features: it rejects programs that reference VM service builtins, extern "C" FFI shims, or std.panic at compile time with exit status 5, and writes no ELF. In particular, importing std.io pulls in VM service builtins, so AOT-friendly programs should use the print builtin as in this example. Async/thread primitives are the exception: the ELF builds, and executing such a primitive traps at runtime (AOT: async primitives unsupported, exit status 1).

# Example loud failure: std.io is a VM-service module.
cat > io_hello.q <<'EOF'
use std.io
fn main() -> i32 {
    println_str("Hello from the VM")
    return 0
}
EOF
build/bqvm --timeout-ms 0 build/qboot.qbc io_hello.q -o io_hello.qbc
build/cgtest_aot io_hello.qbc io_hello.elf   # exit status 5, no io_hello.elf

7. Explore

# Compile and run one of the 193 bundled examples.
build/bqvm --timeout-ms 0 build/qboot.qbc src/examples/fib.q -o /tmp/fib.qbc
build/bqvm /tmp/fib.qbc          # prints 6765

# Run the language regression suite (builds first if build/ is missing).
tools/test.sh                    # ends with QPLUS_LANGUAGE_TESTS_PASS

# Optional: benchmark VM vs AOT ELF vs C reference kernels.
bench/run.sh 3

Concurrency notes for v4.18 (P2-C10 safety fixes):

• The std.async stackful task scheduler is main-thread-only. Worker threads that call async primitives fail loudly (async: tasks are not supported in worker threads); use std.thread channels for cross-thread coordination.
• Thread state is synchronized. A concurrent second join of the same thread is a loud error (thread: join already in progress on this tid); a repeated join from the same thread is idempotent; creating more than 16 threads is a loud error (spawn limit exceeded (max 16 threads)).
• Blocking channel sends/receives are interruptible by the global --timeout-ms budget; use the *_timeout channel APIs for precise per-call deadlines. Channel slots are not recycled after close, and undrained string messages are retained until process exit.
• Read LANGUAGE_GUIDE.en.md for the full language: types and the integer matrix, generics, traits, macros, FFI, async tasks, threads/channels/pools, the AOT support matrix, and known boundaries.
• Browse src/examples/ — sorting, trees, graphs, dynamic programming, string processing, and more.
• Read BUILDING.en.md for build internals and anchors.
• Read FAQ.en.md for licensing, async/threads/macros/FFI, editor support, and the qpm package manager.

Common errors

If a command still fails, collect the exact command, the full output, the output of build/bqvm --version, and your gcc --version, then open an issue using the repository's issue template.