Q+ Language

Q+ is a statically typed systems and application programming language. It comes with a self-hosted compiler (qboot), a bytecode virtual machine (bqvm), a standard library, and a language specification.

This repository contains the language only. The a separate product line (另一产品线) kernel and OS services are a separate closed-source product line and are not part of this repository.

Quick start · Language guide · Building from source · Contributing · FAQ · Specification

Highlights

• Statically typed. A compile-time type checker runs after parsing and before code generation, with clear diagnostics and distinct exit codes for parse, semantic, and type errors.
• Self-hosted compiler. qboot compiles itself from src/compiler/qboot/qboot_v52_final3_fix2.q; the resulting qboot.qbc is deterministic and byte-for-byte reproducible.
• Small bytecode toolchain. Programs are compiled to QBC bytecode and run on bqvm, which is built from a compact C runtime. The standalone build needs only gcc and bash.
• Expressive core. Structs, enums with payloads, match, inherent impl methods, function pointers, fixed-size and dynamic arrays, UTF-8 strings, nested functions, and explicit modules.
• Explicit semantics. Composite values (structs, arrays) have reference semantics; integers are tagged and do not wrap; runtime failures abort with a clear message instead of throwing catchable exceptions.
• Batteries included. 942 standard-library modules under stdlib/std/ and 193 runnable example programs under src/examples/.
• Documented boundaries. The specification records the known limits of the type checker, inference, arrays, and the error model (see the language guide and specification §7.4, §7.5, and §8.3).
• AOT coverage (P2-B1). Int/float conversions (I2F, F2I, I2I) and function-pointer indirect calls (CALL_INDIRECT for fn slots in globals and struct fields) are compiled natively by the ELF AOT backend, with byte-for-byte VM/AOT parity; array-element assignment, impl method arguments and UFCS arguments get checked-integer boundary checks; unsupported sys_* builtins still fail loudly.
• Observability & benchmarks (P2-B2). Runtime failures of bqvm print a stderr traceback with function names and bytecode pc; bench/run.sh records honest VM/AOT/C timings (raw data in bench/results/); explicit wrapping_add/sub/mul_* APIs coexist with the default checked integer semantics.
• AOT correctness + line numbers (P2-B3). Three AOT codegen bugs found by the benchmark suite (integer DIV/MOD zero-check, LEN on strings) are fixed; bench/ is 9/9 VM/AOT-consistent and runs in tools/test.sh. VM tracebacks now show source lines from a minimal QBC debug line table (AOT does not consume it yet).
• Language abstractions (P2-C1). Nested functions may capture enclosing locals (by-value snapshot; outer values are not mutated); generic struct instantiations are tracked by the type checker (Box<i32> vs Box<string>, still erased codegen); dyn Trait is an explicit loud error (static dispatch only).
• Concurrency (P2-C2). async fn/await syntax plus a minimal cooperative single-thread task queue (spawn, await_task, yield_now in std.alg), VM/AOT parity. Suspending futures, cancellation and OS threads/channels are designed but not implemented.
• FFI (P2-C3). extern "C" fn with a controlled VM shim table (puts/strlen); unknown externs are loud load errors, non-C ABIs are compile errors, AOT ELF loud-fails.
• Macros (P2-C3). Design only (docs/MACROS.md) — not implemented.
• Macros (P2-C4). Declarative macro/name!(...) with token-level expansion, category checks, call-site diagnostics, recursion limit and minimal gensym hygiene.

Quick start

Requirements: Linux x86-64 with gcc and bash.

tools/build.sh
build/bqvm --timeout-ms 0 build/qboot.qbc src/examples/arith_sum.q -o <tmp>/arith_sum.qbc
build/bqvm <tmp>/arith_sum.qbc

The last command prints 5050. The build produces two artifacts:

• build/bqvm — the bytecode VM
• build/qboot.qbc — the self-hosted compiler

For a guided first program, see QUICKSTART.en.md. For exact build hashes and test commands, see BUILDING.en.md.

Repository layout

Build and test

tools/build.sh   # build/bqvm and build/qboot.qbc
tools/test.sh    # compile examples and language fixtures, run a runtime smoke test

A passing run ends with QPLUS_LANGUAGE_TESTS_PASS. See BUILDING.en.md for expected hashes, a detailed description of what each script does, and troubleshooting.

Editor support

The release package's supported VS Code extension is 0.6.0 (190 checks ALL PASS; the release tree also contains the extension sources): syntax highlighting and snippets, a zero-dependency formatter (Q+: Format Document), build / run / test / ELF AOT commands, and an offline language server (qplus-lsp, stdio JSON-RPC, no network or third-party dependencies).

The language server implements an LSP v1.0 subset plus the 0.6 editing features: document/workspace symbols, go-to-definition, references, rename (workspace edits with prepare-rename), signature help, semantic tokens, hover/completion, code actions, inlay hints, document links, code lenses, workspace folders, workspace/executeCommand, and real compiler, runtime (Runtime error / Traceback) and ELF AOT (AOT_UNSUPPORTED_*) diagnostics.

Two optional/dev LSP lines exist outside the release tar: 0.7.0/0.8.0 are earlier dev components, and 0.12.0 is the latest optional/dev .vsix (0.9.0/0.10.0/0.11.0/0.12.0 are earlier dev lines). None is a supported release component, shipped in the language tar, or Marketplace published; their features are not a released capability until a future release explicitly includes them. The release tree's VS Code sources are 0.6.0.

.vsix packages are built on demand from the extension sources (scripts/package.sh, requires Node.js/npm) and are not committed to this repository; see the extension README for install and packaging instructions.

Community, governance and releases

• GOVERNANCE.md — decision model, roles, version and release policy
• MAINTAINERS.md — Maintainer/maintainer roles (placeholder until publication)
• SUPPORT.md — where to get help and support boundaries (no SLA)
• RELEASING.md — candidate → freeze → G0–G7 → Maintainer approval → publication runbook (unauthorized publication is prohibited)
• ROADMAP.md — public 1.4.x → 2.0 plan, platform matrix, and non-goals
• P0_RELEASE_CHECKLIST.md — v1.0 publication checklist and the 15 non-claim clauses
• GITHUB_READY.md — repository readiness state and Maintainer decisions
• CODE_OF_CONDUCT.md / SECURITY.md — community expectations and private vulnerability reporting

Status: v1.21.0-dev is a release candidate, NOT PUBLISHED. OS SDK 1.18.0 is an external prototype (API-freeze candidate; 27/27 tests, 13 PASS/3 PARTIAL/4 BLOCKED (api_stability 128/0, examples 5/5); net BLOCKED; not part of the release package); LSP/VS Code 0.6.0 is the supported component, while 0.9.0/0.10.0/0.11.0 are optional/dev .vsix builds (not in the tar and not Marketplace-published).

Status

The language has known, documented boundaries: if/match are statements rather than expressions, u64 is full 64-bit, and a few conversion opcodes are not yet implemented by the AOT backend (they fail loudly). See specification §7.4/§7.5.

What's new in v1.30.0-dev

• M2 macro step 3 single-level nested repetition (A.30.13): the outer repetition group must directly reference one variadic (sequential expansion); one inner repetition group is allowed inside (depth limit 2); p34_m2_nested (m2nest!(1,2; 3,4)) -> VM/AOT 134234; p33 12|348|9 retained; negatives n40/n41/n42 rc=2 + stable messages; MACRO_M2_TEST_PASS 22/0; M1 39/0 no regression; wrapper-type nesting/depth>2/ fixed-params+multi-variadic/zip/recursive emit not done; MB remains incomplete.
• AOT traceback Round55 (12/12 + deep10): 12 byte-identical cases (including deep10 depth parity) + AOT-only diagnostic (async trap fixed message/rc=1/no traceback); TRACEBACK_PARITY_PASS 12/12; residuals other natdisp/shared stub cases not per-item; no full parity claim.
• i64 small-constant accumulation (§9.5.11, unfixed/audited): repro 2^57×8 VM=2^60/AOT=-2^60 etc.; two fixes ineffective/contaminated bootstrap -> reverted; p19 boundary still PASS; needs offline qbc rewrite/stable helper (2-4 days); no i64-full/unconditional full-u64 claim.
• 1.29 test correction: f64 exponent constants (1.5e300) AOT success + VM/AOT parity measured (no overall float parity claim).
• Retained: AOT async M3/M3b (AOT-only POC), AOT text 4 MiB, std.fs AOT four batches, MB batches 1–6, AOT-native POC4, A.30.9 float residual closure.
• T8 English summaries: 13 A-20 docs keep inline ## English Summary; FLOAT_PARITY/MB_M04/U64_A5/ MB_GAPS/AOT_ASYNC_M2 summaries updated; summary-level, not full translation.
• OS SDK 1.18 (external prototype): 14/2/4, tests 29/29, fuzz 339, 128/0, 5/5; not released/not API 1.0.
• IDE 0.19 overlay (external, not in tar; description lags); language-tree supported component 0.6.0.
• B2 documentation/site finalization: 1.30.0-dev/spec v4.61; final anchors bqvm ca0539df/ bqvm_small e24b284b/qboot abd9fb83/cgtest.qbc d0295342/cgtest_aot 1e619ad3; second build SAME; NOT PUBLISHED.

Docs

• QPM install/vendor · TSAN limitations · Windows AOT spike3 · OS SDK 1.18.0 MVP · OS SDK API stability · OS SDK net design · STD_FS (planned) · CI · qfmt · AOT-native design
• English summaries for the Chinese tooling/OS-SDK/AOT docs: docs/ENGLISH_SUMMARIES.md
• STD API coverage (Chinese authoritative / English summary): docs/STD_API.md · docs/STD_API.en.md
• Playground: docs/PLAYGROUND.md · Windows/Wine guide: docs/WINDOWS_WINE_GUIDE.md
• Advanced language guide (Chinese authoritative / English summary): docs/LANGUAGE_GUIDE.md · docs/LANGUAGE_GUIDE.en.md
• Contributing: docs/CONTRIBUTING.md · Release engineering: docs/RELEASE_ENGINEERING.md · Repo layout: docs/REPO_LAYOUT.md
• Download page template (Maintainer-fill): site/content/download.md · Deployment template: deploy/README_DEPLOY.md
• Getting Started tutorial (bilingual): docs/GETTING_STARTED.md
• English specification summary: docs/SPEC_SUMMARY.en.md
• English 1.6.0 release summary: docs/WHATS_NEW_1.6.0.en.md
• English 1.5.0 release summary: docs/WHATS_NEW_1.5.0.en.md
• Language/spec: LANGUAGE_GUIDE.en.md · docs/qplus_language_spec.md
• CHANGELOG.md, BUILDING.en.md, QUICKSTART.en.md, FAQ.en.md, SECURITY.md, CODE_OF_CONDUCT.md
• Benchmark baseline & regression（单机非权威，仅回归）
• Network Phase1 POC · Network Phase2
• Playground deployment & security boundary · Benchmark baseline
• English summaries
• AOT async M2 (fiber basics, AOT-only POC): docs/AOT_ASYNC_M2.md · MB gaps audit: docs/MB_GAPS.md · std.fs AOT first batch: docs/STD_FS_AOT.md
• Inline English summaries (v320/v330): NET Phase7–12, AOT event-loop feasibility, cast semantics, qpm transparency-log design, std.env args, AOT async M2, MB gaps, std.fs AOT and Windows AOT docs carry ## English Summary sections (summary-level, not full translation).
• Network Phase3
• String perf POC
• Security/ASAN summary
• Network Phase4
• AOT-net feasibility (conclusion B)
• QPM production POC
• AOT network POC
• Network Phase5
• SBOM
• SBOM signing POC
• std.net API reference
• OS SDK 1.18.0
• Float parity
• QPM production POC
• QPM key rotation design
• Cast semantics
• Network Phase8
• QPM transparent log design
• STD env args
• AOT event-loop feasibility (external POC, not integrated)
• QPM transparent log design
• AOT event-loop / epoll unified
• Network Phase11
• QPM production POC (SBOM/graph)
• Remaining gaps register
• v1.0 版本决策记录