Files
marqdo/doc/dev-setup.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

4.1 KiB
Executable File
Raw Blame History

开发环境配置(Rust 参考解释器)

状态 M0
相关 dependencies.md · interpreter.md

1. 必备软件

软件 要求 检查
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(若尚未安装):

  • 官方:https://rustup.rs/
  • Windows:下载 rustup-init.exe,按提示安装后重新打开终端

本仓库可选 rust-toolchain.toml(钉 1.81.0)。若本机无 rustup、但已有匹配的 rustc/cargo,也可直接开发。

不需要: Flex、Bison、LLVM。Node/npm 只在开发 VS Code 扩展时需要;核心 Rust 开发不依赖它们。

本仓库提供了固定 Rust 版本:rust-toolchain.toml 使用 Rust 1.81.0,并启用 rustfmt / clippy。在受限开发容器中,推荐先加载仓库环境脚本:

source scripts/dev-env.sh

脚本会优先使用 target/toolchain/ 下的工具链,普通开发机则回退到 PATH 中已有的工具, 并把 Cargo、Go 缓存和临时目录放在工作区内。


2. 获取代码与构建

git clone https://github.com/cflmy/marqdo.git
cd marqdo

cargo build
cargo test
cargo run -- run tests/structure/hello.mq.md

构建 Go web 插件(完整扩展开发需要):

bash scripts/build-web-plugin.sh

当前 M0:run 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。

若 cargo build 报 edition2024 / 过新 crate:仓库已对 clap 等做兼容钉扎(见 Cargo.toml);请使用附带的 Cargo.lock,勿盲目 cargo update 到最新 major。


3. 推荐组件

rustup component add rustfmt clippy   # 若使用 rustup
cargo fmt
cargo clippy --all-targets

只验证 Rust 核心时可运行 cargo test --locked --lib;包含全部扩展的 gold 测试需要 Go, 并建议单线程运行以避免共享临时夹具互相影响:

cargo test --locked --test gold -- --test-threads=1

代理下拉 crate(可选,与 git 推送类似):

# Windows PowerShell 示例
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
cargo build

或配置 %USERPROFILE%\.cargo\config.toml:

[http]
proxy = "http://127.0.0.1:7890"

3.5 Git 推送(遇网络失败时使用代理)

直连 git push 偶尔会报 RPC failed; curl 35 Recv failure: Connection reset by peer 或 curl 56(远端挂断,常见于数据包稍大时)。此时通过本机代理 7890 推送:

# Linux/macOS(本机 clash 监听 127.0.0.1:7890)
git -c http.proxy=http://127.0.0.1:7890 -c http.postBuffer=524288000 push origin main

要点:

  • 代理可用性先探测:curl -x http://127.0.0.1:7890 -o /dev/null -w "%{http_code}\n" https://github.com,返回 200 再推。
  • http.postBuffer=524288000(500 MB)用于规避推送大包被断开(curl 56);两个 -c 可叠加。
  • 该命令一次性生效,不写死仓库配置。若想长期默认走代理,可执行:
    git config http.proxy http://127.0.0.1:7890
    git config http.postBuffer 524288000
    
  • 若是别的代理端口,把 7890 换成实际端口(如 Windows 示例里 $env:HTTPS_PROXY 的同款端口)。

4. 目录约定

路径 含义
src/lex 行分类 / 词法(自研)
src/parse 递归下降语法
src/diagnostics 诊断
tests/ 金样例 + 集成测试(structure / keywords / errors)
public/ 用户可执行文档(无 errors)
spike/ 旧 Python 风险探测,非运行时依赖
doc/ 设计与路线图

5. 下一里程碑

见 interpreter.md:M1 词法·行分类与最小 AST。