Re: [PATCH v2] gdb: add tutorial command

[Eli Zaretskii <eliz@gnu.org>]

> From: Guinevere Larsen <guinevere@redhat.com>
> Cc: Guinevere Larsen <guinevere@redhat.com>
> Date: Thu, 22 Jan 2026 17:28:34 -0300
> 
>  gdb/NEWS                               |   4 +
>  gdb/data-directory/Makefile.in         |   1 +
>  gdb/doc/gdb.texinfo                    |  34 +++
>  gdb/python/lib/gdb/command/tutorial.py | 404 +++++++++++++++++++++++++
>  gdb/top.c                              |   5 +-
>  5 files changed, 447 insertions(+), 1 deletion(-)
>  create mode 100644 gdb/python/lib/gdb/command/tutorial.py

Thanks.

> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -80,6 +80,10 @@ show progress-bars enabled
>    content, to be disabled (the set command), or to see if
>    progress-bars are currently enabled or not (the show command).
>  
> +tutorial
> +  Guided example session with a generated C file, to teach an entirely
> +  new user how to use GDB for basic debugging.

Perhaps "Start a guided example session..." would be more in-line with
the style of describing commands?

Also, I think we should document that this command is only available
if GDB was built with Python, both in NEWS and in the manual.

> +@item tutorial
> +This command starts an interactive tutorial, teaching you basic commands
> +and how you can chain them together for a successful debugging session.
> +Warning: If you have an ongoing debug session, this command will kill that

I would suggest to give "Warning" the @emph or @strong markup.

> +@smallexample
> +(@value{GDBP}) tutorial

This example takes quite a few lines, but we don't want it to be
broken between pages in arbitrary places, I think.  So we should use
@group..@end group either around the entire text, or at least around
each paragraph of it.

> +Welcome to GDB! This quick tutorial should be enough to get
                 ^^
There should be two spaces there.

> +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.

Isn't it strange to teach newbies that to assign a value to a
variable, one must use the 'print' command?  Why not "set variable"?

> +            print("The solution didn't work. Try again!")
                                              ^^
> +    elif tutorial_state == (len(state_string) - 1):
> +        print(
> +            "The tutorial is complete. Exiting tutorial and cleaning up the artifacts"
                                        ^^
Two spaces between sentences again.

> +    This tutorial does not aim to be comprehensive. On the contrary,
                                                     ^^
And here.

> +    def invoke(self, arg_str, from_tty):
> +        global tutorial_state, generated_code
> +        print(
> +            """
> +Welcome to GDB! This quick tutorial should be enough to get
                 ^^
Likewise.

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