How to Debug libCacheSim Simulations with GDB: Complete Developer Guide

libCacheSim provides a dedicated debug script at 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 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). 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:

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

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

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

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

./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:

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 file contains specific instructions for setting up the VS Code launch.json to point to this debug binary, enabling integrated graphical debugging with breakpoints and variable inspection.

Summary

• Use 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 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 in the repository root, with comprehensive documentation available in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}