Lab 0: 环境搭建与实验准备 (#2)

Co-authored-by: cyc <[email protected]>
Co-authored-by: cychester <[email protected]>

.github/workflows/deploy.yml

@@ -15,5 +15,5 @@ jobs:
         with:
           python-version: 3.x
 
-      - run: pip --trusted-host pypi.org --trusted-host files.pythonhosted.org install mkdocs-material
+      - run: pip install mkdocs-material
       - run: mkdocs gh-deploy --force

.gitignore

@@ -3,6 +3,7 @@
 # will have compiled files and executables
 **/debug/
 **/target/
+**/Cargo.lock
 
 # These are backup files generated by rustfmt
 **/*.rs.bk

docs/general/coding_convention.md

@@ -0,0 +1,67 @@
+# 代码规范
+
+本页面列举了一些常见的代码规范要求。
+
+部分要求并不强制，但是建议尽量遵守和学习。
+
+## Git 相关
+
+=== "提交历史"
+
+    - 每个提交都应该有一定的意义，例如实现了新功能，修复了一个问题，定义了新的函数；
+    - 比较复杂的程序，要边开发边提交，而不是写完了再一次性提交；
+    - 不强求线性历史，**但是不允许使用 force push**。
+
+=== "提交消息"
+
+    - 简单明了地描述这个提交的内容；
+    - 建议用英文写，用中文写也可以；
+    - 不要编写的过于详细或过于简略；
+    - 可以采用一些格式，例如 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#examples)；
+    - 不掺杂个人情绪；
+    - 用户名和邮箱应该配置成自己的真实姓名和邮箱；
+    - 可以添加一些 Emoji，[gitmoji](https://gitmoji.dev/) 为提交说明中使用的 Emoji 提出了一些建议，可以参考。
+
+## 代码风格
+
+=== "简洁"
+
+    保证代码的简洁：
+
+    - 有整齐的缩进，建议用空格缩进而非 tab，两个空格或者四个空格作为一级缩进都可以；
+    - 每一行不要有太多字符，例如不超过 80 / 100 个字符；
+
+=== "注释"
+
+    在代码中编写适当的注释：
+
+    - 在比较复杂的代码块前，描述代码的功能；
+    - 过于简单的代码，一般不写注释；
+    - 函数一般要编写注释，包括其功能，参数和输出；
+    - 建议用英文，中文也可以，但是注意要用 UTF-8 编码。
+    - 遵循 [Rustdoc 的约定](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html)
+
+=== "空白"
+
+    代码中应该有适当的空格和空行：
+
+    - 函数中，实现不同功能的代码间需要添加空行；
+    - 操作符前后应该有空格，例如 c = a + b；
+    - 保持前后一致的风格。
+
+=== "命名"
+
+    变量的命名，应该符合一定的规范：
+
+    - 符合 Rust 编译器建议的变量命名规范；
+    - 尽量用英文单词，而不是中文拼音首字母；
+    - 命名与上下文要相关；
+    - 不用类似 `a, b, c, d` 的命名方式。
+
+
+我们建议使用工具来辅助代码风格的检查：
+
+- 使用 `rustfmt`，`cargo fmt --all` 命令来格式化代码；
+- 使用 `clippy`，`cargo clippy` 来检查代码风格。
+
+!!! note "请注意，由于项目 target 不尽相同，`clippy` 需要在每一个 `package` 下使用。"

docs/index.md

@@ -1,12 +1,16 @@
 # 中山大学 YatSenOS v2 操作系统实验教程
 
-A Rust x86_64 OS lab tutorial.
+## 实验说明
+
+本文档提供了一套基于 Rust、面向 UEFI 和 x86_64 的操作系统课程实验方案。
+
+我们期望基于低汇编、避免重复造轮子的宗旨，利用 Rust 语言优秀的包管理和底层支持，借助现有的优秀工程化底层封装，为学生提供一个低负担、现代、面向高级语言的操作系统实验指南。
 
 ## 实验大纲
 
 每一次实验区间为两周。
 
-- [实验零：环境搭建与实验准备](./labs/0x00-env.md)
+- [实验零：环境搭建与实验准备](./labs/0x00/index.md)
 
     1. Rust 学习和巩固，了解标准库提供的基本数据结构和功能。
     2. QEMU 与 Rust 环境搭建，尝试使用 QEMU 启动 UEFI Shell。

docs/labs/0x00/index.md

@@ -0,0 +1,45 @@
+# 实验零：环境搭建与实验准备
+
+!!! tip "代码是一场无声的交流，有些人是优秀的诗人，能够将抽象的想法转化为优雅的语言，而有些人则是忠实的翻译者，将逻辑转换成计算机可理解的语言。"
+
+## 实验目的
+
+1. Rust 学习和巩固，了解标准库提供的基本数据结构和功能。
+2. QEMU 与 Rust 环境搭建，尝试使用 QEMU 启动 UEFI Shell。
+3. 了解 x86 汇编、计算机的启动过程，UEFI 的启动过程，实现 UEFI 下的 `Hello, world!`。
+
+## 实验环境
+
+我们支持并推荐如下平台进行实验：
+
+- Ubuntu 22.04 LTS
+- Ubuntu 22.04 LTS with WSL 2
+- macOS with Apple Silicon（请自行安装相关依赖）
+- 其他可行的平台，但我们不提供技术支持
+
+需要安装的基本软件环境，括号中提供在 Ubuntu 中对应的包名：
+
+- QEMU x86_64 (qemu-system-x86)
+- Rust nightly toolchain (rustup)
+- make, gcc, gdb 等基本编译工具 (build-essential)
+
+## 实验基础知识
+
+!!! note "善用 LLM 进行学习"
+
+    对于现代计算机专业的学生，我们建议并要求大家学习借助 LLM（Large Language Model）进行学习，这是一种非常有效的学习方法，可以帮助你更快的学习到知识。
+
+    对于不理解的知识点和概念，我们建议优先参考文档、借助 LLM 进行实践，在仍然无法解决的情况下再向他人提问。
+
+对于本次实验内容，你需要参考学习如下实验资料：
+
+- [Linux 使用指导](../../wiki/linux.md)
+- [Rust 语言学习](../../wiki/rust.md)
+- [UEFI 启动过程](../../wiki/uefi.md)
+- [QEMU 使用参考](../../wiki/qemu.md)
+
+## 实验任务与要求
+
+1. 请各位同学独立完成作业，任何抄袭行为都将使本次作业判为 0 分。
+2. 请参考 [代码规范](../../general/coding_convention.md) 进行实验代码编写。
+3. 依据 [实验任务](./tasks.md) 完成实验。