Re: [PATCH] gdb: add tutorial command

[Guinevere Larsen <guinevere@redhat.com>]

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