# How to Debug libCacheSim Simulations with GDB: Complete Developer Guide

> Learn to debug libCacheSim simulations using GDB with our complete developer guide. Our script automates building a debug CMake configuration and launches GDB for source-level debugging.

- Repository: [Juncheng Yang/libcachesim](https://github.com/1a1a11a/libcachesim)
- Tags: how-to-guide
- Published: 2026-02-23

---

**libCacheSim provides a dedicated debug script at [`scripts/debug.sh`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/debug.sh) that automates building a debug‑type CMake configuration and launches GDB with the `cachesim` executable, enabling source‑level debugging of cache simulations.**

Debugging cache replacement algorithms and trace processing in the `1a1a11a/libcachesim` repository requires a build with full debugging symbols. The project includes an automated debug script that handles the entire setup, from compiling with strict warning flags to launching GDB with optimized settings for simulation analysis.

## Using the Automated Debug Script

The [`scripts/debug.sh`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/debug.sh) file is the primary entry point for debugging libCacheSim. According to the source code, this script performs four critical operations: creating a dedicated debug build directory, configuring CMake with debug flags, compiling with Ninja, and launching GDB.

### What the Script Configures

When executed, the script creates a `_build_dbg` directory and runs CMake with `-DCMAKE_BUILD_TYPE=Debug` to retain all symbols. It enforces strict compilation standards by adding `-Wall -Wextra -Werror` for both C and C++ compilers (lines 62‑67 of [`scripts/debug.sh`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/debug.sh)). The project is then built using `ninja`, producing the debug executable at `_build_dbg/bin/cachesim`.

The script automatically invokes GDB with `set print thread-events off` to suppress thread-exit messages and keep output clean. If you provide program arguments after the `--` separator, they are passed unchanged to the `cachesim` binary.

### Common Script Workflows

**Full-cycle debugging** allows the script to handle both building and launching:

```bash
./scripts/debug.sh -- data/cloudPhysicsIO.vscsi vscsi lru 100m,1gb

```

**Clean rebuild** forces a fresh compilation before debugging by passing the `-c` flag:

```bash
./scripts/debug.sh -c -- data/cloudPhysicsIO.vscsi vscsi lru 100m,1gb

```

**Basic launch** with no arguments starts GDB with the default configuration:

```bash
./scripts/debug.sh

```

## Manual GDB Configuration

If you prefer to launch GDB manually rather than using the script, first ensure you have built the project with `CMAKE_BUILD_TYPE=Debug`. Then invoke GDB with the debug binary and recommended settings:

```bash
gdb -ex "set print thread-events off" -ex r \
    --args _build_dbg/bin/cachesim data/cloudPhysicsIO.vscsi vscsi lru 100m,1gb

```

This command disables thread-event printing and immediately runs the executable upon launch, placing you at the first breakpoint or the program exit.

## Essential GDB Commands for Cache Simulation

When debugging libCacheSim simulations, these GDB commands target the specific architecture of the project:

- **`b LRU_get`** and **`b LRU_put`** — Set breakpoints in the LRU cache implementation to inspect cache hits and insertions
- **`b vscsi_read_one_req`** — Break inside the VSCSI trace reader to examine how trace files are parsed
- **`b adaptsize_admit`** — Pause execution in the adaptive-size admission policy to study object admission decisions
- **`r`** (run) and **`c`** (continue) — Control execution flow
- **`bt`** — Display the back-trace when investigating crashes
- **`p <variable>`** — Print variable values at specific execution points
- **`watch <variable>`** — Monitor variables for changes during algorithm execution
- **`info locals`** and **`info args`** — Inspect local variables and function arguments in the current frame

## VS Code Integration

The debug script output path `_build_dbg/bin/cachesim` can be referenced directly in Visual Studio Code launch configurations. The [`doc/debug.md`](https://github.com/1a1a11a/libcachesim/blob/main/doc/debug.md) file contains specific instructions for setting up the VS Code [`launch.json`](https://github.com/1a1a11a/libcachesim/blob/main/launch.json) to point to this debug binary, enabling integrated graphical debugging with breakpoints and variable inspection.

## Summary

- **Use [`scripts/debug.sh`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/debug.sh)** to automate debug builds and GDB launching in libCacheSim, located in the root of the `1a1a11a/libcachesim` repository
- **The script creates `_build_dbg`** with `CMAKE_BUILD_TYPE=Debug` and strict warning flags (`-Wall -Wextra -Werror`) to ensure symbol retention and code quality
- **Pass arguments** to the simulation using the `--` separator when invoking the debug script
- **Force clean builds** with the `-c` flag to avoid stale object files
- **Set strategic breakpoints** at `LRU_get`, `LRU_put`, `vscsi_read_one_req`, or `adaptsize_admit` to inspect core cache behaviors
- **Reference [`doc/debug.md`](https://github.com/1a1a11a/libcachesim/blob/main/doc/debug.md)** for IDE integration instructions and advanced debugging workflows

## Frequently Asked Questions

### Where is the debug script located in libCacheSim?

The debug script is located at [`scripts/debug.sh`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/debug.sh) in the repository root, with comprehensive documentation available in [`doc/debug.md`](https://github.com/1a1a11a/libcachesim/blob/main/doc/debug.md). This script is the recommended method for building and debugging the project, as it ensures consistent compiler flags and GDB configuration across different development environments.

### How do I pass command-line arguments to cachesim when using the debug script?

Place your arguments after the `--` separator. For example: `./scripts/debug.sh -- data/cloudPhysicsIO.vscsi vscsi lru 100m,1gb`. Everything following the double dash is forwarded directly to the `_build_dbg/bin/cachesim` executable inside the GDB session.

### Can I debug libCacheSim without using the provided script?

Yes, you can manually create a debug build by running CMake with `-DCMAKE_BUILD_TYPE=Debug`, building with `ninja`, and then launching GDB with `_build_dbg/bin/cachesim`. However, using [`scripts/debug.sh`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/debug.sh) is recommended because it automatically applies strict warning flags (`-Wall -Wextra -Werror`) and configures GDB with `set print thread-events off` for optimal debugging output.

### What are the most useful breakpoints for debugging cache algorithms?

For debugging cache replacement logic, set breakpoints at **`LRU_get`** and **`LRU_put`** in the LRU implementation. To inspect trace file processing, use **`b vscsi_read_one_req`**. For admission policy analysis, set a breakpoint at **`adaptsize_admit`**. These entry points allow you to examine object flow, eviction decisions, and admission controls during simulation execution.