diff --git a/doc/dev-setup.md b/doc/dev-setup.md index 813a1b5..81926a0 100644 --- a/doc/dev-setup.md +++ b/doc/dev-setup.md @@ -13,6 +13,8 @@ |------|------|------| | Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` | | Git | 任意近期版本 | `git --version` | +| GCC / Binutils | 原生依赖编译与链接 | `cc --version` / `ld --version` | +| Go | ≥ 1.22(仅构建 `plugins/web` 与 web 扩展测试需要) | `go version` | 安装 Rust(若尚未安装): @@ -21,7 +23,17 @@ 本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。 -**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。 +**不需要:** Flex、Bison、LLVM。Node/npm 只在开发 VS Code 扩展时需要;核心 Rust 开发不依赖它们。 + +本仓库提供了固定 Rust 版本:`rust-toolchain.toml` 使用 Rust 1.81.0,并启用 +`rustfmt` / `clippy`。在受限开发容器中,推荐先加载仓库环境脚本: + +```bash +source scripts/dev-env.sh +``` + +脚本会优先使用 `target/toolchain/` 下的工具链,普通开发机则回退到 PATH 中已有的工具, +并把 Cargo、Go 缓存和临时目录放在工作区内。 --- @@ -36,6 +48,12 @@ cargo test cargo run -- run tests/structure/hello.mq.md ``` +构建 Go web 插件(完整扩展开发需要): + +```bash +bash scripts/build-web-plugin.sh +``` + 当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。 > 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。 @@ -50,6 +68,13 @@ cargo fmt cargo clippy --all-targets ``` +只验证 Rust 核心时可运行 `cargo test --locked --lib`;包含全部扩展的 gold 测试需要 Go, +并建议单线程运行以避免共享临时夹具互相影响: + +```bash +cargo test --locked --test gold -- --test-threads=1 +``` + 代理下拉 crate(可选,与 git 推送类似): ```bash diff --git a/rust-toolchain.toml b/rust-toolchain.toml new file mode 100644 index 0000000..0f102b7 --- /dev/null +++ b/rust-toolchain.toml @@ -0,0 +1,4 @@ +[toolchain] +channel = "1.81.0" +profile = "minimal" +components = ["rustfmt", "clippy"] diff --git a/scripts/dev-env.sh b/scripts/dev-env.sh index c6f95f3..50e5a10 100755 --- a/scripts/dev-env.sh +++ b/scripts/dev-env.sh @@ -1,11 +1,11 @@ #!/usr/bin/env bash -# Marqdo dev environment for this sandbox (glibc 2.36 host, no system gcc/python3/go). +# Marqdo dev environment. # # Usage: source scripts/dev-env.sh # -# Everything lives under target/toolchain/ (bundled): rust 1.81, zig 0.13 (as cc), -# go 1.25, python 3.12. Zig also solves the "release binary needs GLIBC_2.39" -# problem by targeting x86_64-linux-gnu.2.36. +# If a bundled toolchain is present under target/toolchain/, it is preferred; +# otherwise the script keeps using tools already installed on PATH. This makes +# the script work both in the maintained sandbox image and on a normal dev host. # # Two non-obvious constraints this script encodes: # 1. $HOME is not writable -> zig/rust caches must be redirected explicitly. @@ -15,24 +15,33 @@ _marqdo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" _tc="$_marqdo_root/target/toolchain" -_zshim="/workspace/qdagent/.tools/zigcc" +_zshim="${MARQDO_ZIG_SHIM:-$_marqdo_root/.tools/zigcc}" -export RUSTUP_HOME="$_tc/rustup" -export CARGO_HOME="$_tc/cargo" -export GOCACHE="$_tc/gocache" -export GOPATH="$_tc/gopath" -export TMPDIR="$_tc/gotmp" -export ZIG_GLOBAL_CACHE_DIR="/workspace/qdagent/.tools/zigcache" -export ZIG_LOCAL_CACHE_DIR="/workspace/qdagent/.tools/zigcache" +_prepend_existing() { + [ -d "$1" ] && PATH="$1:$PATH" +} -export PATH="$_zshim/bin:$_tc/python/bin:$_tc/go/bin:$_tc/cargo/bin:$PATH" +export RUSTUP_HOME="${RUSTUP_HOME:-$_tc/rustup}" +export CARGO_HOME="${CARGO_HOME:-$_tc/cargo}" +export GOCACHE="${GOCACHE:-$_tc/gocache}" +export GOPATH="${GOPATH:-$_tc/gopath}" +export TMPDIR="${TMPDIR:-$_tc/tmp}" +export ZIG_GLOBAL_CACHE_DIR="${ZIG_GLOBAL_CACHE_DIR:-$_tc/zigcache}" +export ZIG_LOCAL_CACHE_DIR="${ZIG_LOCAL_CACHE_DIR:-$_tc/zigcache}" + +_prepend_existing "$_zshim/bin" +_prepend_existing "$_tc/python/bin" +_prepend_existing "$_tc/go/bin" +_prepend_existing "$_tc/cargo/bin" # Rust: link through zig cc pinned to glibc 2.36 so the binary runs on this host. -export CC="$_zshim/cc" -export CXX="$_zshim/cc" -export AR="$_zshim/ar" -export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER="$_zshim/cc" +if [ -x "$_zshim/cc" ] && [ -x "$_zshim/ar" ]; then + export CC="$_zshim/cc" + export CXX="$_zshim/cc" + export AR="$_zshim/ar" + export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER="$_zshim/cc" +fi mkdir -p "$TMPDIR" "$GOCACHE" "$GOPATH" "$ZIG_GLOBAL_CACHE_DIR" -echo "marqdo dev-env: rust=$(rustc --version 2>/dev/null | cut -d' ' -f2) go=$(go version 2>/dev/null | awk '{print $3}') python=$(python3 --version 2>&1 | awk '{print $2}') cc=zig-glibc2.36" +echo "marqdo dev-env: rust=$(rustc --version 2>/dev/null | cut -d' ' -f2 || echo missing) go=$(go version 2>/dev/null | awk '{print $3}' || echo missing) python=$(python3 --version 2>&1 | awk '{print $2}' || echo missing)"