实验环境配置

本节我们将完成环境配置并成功运行 rCore-Tutorial-v3 。整个流程分为下面几个部分：

• 系统环境配置

• C/Rust 开发环境配置

• QEMU 模拟器安装

• 其他工具安装

• 运行 rCore-Tutorial-v3

在线开发环境配置

Github Classroom方式进行在线OS 环境配置

注：这种方式目前主要用于 2022年开源操作系统训练营

注解

基于 github classroom 的在线开发方式

基于 github classroom，可方便建立开发用的 git repository，并可基于 github 的 codespace （在线版 ubuntu +vscode）在线开发使用。整个开发环境仅仅需要一个网络浏览器。

1. 在网络浏览器中用自己的 github id 登录 github.com

2. 接收 第一个实验练习 setup-env-run-os1 的github classroom在线邀请 ，根据提示一路选择OK即可。

3. 完成第二步后，你的第一个实验练习 setup-env-run-os1 的 github repository 会被自动建立好，点击此 github repository 的链接，就可看到你要完成的第一个实验了。

4. 在你的第一个实验练习的网页的中上部可以看到一个醒目的 code 绿色按钮，点击后，可以进一步看到 codespace 标签和醒目的 create codesapce on main 绿色按钮。请点击这个绿色按钮，就可以进入到在线的ubuntu +vscode环境中

5. 再按照下面的环境安装提示在 vscode 的 console 中安装配置开发环境：rustc，qemu 等工具。注：也可在 vscode 的 console 中执行 make codespaces_setenv 来自动安装配置开发环境（执行 sudo 需要root权限，仅需要执行一次）。

6. 重要： 在 vscode 的 console 中执行 make setupclassroom_testX （该命令仅执行一次，X的范围为 1-8）配置 github classroom 自动评分功能。

7. 然后就可以基于在线 vscode 进行开发、运行、提交等完整的实验过程了。

上述的3，4，5步不是必须的，你也可以仅仅基于 Github Classroom 生成 git repository，并进行本地开发。

本地操作系统开发环境配置

目前实验内容可支持在 Ubuntu操作系统 、 openEuler操作系统 、 龙蜥操作系统 等上面进行操作。对于 Windows10/11 和 macOS 上的用户，可以使用WSL2、VMware Workstation 或 VirtualBox 等相关软件，通过虚拟机方式安装 Ubuntu18.04 / 20.04、openEuler操作系统、龙蜥操作系统等，并在上面进行实验。

Windows的WSL2方式建立Linux环境

对于Windows10/11 的用户可以通过系统内置的 WSL2 虚拟机（请不要使用 WSL1）来安装 Ubuntu 18.04 / 20.04 。步骤如下：

• 升级 Windows 10/11 到最新版（Windows 10 版本 18917 或以后的内部版本）。注意，如果 不是 Windows 10/11 专业版，可能需要手动更新，在微软官网上下载。升级之后， 可以在 PowerShell 中输入 winver 命令来查看内部版本号。

• 「Windows 设置 > 更新和安全 > Windows 预览体验计划」处选择加入 “Dev 开发者模式”。

• 以管理员身份打开 PowerShell 终端并输入以下命令：

  # 启用 Windows 功能：“适用于 Linux 的 Windows 子系统”
  >> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  
  # 启用 Windows 功能：“已安装的系统虚拟机平台”
  >> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  
  # <Distro> 改为对应从微软应用商店安装的 Linux 版本名，比如：`wsl --set-version Ubuntu 2`
  # 如果你没有提前从微软应用商店安装任何 Linux 版本，请跳过此步骤
  >> wsl --set-version <Distro> 2
  
  # 设置默认为 WSL 2，如果 Windows 版本不够，这条命令会出错
  >> wsl --set-default-version 2
  

• 下载 Linux 内核安装包

• 在微软商店（Microsoft Store）中搜索并安装 Ubuntu18.04 / 20.04。

VMware虚拟机方式进行本地OS开发环境配置

如果你打算使用 VMware 安装虚拟机的话，我们已经配置好了一个能直接运行 rCore-Tutorial-v3 的 Ubuntu22.04 镜像，它是一个 vmdk 格式的虚拟磁盘文件，只需要在 VMware 中新建一台虚拟机，在设置虚拟磁盘的时候选择它即可。百度网盘链接 或者 清华云盘链接 （目前是旧版的 Ubuntu18.04+QEMU5.0的镜像）。已经创建好用户 oslab ，密码为一个空格。它已经安装了中文输入法和作为 Rust 集成开发环境的 Visual Studio Code，能够更容易完成实验并撰写实验报告。如果想要使用 VMWare 安装 openEuler 虚拟机的话，可以在 openEuler官网 下载 ISO 自行安装，接着需要参考网络上的一些教程配置网络和安装图形界面。

Docker方式进行本地OS开发环境配置

注解

Docker 开发环境

感谢 qobilidop，dinghao188 和张汉东老师帮忙配置好的 Docker 开发环境，进入 Docker 开发环境之后不需要任何软件工具链的安装和配置，可以直接将 tutorial 运行起来，目前应该仅支持将 tutorial 运行在 QEMU 模拟器上。

使用方法如下（以 Ubuntu18.04 为例）：

1. 通过 su 切换到管理员账户 root （注：如果此前并未设置 root 账户的密码需要先通过 sudo passwd 进行设置）, 在 rCore-Tutorial-v3 根目录下，执行 make build_docker ，来建立基于docker的开发环境 ；

2. 在 rCore-Tutorial-v3 根目录下，执行 make docker 进入到 Docker 环境；

3. 进入 Docker 之后，会发现当前处于根目录 / ，我们通过 cd mnt 将当前工作路径切换到 /mnt 目录；

4. 通过 ls 可以发现 /mnt 目录下的内容和 rCore-Tutorial-v3 目录下的内容完全相同，接下来就可以在这个环境下运行 tutorial 了。例如 cd os && make run 。

你也可以在 Windows10/11 或 macOS 原生系统或者其他 Linux 发行版上进行实验，基本上不会出现太大的问题。不过由于时间问题我们主要在 Ubuntu18.04 on x86-64上进行了测试，后面的配置也都是基于它的。如果遇到了问题的话，请在本节的讨论区中留言，我们会尽量帮助解决。

手动进行本地OS开发环境配置

基于RISC-V硬件环境的配置

目前已经出现了可以在RISC-V 64（简称RV64）的硬件模拟环境（比如QEMU with RV64）和真实物理环境（如全志哪吒D1开发板、SiFive U740开发板）的Linux系统环境。但Linux RV64相对于Linux x86-64而言，虽然挺新颖的，但还不够成熟，已经适配和预编译好的应用软件包相对少一些，适合hacker进行尝试。如果同学有兴趣，我们也给出多种相应的硬件模拟环境和真实物理环境的Linux for RV64发行版，以便于这类同学进行实验：

• Ubuntu for RV64的QEMU和SiFive U740开发板系统镜像

• OpenEuler for RV64的QEMU系统镜像

• Debian for RV64的D1哪吒开发板系统镜像

注：后续的配置主要基于Linux for x86-64系统环境，如果同学采用Linux for RV64环境，需要自己配置。不过在同学比较熟悉的情况下，配置方法类似且更加简单。可能存在的主要问题是，面向Linux for RV64的相关软件包可能不全，这样需要同学从源码直接编译出缺失的软件包。

C 开发环境配置

在实验或练习过程中，也会涉及部分基于C语言的开发，可以安装基本的本机开发环境和交叉开发环境。下面是以Ubuntu 20.04为例，需要安装的C 开发环境涉及的软件：

$ sudo apt-get update && sudo apt-get upgrade
$ sudo apt-get install git build-essential gdb-multiarch qemu-system-misc gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu

注：上述软件不是Rust开发环境所必须的。且ubuntu 20.04的QEMU软件版本低，而本书实验需要安装7.0以上版本的QEMU。

Rust 开发环境配置

首先安装 Rust 版本管理器 rustup 和 Rust 包管理器 cargo，这里我们用官方的安装脚本来安装：

curl https://sh.rustup.rs -sSf | sh

如果通过官方的脚本下载失败了，可以在浏览器的地址栏中输入 https://sh.rustup.rs 来下载脚本，在本地运行即可。

如果官方的脚本在运行时出现了网络速度较慢的问题，可选地可以通过修改 rustup 的镜像地址（修改为中国科学技术大学的镜像服务器）来加速：

export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
curl https://sh.rustup.rs -sSf | sh

或者使用tuna源来加速 参见 rustup 帮助：

export RUSTUP_DIST_SERVER=https://mirrors.tuna.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.edu.cn/rustup/rustup
curl https://sh.rustup.rs -sSf | sh

或者也可以通过在运行前设置命令行中的科学上网代理来实现：

# e.g. Shadowsocks 代理，请根据自身配置灵活调整下面的链接
export https_proxy=http://127.0.0.1:1080
export http_proxy=http://127.0.0.1:1080
export ftp_proxy=http://127.0.0.1:1080

安装完成后，我们可以重新打开一个终端来让之前设置的环境变量生效。我们也可以手动将环境变量设置应用到当前终端，只需要输入以下命令：

source $HOME/.cargo/env

接下来，我们可以确认一下我们正确安装了 Rust 工具链：

rustc --version

可以看到当前安装的工具链的版本。

rustc 1.62.0-nightly (1f7fb6413 2022-04-10)

警告

目前用于操作系统实验开发的 rustc 编译器的版本不局限在 1.46.0 这样的数字上，你可以选择更新版本的 rustc 编译器。但注意只能用 rustc 的 nightly 类型的版本。

可通过如下命令安装 rustc 的 nightly 版本，并把该版本设置为 rustc 的缺省版本。

rustup install nightly
rustup default nightly

我们最好把软件包管理器 cargo 所用的软件包镜像地址 crates.io 也换成中国科学技术大学的镜像服务器来加速三方库的下载。我们打开（如果没有就新建） ~/.cargo/config 文件，并把内容修改为：

[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"
replace-with = 'ustc'
[source.ustc]
registry = "git://mirrors.ustc.edu.cn/crates.io-index"

同样，也可以使用tuna源 参见 crates.io 帮助：

[source.crates-io]
replace-with = 'tuna'

[source.tuna]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"

接下来安装一些Rust相关的软件包

rustup target add riscv64gc-unknown-none-elf
cargo install cargo-binutils
rustup component add llvm-tools-preview
rustup component add rust-src

警告

如果你换了另外一个rustc编译器（必须是nightly版的），需要重新安装上述rustc所需软件包。rCore-Tutorial 仓库中的 Makefile 包含了这些工具的安装，如果你使用 make run 也可以不手动安装。

至于 Rust 开发环境，推荐 JetBrains Clion + Rust插件 或者 Visual Studio Code 搭配 rust-analyzer 和 RISC-V Support 插件。

注解

• JetBrains Clion是付费商业软件，但对于学生和教师，只要在 JetBrains 网站注册账号，可以享受一定期限（半年左右）的免费使用的福利。

• Visual Studio Code 是开源软件，不用付费就可使用。

• 当然，采用 VIM，Emacs 等传统的编辑器也是没有问题的。

QEMU 模拟器安装

我们需要使用 QEMU 7.0 版本进行实验，低版本的 QEMU 可能导致框架代码不能正常运行。而很多 Linux 发行版的软件包管理器默认软件源中的 QEMU 版本过低，因此我们需要从源码手动编译安装 QEMU 模拟器软件。下面以 Ubuntu 18.04/20.04 上的安装流程为例进行说明：

首先我们安装依赖包，获取 QEMU 源代码并手动编译：

# 安装编译所需的依赖包
sudo apt install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \
              gawk build-essential bison flex texinfo gperf libtool patchutils bc \
              zlib1g-dev libexpat-dev pkg-config  libglib2.0-dev libpixman-1-dev libsdl2-dev libslirp-dev \
              git tmux python3 python3-pip ninja-build
# 下载源码包
# 如果下载速度过慢可以使用我们提供的百度网盘链接：https://pan.baidu.com/s/1dykndFzY73nqkPL2QXs32Q
# 提取码：jimc
wget https://download.qemu.org/qemu-7.0.0.tar.xz
# 解压
tar xvJf qemu-7.0.0.tar.xz
# 编译安装并配置 RISC-V 支持
cd qemu-7.0.0
./configure --target-list=riscv64-softmmu,riscv64-linux-user  # 在第九章的实验中，可以有图形界面和网络。如果要支持图形界面，可添加 " --enable-sdl" 参数；如果要支持网络，可添加 " --enable-slirp" 参数
make -j$(nproc)

注解

注意，上面的依赖包可能并不完全，比如在 Ubuntu 18.04 上：

• 出现 ERROR: pkg-config binary 'pkg-config' not found 时，可以安装 pkg-config 包；

• 出现 ERROR: glib-2.48 gthread-2.0 is required to compile QEMU 时，可以安装 libglib2.0-dev 包；

• 出现 ERROR: pixman >= 0.21.8 not present 时，可以安装 libpixman-1-dev 包。

另外一些 Linux 发行版编译 QEMU 的依赖包可以从 这里 找到。

之后我们可以在同目录下 sudo make install 将 QEMU 安装到 /usr/local/bin 目录下，但这样经常会引起冲突。个人来说更习惯的做法是，编辑 ~/.bashrc 文件（如果使用的是默认的 bash 终端），在文件的末尾加入几行：

# 请注意，qemu-7.0.0 的父目录可以随着你的实际安装位置灵活调整
export PATH=$PATH:/path/to/qemu-7.0.0/build

随后即可在当前终端 source ~/.bashrc 更新系统路径，或者直接重启一个新的终端。

此时我们可以确认 QEMU 的版本：

qemu-system-riscv64 --version
qemu-riscv64 --version

在其他缺少预编译 QEMU with RV64 软件包的Linux x86-64 环境（如openEuler操作系统）上，首先需要从 openEuler 社区维护的 QEMU 的 riscv分支 下载 QEMU 源码，并直接通过 rpmbuild 进行构建。

警告

请尽量不要安装 qemu-kvm ，这可能会导致我们的框架无法正常运行。如果已经安装，可以考虑换用 Docker 。

另外，我们仅在 Qemu 7.0.0 版本上进行了测试，请尽量不要切换到其他版本。

K210 真机串口通信

为了能在 K210 真机上运行 Tutorial，我们还需要安装基于 Python 的串口通信库和简易的串口终端。

pip3 install pyserial
sudo apt install python3-serial

GDB 调试支持

目前我们仅支持基于 QEMU 模拟器进行调试。在 os 目录下 make debug 可以调试我们的内核，这需要安装终端复用工具 tmux ，还需要支持 riscv64 指令集的 gdb 调试器 riscv64-unknown-elf-gdb 。该调试器包含在 riscv64 gcc 工具链中，工具链的预编译版本可以在如下链接处下载：

• Ubuntu 环境

• macOS 环境

• Windows 环境

• CentOS 环境

最新版的工具链可以在 sifive 官方的 repo 中 找到。

解压后在 bin 目录下即可找到 riscv64-unknown-elf-gdb 以及另外一些常用工具 objcopy/objdump/readelf 等。

在其他缺少预编译 riscv64 gcc 工具链的 Linux x86-64 环境（如 openEuler 操作系统、龙蜥操作系统等）上，则需要 clone riscv 工具链仓库 并参考其说明手动构建。

出于某些原因，我们全程使用 release 模式进行构建。为了正常进行调试，请确认各项目（如 os , user 和 easy-fs ）的 Cargo.toml 中包含如下配置：

[profile.release]
debug = true

此外，参考 os/Makefile ，还可以先打开一个终端页面 make gdbserver 启动 QEMU ，此后另开一个终端页面在同目录下 make gdbclient 将 GDB 客户端连接到 QEMU 进行调试。我们推荐使用 gdb-dashboard 插件，可以大大提升调试体验。在本节的评论区已有同学提供了基于各种 IDE 的调试方法，也可参考。

运行 rCore-Tutorial-v3

在 QEMU 模拟器上运行

如果是在 QEMU 模拟器上运行，只需在 os 目录下 make run 即可。在内核加载完毕之后，可以看到目前可以用的 应用程序。 usertests 打包了其中的很大一部分，所以我们可以运行它，只需输入在终端中输入它的名字即可。

之后，可以先按下 Ctrl+a （即：先按下 Ctrl 不松开，再按下小写字母 a 不放，随后同时将两个键松开） ，再按下 x 来退出 QEMU。

在 K210 平台上运行

如果是在 K210 平台上运行则略显复杂。

首先，我们需要将 MicroSD 插入 PC 来将文件系统镜像拷贝上去。

警告

在 os/Makefile 中我们默认设置 MicroSD 在当前操作系统中可以用设备 SDCARD=/dev/sdb 访问。你可以使用 df -hT 命令来确认在你的环境中 MicroSD 是哪个设备，并在 make sdcard 之前对 os/Makefile 的 SDCARD 配置做出适当的修改。不然，这有可能导致 设备 /dev/sdb 上数据丢失 ！

随后，我们将 MicroSD 插入 K210 开发板，将 K210 开发板连接到 PC ，然后进入 os 目录 make run BOARD=k210 在 K210 开发板上跑 rCore Tutorial 。

之后，可以按下 Ctrl+] 来退出串口终端。

由于教程的 ch1~ch5 分支还没有文件系统，在 K210 上运行这些分支无需 MicroSD 卡也不需要进行文件系统镜像烧写工作，直接切换到 os 目录下 make run BOARD=k210 即可。

到这里，恭喜你完成了实验环境的配置，可以开始阅读教程的正文部分了！

Q & A

当代码跑不起来的时候，可以尝试：

• 分支是否与 rCore-Tutorial-v3 原版仓库（而非 fork 出来的仓库）的对应分支同步。如不同步的话考虑通过 git pull 进行更新。注：这是因为 Rust 的版本更迭较快，如不及时更新的话曾经能正常运行的代码也会无法运行。

• 项目根目录下的 rust-toolchain 非常重要，它代表整个项目采用的 Rust 工具链版本。请务必保持其与原版仓库对应分支一致。

• 项目根目录下是否存在放置 RustSBI 的 bootloader/ 目录。如不存在的话可从原版仓库的各分支上获取。

• 通过 make clean 或者 cargo clean 删除 os 或 user 目录下的构建产物，并重新 make run 。注：出现这样的问题通常说明框架的构建脚本存在 bug，可以提 issue。

如果怀疑遇到了网络问题，可以检查：

• 请按照本节说明进行 Rust 安装和 crates.io 镜像配置。通常情况下能够解决 Rust 工具链更新和下载已发布到 crates.io 上库的问题。

• 如果发现在试图从 github 上下载下述几个库的时候卡死，可以修改 os 和 user 目录下的 Cargo.toml 替换为 gitee 上的镜像。例如，将：

  riscv = { git = "https://github.com/rcore-os/riscv", features = ["inline-asm"] }
  virtio-drivers = { git = "https://github.com/rcore-os/virtio-drivers" }
  k210-pac = { git = "https://github.com/wyfcyx/k210-pac" }
  k210-hal = { git = "https://github.com/wyfcyx/k210-hal" }
  k210-soc = { git = "https://github.com/wyfcyx/k210-soc" }
  

  替换为：

  riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] }
  virtio-drivers = { git = "https://gitee.com/rcore-os/virtio-drivers" }
  k210-pac = { git = "https://gitee.com/wyfcyx/k210-pac" }
  k210-hal = { git = "https://gitee.com/wyfcyx/k210-hal" }
  k210-soc = { git = "https://gitee.com/wyfcyx/k210-soc" }