bustub 前情提要(编译测试)

此处完成的是 CMU15-445 Fall2022 的 bustub 项目。

创建 Private Repo

在 github “create a new repository” 页面中直接创建一个private仓库，如 bustub-private。

# 1. 在本地创建一个原仓库的 bare clone，取名 bustub-public
$ git clone --bare https://github.com/cmu-db/bustub.git bustub-public

# 2. 将原public仓库 mirror 到我们自己的private方库，这样就将public仓库的所有东西都推到private仓库
$ cd bustub-public
# If you pull / push over HTTPS
$ git push https://github.com/student/bustub-private.git master
# If you pull / push over SSH
$ git push git@github.com:student/bustub-private.git master

# 3. 删除本地对public仓库的clone
$ cd ..
$ rm -rf bustub-public

# 4. 将自己private仓库clone到本地机器
# If you pull / push over HTTPS
$ git clone https://github.com/student/bustub-private.git
# If you pull / push over SSH
$ git clone git@github.com:student/bustub-private.git

# 5. 添加public库作为第二个remote，便于及时获取公共库后续的更改
$ git remote add public https://github.com/cmu-db/bustub.git

# 可以查看现有的远程库信息，来确认已经添加好了remote
$ git remote -v
origin	https://github.com/student/bustub-private.git (fetch)
origin	https://github.com/student/bustub-private.git (push)
public	https://github.com/cmu-db/bustub.git (fetch)
public	https://github.com/cmu-db/bustub.git (push)

# 后续拉取公共库的最新更改：
$ git fetch public
$ git merge public/master

Build

Linux / Mac (Recommended)

为确保您的计算机上有正确的软件包，运行以下脚本自动安装它们：

# Linux
$ sudo build_support/packages.sh
# macOS
$ build_support/packages.sh

运行以下命令来 build 系统：

$ mkdir build
$ cd build
$ cmake ..
$ make

如果希望在调试模式下编译系统👇。建议始终在调试模式下配置 CMake，这将使您能够输出调试消息并检查是否存在内存泄漏。

$ cmake -DCMAKE_BUILD_TYPE=Debug ..

为了加快构建过程，可以通过传递 -j 标志来使用多个线程。例如，下面的命令将使用四个线程构建系统:

$ make -j$(nproc)

默认情况下，这将启用 AddressSanitizer，若想启用其他的：

$ cmake -DCMAKE_BUILD_TYPE=Debug -DBUSTUB_SANITIZER=thread ..
$ make -j$(nproc)

Testing

可以使用我们的测试框架来测试此任务的各个组件。我们对单元测试用例使用 GTest。

运行 make check-tests 能运行所有的测试用例。注意，有些测试是 disabled，因为您还没有实现以后的项目。可以通过在测试名称中添加 DISABLED_ 前缀来禁用 GTest 中的测试。

$ cd build
$ make check-tests

这些测试只是我们将用来评估和评分项目的所有测试的一个子集。您应该自己编写额外的测试用例来检查实现的完整功能。

Formatting

您的代码必须遵循 Google C++ Style Guide。我们使用 Clang 自动检查源代码的质量。如果您的提交没有通过任何这些检查，您的项目成绩将为零。

执行以下命令检查语法。 format将自动更正代码。 check-lint 和 check-clang-tidy 将打印错误，您必须手动修复，以符合我们的样式指南。

$ make format
$ make check-lint
$ make check-clang-tidy-p0

内存泄露

此项目中，我们使用 LLVM Address Sanitizer (ASAN) and Leak Sanitizer (LSAN) 来检查内存错误。要启用 ASAN 和 LSAN，请在调试模式下配置 CMake，并像往常那样运行测试。如果存在内存错误，您将看到一个内存错误报告。你也可以使用 Valgrind 来检查内存错误。

⚠️ 对于 macOS 用户来说，leak sanitizer 和 Valgrind 都不起作用，他们仍然可以使用 AddressSanitizer。

Run Valgrind with this command:

valgrind \
    --error-exitcode=1 \
    --leak-check=full \
    ./test/starter_trie_test

Development Hints

不要使用 printf 语句进行调试，而是使用 LOG_* macros 来记录信息：

LOG_INFO("# Pages: %d", num_pages);
LOG_DEBUG("Fetching page %d", page_id);

要在项目中启用 logging，需在 cmake 时添加 -DCMAKE_BUILD_TYPE=Debug 或在 IDE 中启用 debug mode。

src/include/common/logger.h 定义了不同的 logging level。enabling logging 后 logging level 默认为 LOG_LEVEL_INFO。任何级别等于或高于 LOG_LEVEL_INFO (e.g., LOG_INFO, LOG_WARN, LOG_ERROR) 的日志记录方法都将发出日志记录信息。

⚠️ 您需要将 #include "common/logger.h" 添加到希望使用日志记录基础结构的文件中。

我们鼓励在遇到问题时使用 gdb 来调试项目。

如果遇到编译问题，运行 make clean 不会完全重置编译过程。 在重新运行 make 之前，您需要删除构建目录并再次运行 cmake..。

提交标准

为了通过这个项目，您必须确保您的代码遵循以下准则：

• 提交是否成功地执行了所有的测试用例并产生了正确的答案？
• 提交是否在没有任何内存泄漏的情况下执行？
• 提交是否遵循代码格式和样式策略？

请注意，我们将使用额外的测试用例（比我们提供给你的测试用例更复杂）对你的提交进行评级。

虽然你可以随心所欲地多次提交你的答案，但是你不应该把 Gradescope 作为你唯一的调试工具。大多数学生在截止日期前提交他们的项目，因此 Grescope 需要更长的时间来处理请求。您可能无法及时获得反馈以帮助您调试问题。此外，Gradescope 的输出不太可能像调试器(如 gdb)的输出那样具有信息量，前提是你投入一些时间学习如何使用它。

课程为非 CMU 学生也提供了 GradeScope 评分权限，点击右上角 Sign Up，填入课程码 PXWVR5，学校选择 CMU（不是你自己的学校），下面填自己的信息。

注册成功后可以看到已经自动加入到本课程中了。每个 Project 的 Submission 部分会指引怎么打包代码文件并提交。