企业官网建设流程全解析

rust-glancer 是一个主打低内存占用的轻量级 Rust LSP（Language Server Protocol）实现。本教程带你从零开始：用just与cargo-nextest完成 rust-glancer 开发环境搭建，构建整个代码库，并运行全量测试，帮助你快速进入开发状态。

一、开发环境一键准备：先装好这 4 样东西

rust-glancer 是一个 Cargo workspace，包含 30 多个 crate（解析器、类型推断、LSP 服务等）。官方开发指南（见 docs/src/development/DEVELOPMENT.md）明确列出：开发只需要just和cargo-nextest两个额外工具。

几个关键配置说明：

• 工具链：仓库通过 rust-toolchain.toml 锁定stable通道，并自动要求clippy和rustfmt组件，用 rustup 打开项目会按需自动补全。
• rust-src是强制性依赖，缺失会导致索引行为不正确，安装后务必执行上面那条命令确认。
• 格式化工具链单独固定为 nightly（rustfmt_toolchain := "nightly-2026-05-28"，见 Justfile），rustup 会在运行just fmt时自动下载，无需手动处理。

二、获取代码：clone 仓库并验证环境

git clone https://gitcode.com/gh_mirrors/ru/rust-glancer cd rust-glancer

clone 下来后，先花一分钟确认工具就位：

just --version cargo nextest --version rustup component list | grep rust-src

三条命令都有输出，即可开始构建。

三、构建代码库：一条命令编译全部 crate

rust-glancer 的主入口是 crates/rust-glancer/ 下的可执行文件，它提供analyze（离线分析）、lsp（启动语言服务器）等子命令（见 main.rs）。

Release 模式构建整个 workspace 只需一条命令：

just build

它等价于cargo build --workspace --release（见 Justfile）。首次构建会下载并编译全部依赖，耗时较长属正常现象；之后增量构建会快很多。

只想做快速语法/类型检查而不产出二进制，可以直接用：

cargo check --workspace

四、运行测试：cargo-nextest 的正确打开方式

为什么用 nextest 而不是 cargo test？

rust-glancer 有上千个测试用例，nextest 通过每个测试独立进程 + 并行调度，显著快于cargo test，并且是官方推荐的运行方式。

仓库还内置了 nextest 配置 .config/nextest.toml，其中fail-fast = false表示不会一遇到失败就停，而是跑完所有测试再汇总报告，方便你一次看到全部问题。

全量测试：just test

just test

即执行cargo nextest run --workspace（见 Justfile），覆盖 engine、lsp、lib 等全部 crate 的测试。

只跑某个 crate 的测试

不想跑全量时，直接对指定 crate 执行即可：

# 只跑类型推断引擎 cargo nextest run -p rg_ty # 只跑分析 crate 中名字包含 inference 的测试 cargo nextest run -p rg_analysis inference

crate 名可在 Cargo.toml 的workspace.dependencies中看到，例如rg_parse、rg_def_map、rg_semantic_ir。

手动/集成测试素材

仓库的 test_targets/ 目录存放了一组"真实但虚构"的 crate 与 workspace（simple/moderate/complex 三档规模），用于手动调试和集成测试，见 test_targets/README.md。可以用just check-test-targets批量校验它们。

五、just 命令速查表：日常开发全靠它

Justfile 是项目的统一命令入口，VS Code 扩展相关命令可通过子模块调用（如just client build）。常用命令如下：

小提示：如果你准备提交 PR，先跑一遍just pr-ready，基本等同于 CI 的完整检查。

六、项目结构速览：测试时知道去哪找代码

crates/ ├── engine/ # 核心分析引擎 │ ├── parse/ 词法与语法解析（rg_parse） │ ├── item-tree/ item tree 降级（rg_item_tree） │ ├── def-map/ 模块定义与路径解析（rg_def_map） │ ├── semantic-ir/ 语义 IR 与 trait 查找（rg_semantic_ir） │ ├── ty/ 类型推断与求解（rg_ty） │ ├── body-ir/ 函数体 IR（rg_body_ir） │ ├── analysis/ 面向 LSP 的查询实现（rg_analysis） │ └── project/ 索引与缓存（rg_project） ├── lsp/ │ ├── server/ LSP 服务器端 │ ├── proto/ 协议层 │ └── engine/ 引擎进程 ├── lib/ # 基础库（rg_std、rg_profile、test-fixture 等） ├── rust-glancer/ # 主二进制（analyze / lsp / codegen） └── tools/codegen/ # 代码生成工具

整体架构文档见 docs/src/architecture/ARCHITECTURE.md，测试哲学（偏好 snapshot 测试、使用expect-test）见 DEVELOPMENT.md。

七、常见问题排查清单

• 索引或构建报标准库相关错误：大概率是缺rust-src，执行rustup component add rust-src。
• 首次just build很慢：依赖庞大（含 rayon、tokio、rustc 系列 crate），属正常现象，耐心等待或先cargo check --workspace预热。
• just fmt触发工具链下载：它固定使用nightly-2026-05-28，首次运行会自动下载，无需干预。
• clippy/dylint 报环境相关错误：dylint 需要在完整环境下运行（沙箱内可能读不到构建元数据），换个普通终端重试。
• 测试失败定位：nextest 跑完会汇总所有失败项，把失败测试名传给cargo nextest run -p <crate> <名字>即可单独复现。

写在最后

至此，你已掌握了 rust-glancer 开发的完整闭环：安装工具 →just build构建 →just test运行测试 →just pr-ready提交前体检。

如果想继续深入，建议按这个顺序读：docs/src/architecture/ARCHITECTURE.md（架构）→ docs/src/development/PROFILING.md（剖析与内存测量）→ docs/src/intro/CONTRIBUTING.md（贡献规范，建议先开 issue 认领任务再动手）。祝你在 rust-glancer 的世界里玩得愉快！🚀