实验0：macOS 使用说明¶

本节目标

面向使用 macOS 的同学，说明在本课程中应如何选择实验环境。对 macOS 用户来说，首选仍然是 VLAB；本页同时补充一条本地备选路线，满足“能编译 kernel、能运行 RISC-V qemu”这一最低要求。

先说结论

对 macOS 用户，课程环境的首选方案仍然是 VLAB 教程，因为它最稳定，也最不容易被本地芯片架构、虚拟化软件和图形界面兼容性问题卡住。

如果你当前的目标只是完成 Lab0，并且你很关心“本地能不能直接编译并运行课程内核”，那么可以把本页后半部分当作一条本地备选路线：不先装 Linux 虚拟机，直接在 macOS 上用 Homebrew 安装课程需要的工具。

1 三条可选路线¶

对 macOS 用户来说，比较实际的三条路线是：

VLAB（首选）：直接使用课程提供的云端 Linux 环境，最稳定、最省心。
最小本地方案（备选）：不装 Linux，直接在 macOS 上安装 qemu、RISC-V 交叉编译器、python3 和 GNU make。
本地 Linux 虚拟机方案（次选）：如果你坚持想要一个完整的 Ubuntu 环境，再自行选择合适的虚拟化软件。

推荐顺序

建议优先阅读并使用 VLAB 教程。如果你明确想在本机先跑通 Lab0 的基础构建流程，再尝试第 2 条最小本地方案；只有当你明确需要一个完整 Ubuntu 用户态环境时，再考虑第 3 条本地 Linux 虚拟机方案。

2 最小本地方案：直接在 macOS 上安装实验所需工具¶

2.1 这条路线适合什么¶

这条路线主要适合下面这种需求：

你希望尽快把 Lab0 跑通；
你只需要能执行 make、make fsimg、make qemu 这类基础构建命令；
你当前最关心的是“能不能编译和运行课程内核”，而不是先得到一个完整 Linux 桌面环境。

这是按当前课程文档推断出来的最小集合

从 Lab0 目前的构建流程来看，本地最小需求主要是：qemu-system-riscv64、RISC-V 交叉编译器、python3 和 GNU make。因此，在 macOS 上优先尝试 Homebrew 方案是合理的。

2.2 先准备基础工具¶

如果你还没有安装 Xcode Command Line Tools，可先执行：

xcode-select --install

然后确认 Homebrew 可用，并更新本地包索引：

brew update
brew upgrade

2.3 用 Homebrew 安装最小工具集合¶

推荐安装：

brew install qemu riscv64-elf-gcc python make

安装完成后，检查关键命令是否可用：

$ qemu-system-riscv64 --version | head -n 1
QEMU emulator version ...
$ riscv64-elf-gcc --version | head -n 1
riscv64-elf-gcc (...) ...
$ python3 --version
Python 3.x.x
$ gmake --version | head -n 1
GNU Make 4.x

为什么这里是 gmake

Homebrew 的 GNU make 默认安装为 gmake。如果你想继续直接输入 make，可以把 Homebrew 的 gnubin 目录加入 PATH。

例如，在 ~/.zshrc 中加入：

export PATH="$(brew --prefix)/opt/make/libexec/gnubin:$PATH"

然后重新加载配置：

source ~/.zshrc

2.4 处理 RISC-V 工具链前缀差异¶

macOS 上一个常见问题是：Homebrew 提供的交叉编译器名字是 riscv64-elf-gcc，但很多教学工程或现成 Makefile 更常见的写法是 riscv64-unknown-elf-gcc。

如果你发现课程仓库在 macOS 上找不到 riscv64-unknown-elf-* 这一组命令，可以先创建一组兼容链接：

mkdir -p ~/.local/bin
for tool in gcc g++ cpp ld ar as nm objcopy objdump ranlib strip; do
    ln -sf "$(brew --prefix)/bin/riscv64-elf-$tool" "$HOME/.local/bin/riscv64-unknown-elf-$tool"
done

然后把 ~/.local/bin 加到 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

如果某个链接创建失败

这通常说明对应工具在你的 Homebrew 环境里命名略有不同。此时先执行 ls "$(brew --prefix)/bin" | grep riscv64-elf 看看实际安装了哪些命令，再有针对性地调整即可。

2.5 在课程仓库中尝试最小构建¶

如果上面的命令都可用，就可以进入课程仓库尝试：

make
make fsimg
make qemu

如果你的 macOS 上 make 仍然不是 GNU make，那就直接改用：

gmake
gmake fsimg
gmake qemu

2.6 这条路线的边界¶

这条路线的目标是“尽快在 macOS 本地完成基础构建与运行”。它的优点是快，但也有边界：

它并不是一个真正的 Linux 环境；
某些后续实验脚本、依赖或调试工具，可能仍然更适合在 Ubuntu 环境中运行；
一旦你在本地遇到过多平台兼容性问题，就不应该继续在平台细节上消耗过多时间。

一个务实建议

如果你只想先把 Lab0 跑通，可以先尝试这条 Homebrew 最小方案；如果花了较长时间仍然卡在兼容性问题上，请优先切回 VLAB 教程，不要继续在本地环境上投入过多时间。

3 如果你坚持在 macOS 本地安装 Linux¶

这不是本页推荐的主路线，但如果你确实想要一个完整的 Ubuntu 环境，可以遵循下面两个原则：

先确认你清楚自己的机器是 Intel Mac 还是 Apple Silicon Mac；
一旦发现本地虚拟化软件、镜像架构、图形界面或网络配置出现大量兼容性问题，请及时止损，不要让这些问题阻塞后续实验进度。

为什么这里不展开成统一教程

macOS 下的本地虚拟化方案会明显受到芯片架构、软件版本和图形界面差异影响，很难像 Windows 的 WSL 那样给出一套对所有人都稳定适用的步骤。因此，本页只保留原则性说明，不再维护一套“所有 Mac 都照抄即可”的本地 Linux 安装教程。

4 常见问题¶

4.1 `make` 找到的不是 GNU Make¶

表现通常是语法不兼容，或者执行课程仓库中的 Makefile 时报出奇怪错误。优先检查：

$ make --version | head -n 1

如果这里显示的不是 GNU Make，就改用 gmake，或按上文把 gnubin 放进 PATH。

4.2 找不到 `riscv64-unknown-elf-gcc`¶

这通常不是你没装工具链，而是因为 Homebrew 提供的是 riscv64-elf-gcc。请按上文第 2.4 节创建兼容链接，或自行调整 PATH / Makefile。

4.3 `qemu-system-riscv64` 已安装但命令仍然找不到¶

先检查：

$ which qemu-system-riscv64

如果没有输出，说明当前 shell 没有正确拿到 Homebrew 的路径。先执行：

brew --prefix

并确认对应的 bin 目录已经在你的 PATH 中。

5 下一步¶

完成本页后，建议继续阅读：

如需继续完成课程仓库配置，可查看实验0：希冀平台与课程仓库接入。