00 — 环境搭建指南

目标: 从零开始，在你的电脑上把 ScratchV 编译器跑起来。 预计时间: 15-30 分钟 前置要求: 会用终端（命令行），电脑能上网

目录

1. 你需要什么
2. 克隆代码
3. 创建虚拟环境
4. 安装 ScratchV
5. 验证安装
6. 安装可选依赖
7. 平台特定说明
8. 检查清单

---

1. 你需要什么

软件	版本要求	怎么检查
Python	3.10 或更高（推荐 3.12）	python3 --version
Git	任意版本	git --version
pip	通常随 Python 安装	pip --version

如果你还没有安装

Ubuntu / Debian / WSL:

sudo apt update
sudo apt install python3 python3-pip python3-venv python3-dev git build-essential

macOS:

# 先安装 Homebrew（如果还没有）: https://brew.sh
brew install python@3.12 git

Windows: - 推荐安装 WSL2（Windows Subsystem for Linux），然后在 WSL 里按 Ubuntu 的方式操作 - 或者从 python.org 下载 Python 安装包

💡 为什么推荐 WSL？ ScratchV 的 RISC-V 仿真工具（TinyFive、Spike）主要在 Linux 上测试过。WSL 让你在 Windows 上拥有一个完整的 Linux 环境，体验最好。

---

2. 克隆代码

打开终端，进入你放项目的目录：

# 进入你喜欢的目录（比如 ~/workspace）
mkdir -p ~/workspace
cd ~/workspace

# 克隆 ScratchV 仓库
git clone https://github.com/kinsomwang/ScratchV.git
cd ScratchV

预期输出（类似）：

Cloning into 'ScratchV'...
remote: Enumerating objects: 1234, done.
remote: Counting objects: 100% (1234/1234), done.
...

💡 网络慢怎么办？ 如果 GitHub 访问慢，可以在项目目录下配置代理： bash git config http.proxy http://127.0.0.1:7890 # 替换为你的代理地址

---

3. 创建虚拟环境

虚拟环境让你的 ScratchV 依赖和系统 Python 隔离开，避免版本冲突。

# 在 ScratchV 目录下创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate    # Linux / macOS / WSL

激活成功后，你的终端提示符前面会出现 (.venv)：

(.venv) kinsomwang@computer:~/workspace/ScratchV$

💡 怎么退出虚拟环境？ 输入 deactivate 即可。下次回来时重新执行 source .venv/bin/activate。

---

4. 安装 ScratchV

# 确保在 ScratchV 目录下，且虚拟环境已激活（提示符前有 (.venv)）
pip install -e .

实际输出：

Obtaining file:///home/kinsomwang/workspace/ScratchV
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  ...
Successfully installed scratchv-0.3.0

-e 参数是 "editable" 模式，意味着你修改源码后不需要重新安装，直接生效。

---

5. 验证安装

5.1 确认导入正常

python3 -c "import scratchv; print('scratchv version:', scratchv.__version__)"

预期输出：

scratchv version: 0.3.0

5.2 运行测试

# 运行全部测试（348 个用例，约 1-2 秒）
python3 -m pytest tests/ -v --tb=short

实际输出：

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.3, pluggy-1.6.0
rootdir: /home/kinsomwang/workspace/ScratchV
configfile: pyproject.toml
collected 348 items

tests/test_asm_beautifier.py::TestAsmBeautifier::... PASSED        [  1%]
tests/test_parser.py::TestDSLParser::test_parse_simple_add PASSED  [  5%]
tests/test_ir.py::TestIRBuilder::test_build_simple_add PASSED      [ 42%]
tests/test_backend.py::TestInstructionSelect::test_select_add PASSED [ 73%]
...
======================= 348 passed in 1.23s ========================

全部绿色 PASSED 就是环境 OK 了 🎉

5.3 快速试跑：编译一个 CNN 模型

python3 scratchv/standalone/onnx_to_riscv_standalone.py models/graph/cnn.onnx \
    -o /tmp/cnn_test.bin --estimate --report

实际输出（关键行）：

ScratchV: Library-free ONNX → RISC-V RV32IM Pipeline
  Input:  models/graph/cnn.onnx
  Graph: main_graph
  Nodes: 15
  Initializers: 12

[1/5] Parsing ONNX protobuf (manual wire-format parser)...
    [0] Conv: input1, layer1.0.weight → ...
    [1] Relu: ...
    [2] MaxPool: ...
    ... (共 15 个算子)

[2/5] Converting weights to Q16.16 fixed-point and planning memory...
  Weight data: 27,673,524 bytes (26.4 MB)

[3/5] Generating inline RISC-V RV32IM machine code...
  Code size: 3,548 bytes (887 instructions)

[4/5] Assembling flat binary...
  Total binary: 27,677,072 bytes (26.4 MB)

[5/5] Writing output files...
  Binary: /tmp/cnn_test.bin (27,677,072 bytes)
  Assembly: /tmp/cnn_test.s

Pipeline complete!
  Code:   3,548 bytes (887 instructions)
  Data:   27,673,524 bytes (26.4 MB)

[estimate] Analytical instruction count estimation...
  Estimated total instructions: 2,203,799,060
  Compute:  62.8%  Memory: 24.8%  Branch: 3.8%

[report] Generating CI benchmark reports...
  HTML: benchmark_reports/benchmark.html
  JSON: benchmark_reports/benchmark.json
  Summary: benchmark_reports/github_summary.md

---

6. 安装可选依赖

ScratchV 的核心编译器零外部依赖（只用 Python 标准库）。以下依赖是可选的，按需安装：

# 安装全部可选依赖
pip install -e ".[all]"

各依赖的用途：

依赖	用途	什么时候需要
tinyfive	RISC-V 仿真执行	想真正运行编译出的代码、看执行结果
llvmlite	生成 LLVM IR	想对比 ScratchV 和 LLVM 的编译效果
onnxruntime	标准 ONNX 推理	想验证 ScratchV 计算结果是否正确

---

7. 平台特定说明

国内用户加速 pip

# 临时使用清华镜像
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或者永久配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

---

8. 检查清单

完成以下所有项，你的环境就准备好了：

• [ ] Python 版本 ≥ 3.10（python3 --version 确认）
• [ ] 代码已克隆到本地（git status 正常）
• [ ] 虚拟环境已创建并激活（终端提示有 (.venv)）
• [ ] pip install -e . 成功
• [ ] python3 -c "import scratchv" 正常
• [ ] python3 -m pytest tests/ -v --tb=short 全部通过
• [ ] 能成功编译 CNN 模型（上一节的命令）

---

遇到问题？

跳到 04-故障排除FAQ 查找常见问题的解决方案。

如果还是解决不了，欢迎到 GitHub Issues 提问。

---

下一步: 环境搭好了，去看看 01-编译器概念入门，理解编译器到底在做什么。