00 — 环境搭建指南

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

本指南面向 Linux/Bash，推荐 Ubuntu 24.04。Qwen3 部署和 W1 及后续阶段的独立复现须使用 Linux 固定环境指南，不要用本页的通用可选依赖替代该项目固定版本。个人开发环境不作为 Linux 验收依据。

目录

你需要什么

克隆代码

创建虚拟环境

安装 ScratchV

验证安装

安装可选依赖

平台特定说明

检查清单

1. 你需要什么

软件版本要求怎么检查

Python 3.10 或更高（推荐 3.12） `python3 --version`

Git 任意版本 `git --version`

pip 通常随 Python 安装 `pip --version`

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

如果你还没有安装

Ubuntu / Debian:

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

在 Linux 主机上安装和验证编译器及仿真工具。复现记录须保存发行版、CPU、 Python 和工具版本；其他个人环境的运行结果不能直接记作 Linux 通过。

2. 克隆代码

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

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

# 克隆 ScratchV 仓库
git clone https://github.com/ScratchV-Compiler/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

激活成功后，你的终端提示符前面会出现 (.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 模型（上一节的命令）

00 — 环境搭建指南

目录

你需要什么

克隆代码

创建虚拟环境

安装 ScratchV

验证安装

安装可选依赖

平台特定说明

检查清单

1. 你需要什么

软件版本要求怎么检查

Python 3.10 或更高（推荐 3.12） `python3 --version`

Git 任意版本 `git --version`

pip 通常随 Python 安装 `pip --version`

5. 验证安装

5.1 确认导入正常
`python3 -c "import scratchv; print('scratchv version:', scratchv.version)"`

预期输出：

`scratchv version: 0.3.0`

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`

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

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

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

00 — 环境搭建指南

目录 你需要什么 克隆代码 创建虚拟环境 安装 ScratchV 验证安装 安装可选依赖 平台特定说明 检查清单

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

5. 验证安装

5.1 确认导入正常 python3 -c "import scratchv; print('scratchv version:', scratchv.__version__)" 预期输出： scratchv version: 0.3.0

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

遇到问题？ 跳到 04-故障排除FAQ 查找常见问题的解决方案。 如果还是解决不了，欢迎到 GitHub Issues 提问。 下一步: 环境搭好了，去看看 01-编译器概念入门，理解编译器到底在做什么。

目录

你需要什么

克隆代码

创建虚拟环境

安装 ScratchV

验证安装

安装可选依赖

平台特定说明

检查清单

1. 你需要什么

软件版本要求怎么检查

Python 3.10 或更高（推荐 3.12） `python3 --version`

Git 任意版本 `git --version`

pip 通常随 Python 安装 `pip --version`

5.1 确认导入正常
`python3 -c "import scratchv; print('scratchv version:', scratchv.version)"`

预期输出：

`scratchv version: 0.3.0`

国内用户加速 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`

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

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

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