Canvas | Gradescope

Textbooks and Resources

The official course textbook is Database Systems Concepts (7th edition), Silberschatz, et al.


For additional background on OS concepts, we recommend Operating Systems: Three Easy Pieces, Arpaci-Dusseau & Arpaci-Dusseau, which is available for free online.

Tools

If you are using VSCode, we recommend you to install CMake Tools, C/C++ Extension Pack and clangd. After that, follow this tutorial to learn how to use the visual debugger in VSCode: Debug a C++ project in VS Code. (If you use the Dev Containers workflow below, these extensions are installed for you automatically inside the container.)

If you are using CLion, we recommend you to follow this tutorial: CLion Debugger Fundamentals.

If you prefer to use gdb for debugging, there are many tutorials available to teach you how to use gdb. Here are some that we have found useful:

Dev Environment

We recommend developing BusTub on Ubuntu 22.04, or using a provided container image of Ubuntu 22.04. We do not officially support any other environments (i.e., do not open issues or come to office hours to debug them). We do not support WSL. You may be able to build the project on other Ubuntu versions, as well as MacOS, but do so at your own risk. The grading environment runs Ubuntu 22.04.

Linux (Recommended) / macOS (Experimental)

To ensure that you have the proper packages on your machine, run the following script to automatically install them:

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

Then run the following commands to build the system:

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

If you want to compile the system in debug mode, pass in the following flag to cmake: Debug mode:

$ cmake -DCMAKE_BUILD_TYPE=Debug ..
$ make -j`nproc`

This enables AddressSanitizer by default.

If you want to use other sanitizers,

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

There are some differences between macOS and Linux (i.e., mutex behavior) that might cause test cases to produce different results in different platforms. We recommend students to use a Linux VM for running test cases and reproducing errors whenever possible.

While there are many ways to run in a Linux environment these days, we provide two ways for students to do this using Docker. The first step for both options is to follow the instructions for setting up Docker on your host machine.

Option 1: Docker

If you prefer to develop directly in a Linux environment, you can start and attach to a pre-configure container with all necessary packages installed by running: ./docker_exec.sh This script will create and set up a container image for bustub, or attach to a running bustub container if one already exists.

Some MacOS users have reported a command not found: docker error when first running this script. If you see this error, you most likely need to add docker to your PATH.

Option 2: VS Code Dev Containers

If you prefer to use VS Code, this repository is set up to integrate with the VS Code Dev Containers extension. In this workflow you clone your personal course repository onto your host machine and open that folder inside a container. Because your code lives in a normal clone on the host, your commits, branches, and git credentials stay on the host and your work is never trapped inside (or lost with) the container.

  1. Install the Dev Containers extension in VS Code.

  2. Clone your personal course repository if you have not already:

    $ git clone <your-personal-repo-url>

  3. Open VS Code. From the command palette (F1), run Dev Containers: Open Folder in Container… and select the folder you cloned your repo into. Wait for the container to build. The first time, it automatically installs all required packages, so this may take a few minutes. Subsequent launches are fast.

  4. Once the container is running, we must set the build configuration using the CMake tab. Click the CMake icon (triangle with a wrench) on the left side bar. Select a Configure Preset. We provide some preset configurations:

    • Debug — debug build with AddressSanitizer (the default).
    • Debug (TSan) — debug build with ThreadSanitizer, equivalent to -DBUSTUB_SANITIZER=thread. Use this for assignments and tests that require the thread sanitizer.
    • Release — optimized build with no sanitizer.
    • RelWithDebInfo — optimized build with debug info.

  5. To build and debug a specific test, click to select a target under the CMake Launch or Debug options. For example, type the test name you want when prompted. With a target selected, you can now click Launch/Debug from within CMake or at the bottom of the window.