Building Q+ from Source

This document describes the standalone build, the self-hosting step, the regression suite, and how to troubleshoot a build that does not match the expected artifacts.

Requirements

• Linux x86-64 (the validated platform; other platforms are not tested in this release)
• gcc (GCC 8 or newer is recommended; the build uses -ffile-prefix-map)
• bash and standard coreutils (sha256sum, mktemp, mv)
• GNU make is not required

No system libraries beyond the C standard library are needed. tools/build.sh uses gcc by default and honors the CC environment variable, so a compatible C compiler can be selected when needed.

Quick build

From the repository root:

tools/build.sh

The script produces:

• build/bqvm sha256 ca0539df3190874eadae942cc1a1166bc0213475abbf146469e42eff17ee79a0 (traceback/行表版；u64 bitwise opcodes)
• build/qboot.qbc sha256 abd9fb8341a23efcb86d0b073331cd2e1247d920a33ee7b0108ff28f908d0d63 (u64 bitwise TC/gen)

Both artifacts are executable directly; no installation step is required. tools/build.sh also accepts an optional output directory:

tools/build.sh <tmp>/qplus-build

What the build does

tools/build.sh runs four stages: VM build, two-step self-host compiler, AOT toolchain rebuild (verified against the shipped fixed point), and a small-heap helper VM.

1. Build the VM. It compiles the C sources of bqvm and its minimal runtime (in src/runtime/bootstrap_qvm/ and src/runtime/mini_kernel/) into build/bqvm. The compiler flags include -ffile-prefix-map and -fmacro-prefix-map, which remove the absolute path of the source tree, so a build from any directory produces the same binary for the same C toolchain.
2. Self-host the compiler. The freshly built build/bqvm runs bootstrap/qboot.qbc on the compiler source src/compiler/qboot/qboot_v52_final3_fix2.q and writes build/qboot.qbc. The bootstrap bytecode compiles the compiler; the output is the compiler.

The script prints the two artifact paths and their SHA-256 checksums on success:

[Q+ build] bqvm=<outdir>/bqvm qboot=<outdir>/qboot.qbc
<sha256>  <outdir>/bqvm
<sha256>  <outdir>/qboot.qbc

Expected hashes

For Q+ 1.19.0-dev, a clean build with the reference toolchain produces:

bootstrap/stage0.q sha256 7a954aa542678d2d44e5e239e600c712c20fe974510c57809d45595036713aab. bootstrap/SHA256SUMS is kept in sync. Reproducibility signals: build/qboot.qbc == bootstrap/qboot.qbc, and build/cgtest_aot == bootstrap/cgtest_aot (AOT fixed point).

Build from scratch

The build does not require an existing build/ directory. To force a clean build:

rm -rf build
tools/build.sh

bootstrap/qboot.qbc is part of the repository and must not be deleted; it is the seed for the self-hosting step.

Run the regression suite

tools/test.sh

If build/bqvm or build/qboot.qbc is missing, the script builds it first. The suite checks:

1. Examples. All 193 programs in src/examples/ must compile.
2. Type-check fixtures. All src/tests/typecheck/good*.q fixtures must compile.
3. Expected failures. parse_*.q fixtures must exit with status 2 (parse error), and bad*.q fixtures must exit with status 4 (type error), exactly as their names promise.
4. Feature and semantics fixtures. All 9 fixtures in src/tests/features/ and all 6 fixtures in src/tests/semantics/ must compile.
5. Runtime smoke test. src/examples/arith_sum.q is compiled, executed, and must print 5050.

On success the script prints:

QPLUS_LANGUAGE_TESTS_PASS

On failure it prints one or more FAIL … lines and exits with a non-zero status. The robustness fixtures in src/tests/robustness/ exercise the compiler's handling of malformed input; they are not part of tools/test.sh in this release.

The suite is fast: on a typical machine a clean build takes a few seconds, and the regression run then takes around ten seconds.

Compile and run a program manually

# Compile: <compiler-qbc> <source.q> -o <output.qbc>
build/bqvm --timeout-ms 0 build/qboot.qbc src/examples/fib.q -o <tmp>/fib.qbc

# Run: <program.qbc> [program arguments...]
build/bqvm <tmp>/fib.qbc

Notes:

• -o <file> names the output file. Without it the compiler writes output.qbc in the current directory; always pass -o in scripts so the output path is explicit.
• --timeout-ms N limits VM execution to N milliseconds. The default is 60000; 0 disables the limit. The build and test scripts use --timeout-ms 0 when compiling.
• Arguments after the QBC file are passed to the Q+ program.
• build/bqvm --help prints all VM options; build/bqvm --version prints the VM and minimal-runtime versions.

What the standalone build does not include

The build script covers the VM and the self-hosted compiler. The AOT backend sources under src/compiler/qplusc/ are included in the repository but are not built by tools/build.sh in this release. The language regression suite and all commands in this document use the bytecode toolchain only.

Continuous integration

.github/workflows/ci.yml runs tools/build.sh followed by tools/test.sh on ubuntu-latest for pushes and pull requests.

Troubleshooting

The build fails with missing source: …

The checkout is incomplete. Re-extract the release archive or re-clone the repository and confirm that tools/build.sh lists only files that exist under src/runtime/.

gcc: command not found

Install a C toolchain. On Debian/Ubuntu:

sudo apt update && sudo apt install build-essential

Permission denied when running tools/build.sh

Either run the script through the shell or restore the executable bit:

bash tools/build.sh
# or
chmod +x tools/build.sh tools/test.sh

build/qboot.qbc has the wrong checksum

The Q+ compiler output is deterministic. A mismatch almost always means the source tree differs from the release:

1. Check sha256sum bootstrap/qboot.qbc. It must be 44c21db965319cd87c2ca6d83c683e316eadafdee52cbdd2ad04af3e83cf100b.
2. Make sure you did not edit src/compiler/qboot/, stdlib/std/, or bootstrap/.
3. Rebuild from a clean directory (rm -rf build) and compare again.
4. Confirm that build/bqvm behaves: it must be the VM produced by this repository, and build/bqvm --version must succeed.

If bootstrap/qboot.qbc matches but build/qboot.qbc does not, the compiler source has been modified.

build/bqvm has a different checksum

This is expected when the host C toolchain differs. Use build/qboot.qbc as the reproducibility check, and run tools/test.sh to confirm the VM behaves correctly. If you need the reference binary, use the release artifact built with the reference toolchain.

A compile times out

Increase or disable the VM execution limit for the compile step:

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

Release tree components（1.30.0-dev / spec v4.61）

Tests fail with FAIL …

Read the failing line: it names the fixture and the unexpected condition. A single failure usually comes from a locally modified fixture or standard-library module. Re-check your changes against docs/qplus_language_spec.md and CONTRIBUTING.en.md, then open an issue if the failure reproduces on an unmodified checkout.

1.19.0-dev build notes (2026-10-30)

The v1.1 compiler source is larger than the v1.0 bootstrap compiler's source-read window, so the build is a two-step bootstrap (bootstrap/qboot.qbc -> bootstrap/stage0.q -> src/compiler/qboot/...). The rebuilt compiler is verified to be a deterministic fixed point.

The build additionally produces:

• build/cgtest.qbc sha256 d0295342b67c15e65ba539511c4241146e0905c1ee75e2387a619bad08eae2f1 (AOT u64 bitwise codegen) must equal the shipped bootstrap/cgtest_aot fixed point);
• build/stage0.qbc - capacity-only bootstrap compiler;
• build/bqvm_small sha256 e24b284b36b173003af532d36780d47628c3fab692835ef349fa4fd8405af4f6 (small-heap VM)

Relative use std.<module> paths are resolved against the current working directory. Set QPLUS_ROOT=<tree-root> to additionally resolve them when running from another directory (the build/test scripts run from the tree root, so this is optional).

tools/test.sh covers examples, typecheck fixtures, features/semantics, type bounds, integer matrix, runtime errors (including heap exhaustion), and VM/AOT parity plus AOT loud-fail checks. Release packaging is tools/package.sh.

Clean-build anchors for 1.19.0-dev:

• build/bqvm sha256 ca0539df3190874eadae942cc1a1166bc0213475abbf146469e42eff17ee79a0 (traceback/行表版；u64 bitwise opcodes)
• build/qboot.qbc sha256 abd9fb8341a23efcb86d0b073331cd2e1247d920a33ee7b0108ff28f908d0d63 (u64 bitwise TC/gen)
• build/cgtest.qbc sha256 d0295342b67c15e65ba539511c4241146e0905c1ee75e2387a619bad08eae2f1 (AOT u64 bitwise codegen)
• build/cgtest_aot sha256 1e619ad37109b383ecc3fb1343898a06196db4f1ea5af41849fcfc2c664a268c (deterministic; equals bootstrap/cgtest_aot fixed point; u64 bitwise)

P2-B1 build notes (2026-10-29)

The AOT ELF tool now implements integer/float conversions (I2F, F2I, I2I) and CALL_INDIRECT (function values in globals and struct fields), with VM/AOT byte-parity tests. Unknown or unmapped sys_* builtins still fail loudly (exit code 5, no ELF). Small-int boundary checks now also cover array-element assignment, impl method arguments and UFCS arguments. The FS/payload AOT compiler (cgtest_fs.q, not part of the language release) was hardened the same way in the development tree.

P2-B2 notes (2026-10-29)

• Runtime traceback (VM, stderr): function name + bytecode pc per frame; QPLUS_TRACEBACK=0 disables it. Source line numbers require a QBC debug line table (not implemented yet).
• Benchmark suite: bench/run.sh (9 programs; bqvm vs AOT ELF, plus C references) writes raw per-run data to bench/results/. Known AOT correctness gaps surfaced by the suite are recorded honestly in bench/README.md.
• Wrapping arithmetic: use std.alg provides wrapping_add/sub/mul_u8/_u16/_u32/_i8/_i16/_i32 (explicit wraparound, coexisting with default checked semantics).
• AOT now fails loudly (rc=5, no ELF) on exponent-notation float constants (QBC const type 10) instead of hanging.

P2-B3 notes (2026-10-29)

• qboot now writes a minimal debug line table after the QBC globals section (u32 count, then (fn, pc, line) u32 triples). bqvm consumes it so runtime tracebacks print at <fn> (line <N>, pc=<offset>); legacy QBC files without the section still load (traceback falls back to pc only). The AOT backend ignores the debug section and does not emit tracebacks (its error lines remain byte-identical to the VM).
• Fixed three AOT correctness bugs surfaced by the benchmark suite: integer DIV/MOD zero-check (test r,0 always set ZF) and LEN on strings (read as an array header). bench/ is now 9/9 VM/AOT-consistent and is part of tools/test.sh.

P2-C1 notes (2026-10-29)

• Nested functions may read enclosing function locals/parameters: captures are passed as implicit by-value arguments at each call site (snapshot semantics; writes inside the nested function only affect its local copy). Self-recursion is supported; taking the address of a capturing nested function or delaying the call through a fn slot is rejected loudly (TC).
• Generic struct instantiations (Box<i32> vs Box<string>) are tracked by the type checker for field typing and assignment checks (erased codegen: one struct layout, one code copy).
• dyn Trait is a clear [TC11] loud error (static dispatch only); static trait contracts keep working.

P2-C2 notes (2026-10-29)

• async fn and await are accepted; await e desugars to await_task(e) from std.alg. The current PoC is a single-threaded cooperative task queue: spawn(fn()->i32) enqueues, await_task(id) runs queued tasks FIFO to completion (deterministic; no suspension or preemption); yield_now() runs one queued task. VM and ELF AOT both support it (byte-parity tested). Suspending futures, cancellation and OS threads/channels are not implemented yet; the design blueprint is docs/CONCURRENCY.md.

编辑器对齐（B2）：editors/vscode 源码树为 0.5.0 dev 基线；v1.0 发布 pack 的 editors 0.6.0 由发布工程 overlay 构建。LSP 支持组件 = 0.6.0；0.9.0/0.10.0/0.11.0/0.12.0 为 OPTIONAL/DEV（不进 tar、未发布 Marketplace）。