[PATCH] gdb: add tutorial command

[PATCH] gdb: add tutorial command

[Guinevere Larsen]

Before this commit, there is little way for a new user to learn how to
use GDB on their own.  The documentation contains an example session,
but that isn't contained in GDB itself, and the "help" and "apropos"
commands exist, but they aren't the best to really teach what GDB can
do, only to describe commands on their own.

This commit changes this by introducing a command called "tutorial",
which takes a page out of common design from the last few decades and
provides a self-contained tutorial for users, walking them through a
simple bug in C code, and explaining several commands in context.
---
 gdb/NEWS                               |   4 +
 gdb/data-directory/Makefile.in         |   1 +
 gdb/python/lib/gdb/command/tutorial.py | 358 +++++++++++++++++++++++++
 3 files changed, 363 insertions(+)
 create mode 100644 gdb/python/lib/gdb/command/tutorial.py

diff --git a/gdb/NEWS b/gdb/NEWS
index 01c998f4ea0..4543404d28a 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -59,6 +59,10 @@ maintenance test-remote-args ARGS
   Test splitting and joining of inferior arguments ARGS as they would
   be split and joined when being passed to a remote target.
 
+tutorial
+  Guided example session with a generated C file, to teach an entirely
+  new user how to use GDB for basic debugging.
+
 * Changed commands
 
 maintenance info program-spaces
diff --git a/gdb/data-directory/Makefile.in b/gdb/data-directory/Makefile.in
index d7f4c988fb6..d80ff760ee6 100644
--- a/gdb/data-directory/Makefile.in
+++ b/gdb/data-directory/Makefile.in
@@ -93,6 +93,7 @@ PYTHON_FILE_LIST = \
 	gdb/command/missing_files.py \
 	gdb/command/pretty_printers.py \
 	gdb/command/prompt.py \
+	gdb/command/tutorial.py \
 	gdb/command/type_printers.py \
 	gdb/command/unwinders.py \
 	gdb/command/xmethods.py \
diff --git a/gdb/python/lib/gdb/command/tutorial.py b/gdb/python/lib/gdb/command/tutorial.py
new file mode 100644
index 00000000000..2ca4565793e
--- /dev/null
+++ b/gdb/python/lib/gdb/command/tutorial.py
@@ -0,0 +1,358 @@
+# GDB 'tutorial' command.
+# Copyright (C) 2025 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Implementation of the GDB 'tutorial' command using the GDB Python API."""
+
+import os
+
+import gdb
+
+state_string = [
+    """
+Welcome to GDB! This quick tutorial should be enough to get
+you acquainted with essential commands for basic debugging.
+At any point, you can feel free to use 'help <command>' to
+learn more about the commands that are being suggested, or
+any other commands that you may have heard of.  You may also
+type 'quit' at any point to quit this tutorial, and use it
+again to quit GDB entirely.
+
+First, GDB will generate a C file with example code for the
+debug session.  The code will contain a slightly flawed
+implementation of a bubble sort, which is used to sort an
+array of size 6.  After the function is called, the program
+will print either "sorted" or "not sorted" depending on
+the result.  Finally, the program will return 0 if the array
+is *not* sorted, and 1 if it is sorted.
+
+Enter the desired name for the file.  This is important to
+avoid a collision that could overwrite your local data.
+""",
+    """
+Please enter the desired binary name for the example program.
+""",
+    """
+Finally, please enter the compilation line for your compiler of
+choice.  If you don't know how to compile via command line, you
+can try using:""",
+    """
+To start properly debugging, first the file, which GDB calls the
+"inferior", needs to be loaded.  That is how this tutorial
+will refer to it from now on.
+Use the following command to load the inferior:""",
+    """
+Next, you should verify that there really is a bug in the
+example, by running the entire program.  One way to do that
+is by using the command "start", which runs the inferior
+until the first line of the main function, and then use the
+command "continue", which runs the inferior until it is
+forced to stop, such as by a breakpoint, signal or finishing.
+""",
+    """
+You've verified that the bug is there, now you should check
+if the bug is happening in the sort function or in the
+verification function.  Stop after the sorting function, to
+be able to confirm if the array is sorted or not.
+You can do so by using "list main" to find the line number
+after the call to 'sort', then using the command "break <num>"
+to break right before executing line '<num>'.  Then, execute
+the inferior again.
+If the call to the function 'sort' was not visible, following
+invocations of "list" will print following lines of the source
+code.
+""",
+    """
+You can check the value of the variable with the command
+"print vec".  That command will evaluate any arbitrary
+expression valid for the current language, with all side effects
+that the expression would have.
+This means you can use it to prototype a solution without
+needing to recompile the inferior.  Try it by setting 'vec'
+to a sorted array, like by using:
+    print vec = {0, 1, 2, 3, 4, 5}
+and see how the program would end, with the "continue"
+command again.
+""",
+    """
+Now that you're sure that 'sorted' is working correctly, you
+should get to the start of the 'sort' function.  You can set a
+breakpoint using the function name, or you can repeatedly use
+the command "step" after "start", to move one line at a time,
+and entering any function calls that happen.
+""",
+    """
+This is the end of the tutorial.  Feel free to debug to your
+preference.  The following commands may be helpful:
+    "next" - execute one line, skips functions
+    "display" - like print, but every time the inferior stops
+    "watch" - like breakpoint, but when a variable changes
+Feel free to use "help <cmd>" to get more information on those
+commands.
+
+Additionally, if you'd like to see the entire array like it
+was printed in the 'main' function, use the following syntax:
+    print (*vec)@6
+
+Once you satisfied with exploring this example
+program, use "quit" to leave the tutorial.
+""",
+]
+
+
+class Tutorial(gdb.Command):
+    """Tutorial on the usage of the core commands of GDB.
+
+    usage: tutorial
+
+    This tutorial does not aim to be comprehensive. On the contrary,
+    it aims to be a quick way for you to start using GDB and learn
+    how to search for more commands that you may find useful.
+    """
+
+    def __init__(self):
+        super(Tutorial, self).__init__(
+            name="tutorial", command_class=gdb.COMMAND_ESSENTIAL, prefix=False
+        )
+        # If left empty, the files won't have been created yet.
+        self.example_file = ""
+        self.output_file = ""
+        self.prompt = "(tutorial-gdb) "
+        # Whether we should print a recap of the tutorial when
+        # leaving.
+        self.should_print_recap = False
+        # Get last word of the input, this is either "on." or "off.".
+        pagination = gdb.execute("show pagination", to_string=True).split()[-1]
+        # Remove period at the end.
+        self.pagination = pagination.strip(".")
+
+    def invoke(self, arg_str, from_tty):
+        self._setup()
+        print(state_string[0])
+        self.example_file = self._get_user_input(
+            "Leave empty for default, example_code.c: "
+        )
+
+        if self.example_file == "":
+            self.example_file = "example_code.c"
+
+        try:
+            self._generateFile()
+            self.teachMainCommands()
+        except Exception:
+            print("leaving tutorial")
+        finally:
+            if self.should_print_recap:
+                self._print_recap()
+            self._cleanup()
+
+    def _setup(self):
+        # Avoid pagination as the command will take several screens to be
+        # fully executed.
+        gdb.execute("set pagination off")
+        # $_exitcode is used to recognize when the user has executed the
+        # inferior at least once, to advance the state.  Therefore we
+        # need it to start with the known value of "no execution".
+        gdb.set_convenience_variable("_exitcode", None)
+
+    def _cleanup(self):
+        # Clean up example code.
+        try:
+            f = open(self.example_file)
+            f.close()
+            print("removing", self.example_file)
+            os.remove(self.example_file)
+        except FileNotFoundError:
+            # File doesn't exist, nothing to do.
+            pass
+        try:
+            f = open(self.output_file)
+            f.close()
+            print("removing", self.output_file)
+            os.remove(self.output_file)
+        except FileNotFoundError:
+            # File doesn't exist, nothing to do.
+            pass
+        # Undo setup.  Pagination should be the last change.
+        gdb.execute("set pagination " + self.pagination)
+
+    def _get_user_input(self, msg):
+        inp = input(msg)
+        while inp.startswith("help "):
+            try:
+                gdb.execute(inp)
+            except gdb.error as e:
+                print(e)
+            inp = input(msg)
+        if inp == "quit":
+            raise Exception("user requested to quit")
+        return inp
+
+    def _run_user_input(self, msg):
+        inp = self._get_user_input(msg)
+        try:
+            gdb.execute(inp)
+        except gdb.error as e:
+            print(e)
+
+    def _print_recap(self):
+        print(
+            """
+Thank you for taking this tutorial.  We hope it has been
+helpful for you.  If you found any bugs or would like to
+provide feedback, feel free to send do so through IRC, in
+the #gdb room of libera.chat, or send an email to
+gdb@sourceware.org.
+To recap, these were the commands explained in the tutorial
+  * shell
+  * file
+  * start
+  * continue
+  * list
+  * break
+  * print
+  * step
+  * next
+  * display
+  * watch
+  * quit
+  * help
+  """
+        )
+
+    def _get_inferior_binary(self):
+        inf = gdb.execute("inferior", to_string=True)
+        inf = inf[inf.find("(") + 1 : inf.rfind(")")]
+        return inf
+
+    def teachMainCommands(self):
+        print(state_string[3])
+        print("    file", self.output_file)
+        curr_bin = ""
+        while not curr_bin.endswith(self.output_file):
+            self._run_user_input(self.prompt)
+            curr_bin = self._get_inferior_binary()
+
+        print(state_string[4])
+        while gdb.convenience_variable("_exitcode") is None:
+            self._run_user_input(self.prompt)
+
+        print(state_string[5])
+        while not self.inferior_in_location(25):
+            self._run_user_input(self.prompt)
+
+        print(state_string[6])
+        while gdb.convenience_variable("_exitcode") != 1:
+            self._run_user_input(self.prompt)
+
+        print(state_string[7])
+        while not self.inferior_in_location(13, 20):
+            self._run_user_input(self.prompt)
+
+        self.should_print_recap = True
+        print(state_string[8])
+        while True:
+            self._run_user_input(self.prompt)
+
+    def inferior_in_location(self, first_line, last_line=None):
+        # This is in a try block because if the inferior isn't running,
+        # a "No stack" exception is thrown.
+        try:
+            loc = gdb.execute("frame", to_string=True)
+            loc = int(loc.split("\n")[1].split()[0])
+            if loc > first_line:
+                if last_line is None or loc <= last_line:
+                    return True
+        except gdb.error:
+            pass
+        return False
+
+    def _generateFile(self):
+        code = """
+#include <stdio.h>
+
+int sorted(int *vec, int size);
+
+void swap(int *a, int *b)
+{
+  int tmp = *a;
+  *a = *b;
+  *b = tmp;
+}
+
+int sort(int *vec, int size)
+{
+  for (int i = 0; i < size; i++)
+    for (int j = i; j < size - 1; j++)
+      if (vec[j] >= vec[j+1])
+        swap (&vec[j], &vec[j+1]);
+}
+
+int main ()
+{
+  int vec[6] = {5, 4, 3, 2, 1, 0};
+
+  sort(vec, 6);
+  return !sorted(vec, 6);
+}
+
+int sorted(int *vec, int size)
+{
+  int ret = 0;
+  for (int i = 0; i < size - 1; i++)
+    {
+      if (vec[i] > vec[i+1])
+        {
+          printf("not ");
+          ret = 1;
+          break;
+        }
+    }
+  printf("sorted\\n");
+  return ret;
+}"""
+        try:
+            with open(self.example_file, "w") as f:
+                f.write(code)
+            print("Example code was created successfully")
+        except Exception:
+            print("Unable to automate creation of example code.")
+            print("Please paste the following in a file named")
+            print(f'"{self.example_file}"')
+            print(code)
+
+        print(state_string[1])
+        self.output_file = self._get_user_input(
+            "Leave empty for the default name, a.out: "
+        )
+        if self.output_file == "":
+            self.output_file = "a.out"
+
+        print(state_string[2])
+        print(f"  gcc {self.example_file} -g -o {self.output_file}\n")
+        inp = self._get_user_input("Enter the compilation command: ")
+        if inp == "":
+            inp = "gcc " + self.example_file + " -g -o " + self.output_file
+        gdb.execute(f"shell {inp}")
+
+        if gdb.convenience_variable("_shell_exitcode") != 0:
+            print("Compilation failed.  This might have been because of")
+            print("a typo in your input, or the compiler not being in the")
+            print("path.  Please ensure that the command line is correct:")
+            print(inp)
+            raise Exception("compilation fail")
+
+
+Tutorial()

base-commit: 25902bd0baaf58ae86ac46f7d1d71f3f9ee62c1c
-- 
2.52.0

Re: [PATCH] gdb: add tutorial command

[Eli Zaretskii]

> From: Guinevere Larsen <guinevere@redhat.com>
> Cc: Guinevere Larsen <guinevere@redhat.com>
> Date: Mon,  1 Dec 2025 14:08:19 -0300
> 
> Before this commit, there is little way for a new user to learn how to
> use GDB on their own.  The documentation contains an example session,
> but that isn't contained in GDB itself, and the "help" and "apropos"
> commands exist, but they aren't the best to really teach what GDB can
> do, only to describe commands on their own.
> 
> This commit changes this by introducing a command called "tutorial",
> which takes a page out of common design from the last few decades and
> provides a self-contained tutorial for users, walking them through a
> simple bug in C code, and explaining several commands in context.

Thanks.  It's a very good idea to have an interactive tutorial, but I
suggest we discuss a few alternatives for implementing it before
diving into the details.

First, writing this command in Python means that GDB without Python
will not have a tutorial, which is IMO a pity.  Is it so complicated
to have this implemented in C++ instead?  The text and the basic
script of the tutorial session could be on a text file that code
accesses when the tutorial is running, so that only the necessary
stuff needs to be in code.

Next, I'm not sure we need to compile a program for this purpose.  We
could use the GDB executable itself instead: that would allow us to
show the basic commands without the need for the user to have a
compiler and a working development environment to go with it.

Also, a tutorial doesn't have to teach people how to debug, it could
only teach them the important GDB commands to use for debugging.
Doing both makes the tutorial more complex because it teaches two
non-trivial subjects instead of just one.

What do others think?

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 01c998f4ea0..4543404d28a 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -59,6 +59,10 @@ maintenance test-remote-args ARGS
>    Test splitting and joining of inferior arguments ARGS as they would
>    be split and joined when being passed to a remote target.
>  
> +tutorial
> +  Guided example session with a generated C file, to teach an entirely
> +  new user how to use GDB for basic debugging.
> +
>  * Changed commands

This part is okay.  Should we describe this in the manual as well?

Reviewed-By: Eli Zaretskii <eliz@gnu.org>

Re: [PATCH] gdb: add tutorial command

[Guinevere Larsen]

On 12/2/25 11:20 AM, Eli Zaretskii wrote:
>> From: Guinevere Larsen <guinevere@redhat.com>
>> Cc: Guinevere Larsen <guinevere@redhat.com>
>> Date: Mon,  1 Dec 2025 14:08:19 -0300
>>
>> Before this commit, there is little way for a new user to learn how to
>> use GDB on their own.  The documentation contains an example session,
>> but that isn't contained in GDB itself, and the "help" and "apropos"
>> commands exist, but they aren't the best to really teach what GDB can
>> do, only to describe commands on their own.
>>
>> This commit changes this by introducing a command called "tutorial",
>> which takes a page out of common design from the last few decades and
>> provides a self-contained tutorial for users, walking them through a
>> simple bug in C code, and explaining several commands in context.
> Thanks.  It's a very good idea to have an interactive tutorial, but I
> suggest we discuss a few alternatives for implementing it before
> diving into the details.
>
> First, writing this command in Python means that GDB without Python
> will not have a tutorial, which is IMO a pity.  Is it so complicated
> to have this implemented in C++ instead?  The text and the basic
> script of the tutorial session could be on a text file that code
> accesses when the tutorial is running, so that only the necessary
> stuff needs to be in code.

I haven't looked into attempting to implement this as a C++, however, 
considering that the only other fully interactive command is also in 
python (the explore command), I figured this was a decent way to go 
about things.

>
> Next, I'm not sure we need to compile a program for this purpose.  We
> could use the GDB executable itself instead: that would allow us to
> show the basic commands without the need for the user to have a
> compiler and a working development environment to go with it.

Strong disagree here. If we're teaching a user something, we should have 
as few complicated factors as possible, and the GDB codebase is an 
incredibly complicated factor. It's my biggest gripe with our 
documentation's current example session: it just mixes "things you 
should learn" with "things you don't have to bother about learning 
because they don't matter" in a way that can lead to unnecessary 
confusion. And since we can't know what kind of projects a user would be 
familiar with, a small C program that could fit in a screen is probably 
a good enough compromise for entirely new programmers who'd use GDB and 
advanced programmers who just never learned to use the debugger.

I'm open to the idea that this could be handled in a better way, but 
having a small example program that nearly any C programmer can 
understand (and hopefully most non-C programmers too) is a necessity.

> Also, a tutorial doesn't have to teach people how to debug, it could
> only teach them the important GDB commands to use for debugging.
> Doing both makes the tutorial more complex because it teaches two
> non-trivial subjects instead of just one.

I don't have such a strong feeling on this point, but I do think that 
the power of the tutorial comes from teaching the users how they can 
combine commands in powerful ways. If we're just listing important 
commands, would there be any meaningful difference from telling the user 
to run "help essential" ?

>
> What do others think?
>
>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index 01c998f4ea0..4543404d28a 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>> @@ -59,6 +59,10 @@ maintenance test-remote-args ARGS
>>     Test splitting and joining of inferior arguments ARGS as they would
>>     be split and joined when being passed to a remote target.
>>   
>> +tutorial
>> +  Guided example session with a generated C file, to teach an entirely
>> +  new user how to use GDB for basic debugging.
>> +
>>   * Changed commands
> This part is okay.  Should we describe this in the manual as well?
I think it should be there, yes. I forgot to add it, sorry. Will fix 
things locally, but I'll wait for more thoughts from others on the 
tutorial itself before sending a v2
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
>

-- 
Cheers,
Guinevere Larsen
It/she

Re: [PATCH] gdb: add tutorial command

[Simon Marchi]

On 12/2/25 9:20 AM, Eli Zaretskii wrote:
>> From: Guinevere Larsen <guinevere@redhat.com>
>> Cc: Guinevere Larsen <guinevere@redhat.com>
>> Date: Mon,  1 Dec 2025 14:08:19 -0300
>>
>> Before this commit, there is little way for a new user to learn how to
>> use GDB on their own.  The documentation contains an example session,
>> but that isn't contained in GDB itself, and the "help" and "apropos"
>> commands exist, but they aren't the best to really teach what GDB can
>> do, only to describe commands on their own.
>>
>> This commit changes this by introducing a command called "tutorial",
>> which takes a page out of common design from the last few decades and
>> provides a self-contained tutorial for users, walking them through a
>> simple bug in C code, and explaining several commands in context.
> 
> Thanks.  It's a very good idea to have an interactive tutorial, but I
> suggest we discuss a few alternatives for implementing it before
> diving into the details.
> 
> First, writing this command in Python means that GDB without Python
> will not have a tutorial, which is IMO a pity.  Is it so complicated
> to have this implemented in C++ instead?  The text and the basic
> script of the tutorial session could be on a text file that code
> accesses when the tutorial is running, so that only the necessary
> stuff needs to be in code.

If possible, it would indeed be nice, but I'll take a tutorial written
in Python over nothing.

Maybe an advantage to have it in C++ is that it could be better
integrated in the event-loop / command system.  I haven't look at the
current implementation in depth, but from what I see, it grabs textual
user input and passes in through gdb.execute.  This means that
things like tab completion and readline shortcuts won't work.  I think
that tab completion at least would be nice to demonstrate in the
tutorial.

> Next, I'm not sure we need to compile a program for this purpose.  We
> could use the GDB executable itself instead: that would allow us to
> show the basic commands without the need for the user to have a
> compiler and a working development environment to go with it.

I don't see how that's feasible or practical.  The GDB binary users are
most likely to have are optimized (bad debugging experience, especially
if you're learning) and won't have debug info anyway.  And like
Guinevere said, GDB is way too complicated to throw at newbies anyway.
I like Guinevere's idea of giving the user a small program they can toy
with.

> 
> Also, a tutorial doesn't have to teach people how to debug, it could
> only teach them the important GDB commands to use for debugging.
> Doing both makes the tutorial more complex because it teaches two
> non-trivial subjects instead of just one.
> 
> What do others think?

I don't understand your last point.  Do you mean that the tutorial
should just be some text that says "you can use command X to do this,
command Y to do that, etc"?  Seems way less interesting and interactive
than what is proposed here.

Simon

Re: [PATCH] gdb: add tutorial command

[Eli Zaretskii]

> Date: Tue, 2 Dec 2025 14:33:08 -0500
> Cc: gdb-patches@sourceware.org
> From: Simon Marchi <simark@simark.ca>
> 
> > First, writing this command in Python means that GDB without Python
> > will not have a tutorial, which is IMO a pity.  Is it so complicated
> > to have this implemented in C++ instead?  The text and the basic
> > script of the tutorial session could be on a text file that code
> > accesses when the tutorial is running, so that only the necessary
> > stuff needs to be in code.
> 
> If possible, it would indeed be nice, but I'll take a tutorial written
> in Python over nothing.

If the C++ implementation is not feasible or not practical, I agree.
My point is that we should consider that possibility before deciding
on a Python implementation.

> > Next, I'm not sure we need to compile a program for this purpose.  We
> > could use the GDB executable itself instead: that would allow us to
> > show the basic commands without the need for the user to have a
> > compiler and a working development environment to go with it.
> 
> I don't see how that's feasible or practical.  The GDB binary users are
> most likely to have are optimized (bad debugging experience, especially
> if you're learning) and won't have debug info anyway.  And like
> Guinevere said, GDB is way too complicated to throw at newbies anyway.
> I like Guinevere's idea of giving the user a small program they can toy
> with.

This is a _GDB_ tutorial.  It doesn't need to include a complete
debugging problem described in its entirety, right up to finding the
bug and fixing it.  It needs to show the use of important GDB
commands, under the assumption that the person using the tutorial
knows how to debug programs, but is not familiar with GDB commands to
do that.  (Yes, teaching debugging techniques in addition is helpful,
but IMO the minimal requirements from a useful tutorial are to teach
the commands.)

For the purpose of teaching the useful commands, it doesn't matter
much that GDB is optimized, the only possible problem could be that
it's stripped.  If it is not stripped, I don't see why we couldn't
show use of important commands on GDB itself, explaining their purpose
in plain text.  There's no need to solve an actual bug, just let users
tinker with commands when they have a live program at their disposal.
Whatever the complexity of GDB, users definitely can step it, step
into functions, examine its data, set breakpoints and watchpoints and
see them break, etc.  We could also show how to change values of
variables and call functions from the program.  Moreover, if we limit
ourselves to teaching commands, we can show advanced commands and
techniques, like working with threads and scheduling them, following
'fork', handling signals, etc. -- these are hard to impossible to do
with toy programs, but they are needed in most real-life debugging
sessions.

> > Also, a tutorial doesn't have to teach people how to debug, it could
> > only teach them the important GDB commands to use for debugging.
> > Doing both makes the tutorial more complex because it teaches two
> > non-trivial subjects instead of just one.
> > 
> > What do others think?
> 
> I don't understand your last point.  Do you mean that the tutorial
> should just be some text that says "you can use command X to do this,
> command Y to do that, etc"?  Seems way less interesting and interactive
> than what is proposed here.

Yes, I mean just describe the important commands and let the user try
them and see the results.

Indeed, teaching both debugging techniques and GDB commands is better,
but that job is much more complex if taken seriously.  And I question
the actual value of showing how to debug a toy program anyway, because
it is nothing like debugging real-life programs.  The latter
frequently requires advanced techniques, some of them special to the
program in question (e.g., see etc/DEBUG in the Emacs source tree).

So I suggest to start from a modest task of showing and teaching the
important commands, leaving the rest to the users, who will need to
learn much more, if they never debugged a real-life program.  We may
decide in the future to have a separate tutorial about debugging
techniques.

Please note that the above is just MO; I will not object and won't
argue if you-all think differently.  I just wanted to present an
alternative POV, so that people could think about this and make up
their minds.  After all, it is unlikely that I will use this tutorial
myself...

Re: [PATCH] gdb: add tutorial command

[Guinevere Larsen]

[-- Attachment #1: Type: text/plain, Size: 7438 bytes --]

On 12/3/25 9:43 AM, Eli Zaretskii wrote:
>> Date: Tue, 2 Dec 2025 14:33:08 -0500
>> Cc:gdb-patches@sourceware.org
>> From: Simon Marchi<simark@simark.ca>
>>
>>> First, writing this command in Python means that GDB without Python
>>> will not have a tutorial, which is IMO a pity.  Is it so complicated
>>> to have this implemented in C++ instead?  The text and the basic
>>> script of the tutorial session could be on a text file that code
>>> accesses when the tutorial is running, so that only the necessary
>>> stuff needs to be in code.
>> If possible, it would indeed be nice, but I'll take a tutorial written
>> in Python over nothing.
> If the C++ implementation is not feasible or not practical, I agree.
> My point is that we should consider that possibility before deciding
> on a Python implementation.
>
>>> Next, I'm not sure we need to compile a program for this purpose.  We
>>> could use the GDB executable itself instead: that would allow us to
>>> show the basic commands without the need for the user to have a
>>> compiler and a working development environment to go with it.
>> I don't see how that's feasible or practical.  The GDB binary users are
>> most likely to have are optimized (bad debugging experience, especially
>> if you're learning) and won't have debug info anyway.  And like
>> Guinevere said, GDB is way too complicated to throw at newbies anyway.
>> I like Guinevere's idea of giving the user a small program they can toy
>> with.
> This is a _GDB_ tutorial.  It doesn't need to include a complete
> debugging problem described in its entirety, right up to finding the
> bug and fixing it.  It needs to show the use of important GDB
> commands, under the assumption that the person using the tutorial
> knows how to debug programs, but is not familiar with GDB commands to
> do that.  (Yes, teaching debugging techniques in addition is helpful,
> but IMO the minimal requirements from a useful tutorial are to teach
> the commands.)
>
> For the purpose of teaching the useful commands, it doesn't matter
> much that GDB is optimized, the only possible problem could be that
> it's stripped.  If it is not stripped, I don't see why we couldn't
> show use of important commands on GDB itself, explaining their purpose
> in plain text.  There's no need to solve an actual bug, just let users
> tinker with commands when they have a live program at their disposal.
> Whatever the complexity of GDB, users definitely can step it, step
> into functions, examine its data, set breakpoints and watchpoints and
> see them break, etc.  We could also show how to change values of
> variables and call functions from the program.

It does matter that GDB is optimized, though. Assuming that the user 
could get debug info, they could use "next" and end up in a previous 
line because the compiler decided to reorder instructions/lines, they 
could try to step into a function that was entirely optimized away, they 
could try to read the value of a variable only to find that it was 
optimized away

And, most importantly, if they aren't familiar with GDB, it isn't 
unreasnable to think they never used a debugger before and only did 
printf debugging. Having those confusing reactions would only cement in 
such user's brains that debuggers are actually not as useful as printf, 
because variables can disappear when they never do in a printf, for example.

Lastly, we aren't arguing about still needing to come up with a small 
toy problem. I already did that, the code is already here. The decision 
is "should we scrap what has already been done or not" rather than 
"should we come up with something very good from scratch or not".

> Moreover, if we limit
> ourselves to teaching commands, we can show advanced commands and
> techniques, like working with threads and scheduling them, following
> 'fork', handling signals, etc. -- these are hard to impossible to do
> with toy programs, but they are needed in most real-life debugging
> sessions.

These are most definitely out of scope for a tutorial that opens with 
"welcome to GDB" and assumes minimal knowledge of programming in 
general. But that's ok, because this doesn't have to be the only 
tutorial. What I'm presenting here is a quickstart tutorial, that'll get 
users acquainted with general purpose tools, and this framework can 
easily be expanded to have specific tutorials, like multi-threaded 
debugging, reverse debugging, linker namespace debugging and other 
advanced cases I haven't ran into.

Also, I think it's worth to note that I haven't used any of the other 
commands. So unless my last 5 years of work experience (4 of them in 
GDB) aren't real life debugging sessions, I think you're overestimating 
the commonality of the issues you deal with.

>
>>> Also, a tutorial doesn't have to teach people how to debug, it could
>>> only teach them the important GDB commands to use for debugging.
>>> Doing both makes the tutorial more complex because it teaches two
>>> non-trivial subjects instead of just one.
>>>
>>> What do others think?
>> I don't understand your last point.  Do you mean that the tutorial
>> should just be some text that says "you can use command X to do this,
>> command Y to do that, etc"?  Seems way less interesting and interactive
>> than what is proposed here.
> Yes, I mean just describe the important commands and let the user try
> them and see the results.
Then I don't see the difference between using "tutorial" or telling the 
user to use "help essential". And if that is your suggestion, we already 
have the C++ implementation of a tutorial.
>
> Indeed, teaching both debugging techniques and GDB commands is better,
> but that job is much more complex if taken seriously.
But I already did the job. This is already implemented. Your suggestion 
is that, because the task is hard, we shouldn't use the solution I 
already came up with?
> And I question
> the actual value of showing how to debug a toy program anyway, because
> it is nothing like debugging real-life programs.
I am unfamiliar with any starter tutorial that, both, starts with a real 
life example showing all the complexities of real life example and is 
well liked at the same time.
> The latter
> frequently requires advanced techniques, some of them special to the
> program in question (e.g., see etc/DEBUG in the Emacs source tree).

Again, this isn't meant to be the tutorial that teaches all of GDB; to 
quote the tutorial's own opening words: "This quick tutorial should be 
enough to get ou acquainted with essential commands for basic debugging."

Once a first tutorial goes through and we have a basic framework for how 
to teach things to users, you're welcome to try your hand at teaching 
the advanced techniques with a tutorial of your own, say "tutorial 
multithreaded" for example.

> So I suggest to start from a modest task of showing and teaching the
> important commands, leaving the rest to the users, who will need to
> learn much more, if they never debugged a real-life program.  We may
> decide in the future to have a separate tutorial about debugging
> techniques.
>
> Please note that the above is just MO; I will not object and won't
> argue if you-all think differently.  I just wanted to present an
> alternative POV, so that people could think about this and make up
> their minds.  After all, it is unlikely that I will use this tutorial
> myself...
>

-- 
Cheers,
Guinevere Larsen
It/she

[-- Attachment #2: Type: text/html, Size: 9604 bytes --]

Re: [PATCH] gdb: add tutorial command

[Simon Marchi]

On 2025-12-03 08:07, Guinevere Larsen wrote:
>> This is a _GDB_ tutorial.  It doesn't need to include a complete
>> debugging problem described in its entirety, right up to finding the
>> bug and fixing it.  It needs to show the use of important GDB
>> commands, under the assumption that the person using the tutorial
>> knows how to debug programs, but is not familiar with GDB commands to
>> do that.  (Yes, teaching debugging techniques in addition is helpful,
>> but IMO the minimal requirements from a useful tutorial are to teach
>> the commands.)

I agree that it's perhaps not necessary to have a program with a bug,
and explain what is the bug, etc.  It seems distracting to me.  Having a
program that does something simple (without being too trivial) would be
sufficient to teach the user how to launch, navigate and print values.

I have minor comments like this on the content of the tutorial but
haven't had the time to formulate them.  I thought we would resolve the
more major issues / disagreements first.

>> For the purpose of teaching the useful commands, it doesn't matter
>> much that GDB is optimized, the only possible problem could be that
>> it's stripped.  If it is not stripped, I don't see why we couldn't
>> show use of important commands on GDB itself, explaining their purpose
>> in plain text.  There's no need to solve an actual bug, just let users
>> tinker with commands when they have a live program at their disposal.
>> Whatever the complexity of GDB, users definitely can step it, step
>> into functions, examine its data, set breakpoints and watchpoints and
>> see them break, etc.  We could also show how to change values of
>> variables and call functions from the program.  
> 
> It does matter that GDB is optimized, though. Assuming that the user could get debug info, they could use "next" and end up in a previous line because the compiler decided to reorder instructions/lines, they could try to step into a function that was entirely optimized away, they could try to read the value of a variable only to find that it was optimized away
> 
> And, most importantly, if they aren't familiar with GDB, it isn't unreasnable to think they never used a debugger before and only did printf debugging. Having those confusing reactions would only cement in such user's brains that debuggers are actually not as useful as printf, because variables can disappear when they never do in a printf, for example.

For this tutorial and the way it works (the user doing actions makes
the tutorial progress forward), I think we need something extremely
predictable.  Using the GDB production binary is never going to work for
that, on top of the other issues (like obtaining debug info).

>> Moreover, if we limit
>> ourselves to teaching commands, we can show advanced commands and
>> techniques, like working with threads and scheduling them, following
>> 'fork', handling signals, etc. -- these are hard to impossible to do
>> with toy programs, but they are needed in most real-life debugging
>> sessions.
> 
> These are most definitely out of scope for a tutorial that opens with "welcome to GDB" and assumes minimal knowledge of programming in general. But that's ok, because this doesn't have to be the only tutorial. What I'm presenting here is a quickstart tutorial, that'll get users acquainted with general purpose tools, and this framework can easily be expanded to have specific tutorials, like multi-threaded debugging, reverse debugging, linker namespace debugging and other advanced cases I haven't ran into.

It seems like there is a disagreement on the target audience for this
tutorial (which we could imagine being chapter 1 of a more comprehensive
tutorial).  Eli seems to think it should target seasoned programmers who
write complex programs.  Guinevere seems to think that it should be
accessible to people who start programming.

And I also think that it should be accessible to beginners, showing them
early in their journey that debuggers are useful.  Even if the example
is a toy one, I think that experienced programmers will be able to
extrapolate it to their own programs.  We can discuss further how the
material is presented exactly, but I think that the core of commands
presented in this tutorial already goes a long way, even when debugging
complex programs.

> Also, I think it's worth to note that I haven't used any of the other commands. So unless my last 5 years of work experience (4 of them in GDB) aren't real life debugging sessions, I think you're overestimating the commonality of the issues you deal with.

I agree, 95% of my day to day GDB usage to debug GDB must be:

 - break
 - run
 - print variable
 - step, step, next, finish
 - print variable
 - exit

It's not to say that other commands aren't useful on occasion, but for
the scope of a 10 minutes (or whatever is the maximum attention span
nowadays) tutorial, I think it's fine.

>> The latter
>> frequently requires advanced techniques, some of them special to the
>> program in question (e.g., see etc/DEBUG in the Emacs source tree).
> 
> Again, this isn't meant to be the tutorial that teaches all of GDB; to quote the tutorial's own opening words: "This quick tutorial should be enough to get ou acquainted with essential commands for basic debugging."
> 
> Once a first tutorial goes through and we have a basic framework for how to teach things to users, you're welcome to try your hand at teaching the advanced techniques with a tutorial of your own, say "tutorial multithreaded" for example.

Off the top of my head, I think that conditional breakpoints should be
explained.  They are relatively simple to use and useful in real-world
situations.  But this introduction tutorial would not be the right
place, perhaps in an eventual subsequent chapter.

>> So I suggest to start from a modest task of showing and teaching the
>> important commands, leaving the rest to the users, who will need to
>> learn much more, if they never debugged a real-life program.  We may
>> decide in the future to have a separate tutorial about debugging
>> techniques.

I don't really see it as showing debugging techniques.  The tutorial
with the toy example allows users to try the GDB command being taught
for themselves and see the result.  Which I guess is the point of an
interactive tutorial, over just a list of "command X does that".

Simon