Debugging Workshop

Welcome to the Debugging workshop at ICCS Summer School 2025. This tutorial will introduce the basics of debuggers with some carefully chosen examples, to demonstrate the power of debuggers ⚡.

This repo contains some example programs to help you learn how to use gdb and mdb.

└── exercises
    ├── ex1_play
    ├── ex2_occasional
    ├── ex3_memory
    └── ex4_mpi

In each folder there is a README.md which contains instructions on how to run the example programs and some helper scripts should you need them for guidance. Effort has been made to provide examples in multiple languages i.e., C++ and Fortran. I appreciate some of you may be more familiar with one language over another, but I have tried to keep the examples as simple as possible.

If you finish the examples early, feel free to tackle your own codes in the wild 🔍🐛.

Prerequisites

Background knowledge

• Unix command line (things like cding, running the make command and running binaries like this ./myprogram.exe)
• Basic experience with a compiled language (C/C++/Fortran or Rust)
• No prior knowledge of debuggers is assumed
• (optional) Experience with MPI programs

Software

• (optional but recommended) install VS Code
• If you do not have VS Code, you will need a browser (Firefox/Chrome have been tested)

Getting Started

This course is designed to run in GitHub codespaces. There are two main ways that you can run a codespace.

1. Visual Studio Code (recommended)
2. Your internet browser -- option 1 is recommended because the browser sometimes absorbs keyboard shortcuts. You should still be able to complete the entire course without any issues.

Instructions are provided below.

Note

GitHub codespaces provides free monthly usage of 120 core hours. We should only need 3 for this course. For more info on billing please see GitHub's documentation.

Note

GitHub provides a default of 2 cores and 8 GB Ram, which is more than enough for this course. If you select 4 cores, when creating a new codespace it will use twice as many core hours from your allowance.

Note

The first time you create this codespace it will take 2-3 minutes to load (whilst it pulls the docker image and runs initial setup). Re-connecting to a previous session will be much quicker.

Running in Visual Studio Code

(click here to expand instructions)

1. Open Visual Studio Code (code)
2. If you haven't already, download the "GitHub Codespaces" extension
   • Click "Extensions" (or press CTRL+SHIFT+X)
   • Type "GitHub Codespaces"
3. Click on "Remote Explorer" in the side bar
4. If you haven't already, sign into your GitHub account
5. Click "Create Codespace"
6. Type https://github.com/Cambridge-ICCS/debugging-workshop into the search bar and press the Enter key.
7. Click "main Default Branch"
8. Click "2 cores, 8 GB RAM, 32 GB storage"
9. This will connect to a remote instance of the GitHub codespace. You are now ready to start the course! 🎉

Running in Browser

(click here to expand instructions)

1. Navigate to https://github.com/Cambridge-ICCS/debugging-workshop
2. Click on the + icon to create a new on branch main
3. This will open a new tab in your browser with a Visual Studio Code interface connected to the GitHub codespace. You are now ready to start the course! 🎉

Start the Course 💻

Now that we have the codespace running in VSCode or the browser, we can get started with the course. All of the following instructions will be the same regardless of how you setup your codespace.

Navigate into the exercises folder and start with exercise 1.

cd exercises/ex1_play/

Start reading through the README.md for that exercise i.e., exercises/ex1_play/README.md.