第2章环境搭建

第2章环境搭建：安装avatar2与QEMU，配置Python虚拟环境，验证第一个Hello World模拟

好，咱们直接进入正题。环境搭建这事儿，说难不难，说简单吧，我第一次搞的时候也踩了不少坑。尤其是avatar2和QEMU的版本匹配问题，折腾了我整整一个下午。今天我把这些经验都摊开来讲，你跟着走一遍，应该半小时内就能跑起来。

2.1 为什么需要虚拟环境？

你可能觉得奇怪，直接pip install不就行了？嗯，我以前也这么想。直到有一次，我在做另一个项目时需要用Python 3.6，而avatar2要求3.8以上，两个项目挤在一个环境里，那叫一个乱。

说白了，Python虚拟环境就是给你的每个项目一个独立的小房间。互不干扰，干净清爽。

我的习惯：每个嵌入式仿真项目都单独建一个虚拟环境。虽然多花几分钟，但后面省心太多了。

2.2 安装Python虚拟环境工具

我建议直接用Python自带的venv模块。从Python 3.3开始就内置了，不需要额外安装。

# 检查Python版本
python3 --version

# 如果版本低于3.8，建议先升级
# Ubuntu/Debian
sudo apt update
sudo apt install python3.8 python3.8-venv

# macOS (用Homebrew)
brew install python@3.8

注意：avatar2官方推荐Python 3.8或3.9。我曾经用Python 3.10试过，结果某些依赖包编译报错，折腾了两小时才换回3.8。

2.3 创建并激活虚拟环境

这一步很简单，但容易忘。我刚开始时经常忘记激活环境就直接pip install，结果装到了系统环境里。

# 创建虚拟环境（在项目目录下）
python3 -m venv avatar2_env

# 激活虚拟环境
# Linux/macOS
source avatar2_env/bin/activate

# Windows
avatar2_env\Scripts\activate

# 看到终端前面出现 (avatar2_env) 就说明成功了

激活后，你所有的pip操作都会局限在这个环境里。退出时输入deactivate就行。

2.4 安装avatar2

avatar2的安装其实就一条命令，但有个坑——它依赖的某些库需要系统级安装。

# 先安装系统依赖
# Ubuntu/Debian
sudo apt install libglib2.0-dev libpixman-1-dev

# macOS
brew install glib pixman

# 然后安装avatar2
pip install avatar2

我曾经踩过的坑：直接pip install avatar2，结果编译报错说找不到glib.h。后来才发现要先装系统库。嗯，这个顺序很重要。

2.5 安装QEMU

avatar2需要QEMU作为后端模拟器。这里有两种方式：

方式	命令	适用场景
系统包管理器	`sudo apt install qemu-system-arm`	快速体验，版本可能较旧
源码编译	从QEMU官网下载源码编译	需要最新特性或特定补丁

我个人建议先用系统包管理器安装。等后面遇到版本问题时再考虑源码编译。

# 安装QEMU（以ARM为例）
sudo apt install qemu-system-arm qemu-user

# 验证安装
qemu-system-arm --version

小提示：avatar2支持多种架构，包括ARM、MIPS、RISC-V等。我们课程主要用ARM，但方法对其他架构也通用。

2.6 验证安装：第一个Hello World

好，环境搭好了，我们来跑第一个例子。这个例子会模拟一个ARM Cortex-M3开发板，让LED灯闪烁。

# 创建一个测试脚本 test_avatar.py
from avatar2 import *

# 创建avatar实例
avatar = Avatar(arch=ARM_CORTEX_M3)

# 添加QEMU作为后端
qemu = avatar.add_target(QemuTarget,
                         name='stm32',
                         cpu='cortex-m3')

# 加载固件（这里用内置的测试固件）
qemu.load_binary('test_firmware.bin')

# 运行
qemu.run()

# 读取某个外设寄存器
reg_val = qemu.read_memory(0x40020000, 4, 1)
print(f"GPIO寄存器值: {hex(reg_val)}")

# 停止模拟
qemu.stop()
avatar.shutdown()

运行这个脚本：

python test_avatar.py

如果看到类似GPIO寄存器值: 0x0的输出，恭喜你，环境搭建成功了！

为什么是这个结果？因为刚上电时，GPIO寄存器默认值是0。后面我们会学到如何通过写寄存器来控制LED。

2.7 知识体系总览

下面这张图展示了我们整个环境搭建的核心逻辑：

2.8 常见问题与避坑指南

pip安装超时：国内用户建议换清华源 pip install avatar2 -i https://pypi.tuna.tsinghua.edu.cn/simple
QEMU版本不匹配：avatar2 0.7版本要求QEMU 5.0以上。用qemu-system-arm --version检查
虚拟环境激活失败：Windows用户注意，PowerShell可能需要先执行Set-ExecutionPolicy Unrestricted

重要提醒：每次打开新终端，都要记得先激活虚拟环境！我至少有过三次忘记激活，然后发现import avatar2失败，愣了半天才反应过来。

好了，环境搭建就到这里。你跟着走一遍，应该能顺利跑起来。如果遇到问题，先检查版本号，再检查虚拟环境是否激活——这两个问题占了90%的坑。

📚 课程目录