Skip to content

Latest commit

 

History

History
241 lines (151 loc) · 11.2 KB

debugging_in_terminal.md

File metadata and controls

241 lines (151 loc) · 11.2 KB

How to use a debugger in the terminal?

I assume you have some minimal C++ knowledge: already tried compiling a few simple programs, and know what "variables" are. If not, come back later.

What is debugging?

"Debugging" refers to fixing a program when it doesn't work correctly, i.e. finding the issue in the code and fixing it. This is often done with the help of a debugger.

What is a debugger?

A debugger is a program that assists you in debugging. It can run your program step by step, letting you observe the values of all variables and so on.

There are several popular debuggers: LLDB, GDB, and the Visual Studio debugger. They are commonly used with Clang, GCC, and MSVC compilers respectively.

We will be using LLDB (Why LLDB?), but the other debuggers should work fine too.

LLDB and GDB are similar on the surface level. This article is written primarily for LLDB, but can be used for GDB as well.

Installing the debugger

Install LLDB in MSYS2: pacman -S mingw-w64-clang-x86_64-lldb. (Why not the official Clang installer?)

Confirm that it works by running lldb --version.

Or if you prefer GDB, install it using pacman -S mingw-w64-clang-x86_64-gdb and check it with gdb --version.

(⚠ Those installation commands assume you've been following the previous chapters of the tutorial as is. If you instead configured MSYS2 in some other manner, you might need to pick a different version of LLDB/GDB, since MSYS2 provides multiple. Consult this page for more details, or follow the tutorial from the beginning, reinstalling everything exactly as recommended.)

Debugging in the terminal

Go read Terminal for Dummies if you haven't already.

Most debuggers (except for the Visual Studio one, from what I know) can be used in a terminal. There are ways to use them with UI as well, but we'll be covering that later.

Most of the time you won't be debugging in a terminal (though sometimes this is the only option). The goal of this chapter is to give a minimal first-hand experience of doing so, before teaching more convenient methods.

Don't feel the need to remember all the commands. Just play around with the debugger as explained below a bit.

Using the debugger

Let's start with the following test program.

I assume you already know the basics of C++. If you don't understand this program, go read your C++ book a bit more and come back.

#include <iostream>

int main()
{
    int x = 10;
    for (int i = 0; i < 5; i++)
        x += i;
    std::cout << x << '\n';
}

Compiling a program with debugging information

First, you need to compile it with the -g flag, e.g. clang++ prog.cpp -o prog -g. This adds debugging information to it, allowing the debugger to interact with it in a meaningful way.

Running a program in the debugger

Start LLDB on your program using lldb prog (or gdb prog for GDB).

In LLDB you'll see something like this: (GDB prints a slightly different message)

(lldb) target create "prog.exe"
(rrent executable set to 'C:\code\a\prog.exe' (x86_64).
(lldb)

Now typing r (or run) will run your application. You'll see its window flash for a moment, and close immediately. You'll see a message similar to this:

Process 9804 exited with status = 0 (0x00000000)

0 means the program ran and finished successfully.

At the time of writing this, LLDB has a bug on Windows that causes r to fail with error: The parameter is incorrect.. If you run into this problem, install winpty using pacman -S winpty, and then use winpty lldb ... instead of lldb ....

Breakpoints

Now, to execute it step by step, you need to create a "breakpoint", i.e. tell the debugger on what line of the code to pause.

Type b 5 to put a breakpoint on line 5 (which should be int x = 10;). When more than one file is involved, you will need to a file name, e.g. b main.cpp:5. You can also target functions, e.g. b main to break when entering main().

Now if you type r again, you should see following:

lldb in action

The program is paused on line 5. You can use n (short for next) to execute one line and go to the next line.

Print the values of variables using p (short for print). E.g. try p x and p i.

Or use fr v (short for frame variable) to print all variables. (This is for LLDB; GDB users need i lo or info locals.)

Another useful command is "continue executing until a specific line", th u 10 (short for thread until 10), which can be used to quickly break out of loops. (This is for LLDB, GDB users need just u 10 or until 10.)

If you forgot on what line the program is paused, you can type f (short for frame) to get a reminder. (In GDB this only prints a single line, use l . or list . to get more context.)

Lastly, when you want to unpause your program, type c (short for continue).

Type quit or exit to exit LLDB and return to the shell.

Debugging programs that accept input

At the time of writing, at least on Windows, LLDB seems to have issues with programs that use std::cin (or read the standard input in any other way).

Let's try it on a simple program:

#include <iostream>

int main()
{
    int x = 0;
    std::cin >> x;
    std::cout << x << '\n';
}

At the time or writing, the console opens, but I'm unable to input anything. If this works for you as is, skip the rest of this section.

One solution is to prepare a text file with the input (let's say in.txt with 42 in it), and then before starting the program (before typing r), run settings set target.input-path in.txt. This will read input from a file instead of pausing and waiting for you to input something.

Alternatively, replacing r with process run -i in.txt seems to work equally well.

Debugging functions

For this, you must understand what "functions" are. If you don't, read your C++ book more and come back later.

Consider this simple program with a function:

#include <iostream>

int foo()
{
    int r = 10;
    r += 1;
    r += 2;
    r += 3;
    return r;
}

int main()
{
    int x = foo();
    std::cout << x << '\n';
}

Run this in the debugger. Place a breakpoint on line int x = foo();. Press n to go to the next line and notice that it jumps immediately to std::cout, without showing you how the function executes. How do we debug the function?

Restart the program, but this time use s (short for step) instead of n. Notice that the debugger did step into the function:

lldb steps into a function

When there's no function to enter, s is equivalent to n.

Now typing s or n will debug foo() line by line.

If you forgot where foo() was called from, type bt (meaning "backtrace") to show the "call stack":

lldb backtrace

Here frame #0 is the current line inside foo(), and frame #1 is the line in main() that called foo(). Everything below that are the internals of the standard library that called your main().

Typing e.g. f 1 (short for "frame") will show the code at that location, so you don't need to look it up by the line number. f 0 will print the current line. Just f alone will use the most recent number by default. You can also use up and down to switch between the frames.

To return back to main, you either press s or n enough times, or type fin (or finish) to return to the calling function, back at int x = foo();. But this time, typing s will jump to std::cout << ... (just like n) rather than entering foo(), because it has already finished executing.

Debugging nested errors

Consider this nonsensical program:

#include <iostream>

int main()
{
    int x = 42;
    std::cout << x << '\n';
    delete &x;
    std::cout << x << '\n';
}

It's recommended that you understand what delete is. (If not, perhaps read your C++ book more and come back later.) But it's not strictly necessary.

The point is, this program compiles, but when you run it it fails with an error, because of the incorrect use of delete.

Compile and run it (without the debugger yet), observe that the first number is printed but the second isn't. Notably it doesn't tell you what line caused the error, and in more complex cases it might not be immediately obvious from the output.

Let's try to find the offending line with the debugger. Run this program in the debugger as explained above. Don't place any breakpoints yet, just type r to run. (Though pressing n a bunch of times is a valid debugging strategy as well.)

lldb shows a cryptic error

Since the error happens deep inside delete, it doesn't directly show you the offending line in your source file.

Type bt (meaning "backtrace") to see where delete was called from:

lldb cryptic backtrace

The frame #7 ... prog.exe`main at prog.cpp:7:5 refers to the delete &x line in your program. Everything above it is the internals of delete. And as I already said above, everything below it is the internals of the standard library that called your main().

You always look for the first frame that belongs to your code, and that is the offending line.

Lastly, type f 7 (meaning "frame #7") to view that code:

lldb shows the offending frame

Debugging stuck programs

Another bit of knowledge is how to deal with "stuck" programs. Consider this code:

#include <chrono>
#include <iostream>
#include <thread>

int main()
{
    int i = 0;
    while (true)
    {
        std::this_thread::sleep_for(std::chrono::seconds(1));
        std::cout << i++ << '\n';
    }
}

This endlessly prints numbers.

If you know what loop is being executed, you can place a breakpoint there. But if you don't, you might want to just pause the program, doesn't matter where.

This is achieved by pressing CtrlC, or alternatively by typing pro i (short for process interrupt) (this is for LLDB; GDB has just interrupt, but it doesn't let you type commands while the program is running by default).

Then you can use bt as was explained above, to figure out where you are. To get meaningful results, you might need to first run t 1 first to switch to the main thread. (Threads are parts of a program that run in parallel, at the same time as one another. In addition to your main() function which is run by the main thread, there might be other code executing in parallel, in other threads, either started by the standard library or by you.)

Try it.


Next step: learn How to debug in VSCode.