Q+ 文档
首页 Playground

Q+ 快速上手 / Getting Started（1.9.0-dev / spec v4.40）

English. Q+ is a statically typed systems/application language with a self-hosted compiler (qboot), bytecode VM (bqvm) and an ELF AOT backend (cgtest_aot, Linux x86-64). This tutorial takes you from build to your first VM/AOT program, tests and next steps. Commands/outputs were run on the 1.9.0-dev candidate (v190_rc1) on Linux x86-64. 1.9.0-dev is a release candidate (NOT PUBLISHED), not a final release.

中文：Q+ 是静态类型系统/应用语言，自带编译器 qboot、字节码 VM bqvm 与 ELF AOT 后端 cgtest_aot（仅 Linux x86-64）。本教程覆盖构建 → 第一个程序 → VM/AOT 运行 → 测试 → FAQ/下一步；命令与输出在 1.9.0-dev 候选（v190_rc1）Linux x86-64 实测。

0. 前置条件（Prerequisites）

1. 构建（Build）

bash tools/build.sh       # ~1–2 分钟

实测输出（尾部）：

Phase 3: CodeGen
  Constants: 257 Code bytes: 76365
[Q+ build] artifacts in .../build
b526b807...  build/bqvm
bd0dec4b...  build/bqvm_small
7248ce0d...  build/qboot.qbc
1dc2d240...  build/cgtest.qbc
cbd42172...  build/cgtest_aot

锚点应与 BUILDING 的 5 锚点一致；bootstrap/qboot.qbc 与 bootstrap/cgtest_aot 为固定点。

2. 第一个程序（First program）

use std.io;

fn main() -> i32 {
    print("Hello, Q+!\n")
    return 0
}
build/bqvm --timeout-ms 0 build/qboot.qbc hello.q -o hello.qbc
# Phase 3: CodeGen / Constants: 19 Code bytes: 796

3. VM 运行（Run on the VM）

build/bqvm hello.qbc
# Hello, Q+!

4. AOT ELF 运行（AOT）

AOT 工具用位置参数 cgtest_aot <in.qbc> <out.elf>（不是 -o），且不写可执行位：

build/cgtest_aot hello.qbc hello.elf   # EMIT_OK code=54587 elf=57392
chmod +x hello.elf
./hello.elf                            # Hello, Q+!

AOT 未支持能力（线程/async/FFI/std.fs/网络/未支持 sys）loud（rc=5/no ELF 或运行期 trap）。 AOT 网络可行性结论 B：本轮不交付、AOT 保持 loud（AOT-net feasibility）。

5. 测试（Test）

bash tools/test.sh        # 通过时末行 QPLUS_LANGUAGE_TESTS_PASS
bash tools/test_qfmt.sh   # qfmt 306 checks / 29 fixtures

6. 文档站与 Playground（Docs site & Playground）

cd site
python3 build_site.py --qplus-root ..   # 78 页 / 155 checks（候选）
python3 ci/selftest.py                  # 155/155 PASS
python3 playground.py                   # http://127.0.0.1:8787/

Playground 是本地/内部演示，非沙箱/非公网安全边界；运行器限额不变 （安全边界）。

7. FAQ / 常见问题

8. 下一步（Next steps）

English walkthrough

Prerequisites: Linux x86-64, Python 3.11+, bash/C toolchain; 1.9.0-dev is a release candidate (NOT PUBLISHED).

bash tools/build.sh
cat > hello.q <<'EOF'
use std.io;

fn main() -> i32 {
    print("Hello, Q+!\n")
    return 0
}
EOF
build/bqvm --timeout-ms 0 build/qboot.qbc hello.q -o hello.qbc
build/bqvm hello.qbc                    # Hello, Q+!
build/cgtest_aot hello.qbc hello.elf    # EMIT_OK code=54587 elf=57392
chmod +x hello.elf && ./hello.elf       # Hello, Q+!
bash tools/test.sh                      # QPLUS_LANGUAGE_TESTS_PASS

Candidate anchors: bqvm b526b807…, bqvm_small bd0dec4b…, qboot 7248ce0d…, cgtest.qbc 1dc2d240…, cgtest_aot cbd42172…. See Language Guide, FAQ, SPEC_SUMMARY.en; network Phase4 is a VM-only loopback POC and AOT networking is conclusion B (not delivered, AOT loud).

← Q+ Hub