Re: [PATCH] gdb: add tutorial command

[Simon Marchi <simark@simark.ca>]

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