From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id aX8VIVM2MGlYBRUAWB0awg (envelope-from ) for ; Wed, 03 Dec 2025 08:08:35 -0500 Authentication-Results: simark.ca; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=cdNZd/m7; dkim-atps=neutral Received: by simark.ca (Postfix, from userid 112) id 839D01E0B3; Wed, 03 Dec 2025 08:08:35 -0500 (EST) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-25) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=ARC_SIGNED,ARC_VALID,BAYES_00, DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HTML_MESSAGE, MAILING_LIST_MULTI,RCVD_IN_VALIDITY_CERTIFIED_BLOCKED, RCVD_IN_VALIDITY_RPBL_BLOCKED,RCVD_IN_VALIDITY_SAFE_BLOCKED autolearn=no autolearn_force=no version=4.0.1 Received: from sourceware.org (vm01.sourceware.org [38.145.34.32]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 8DABB1E08D for ; Wed, 03 Dec 2025 08:08:34 -0500 (EST) Received: from vm01.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 1EE1448EACEF for ; Wed, 3 Dec 2025 13:08:34 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 1EE1448EACEF Authentication-Results: sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=cdNZd/m7 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTP id 5E4E048F8A6A for ; Wed, 3 Dec 2025 13:08:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 5E4E048F8A6A Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 5E4E048F8A6A Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1764767282; cv=none; b=D5mcF4bo1j4ZFaaYIzyHUu1gbI5VPw5Q3RVI+MlASDDqP7pRWUnY1mM13m8hfAWxPnXe2Mc+t6EHkMH1dZAXGlrXTJptPRbV7BFj9g3NWBQB7Bn4lZiv+tDUtS98/t9ZUxU6rRiQSuIxf6sSlVfR4jx4aYFA0LEttbJMO0y7Kps= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1764767282; c=relaxed/simple; bh=qXDhXXQ4gchpl6KbzomdDW9uiC1kw/uZeuN+uyLaZ2c=; h=DKIM-Signature:Message-ID:Date:MIME-Version:Subject:To:From; b=B5LgpTNoPRdGDtmNr1J9cdJLfe/LOZHM/FxbnbIEH178FlsC3OLb+dGEkkRVPa1URmGjpGyLYdVmupP+BBjuSZJblcB25pd6WpoCdfbPZTIVnkR2Uq6haOoaJ0sq9rGyRp331kH/J8tInyXLsyQeyc58p1sOfNmyp2J71Tey+/U= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 5E4E048F8A6A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1764767282; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=ejyU8qrI7NbYDKLeKhaLjpI8ZbFCFgCr1UJY96Vf4RQ=; b=cdNZd/m7MIbVbVuzsKqZCfdMzxP+20uMtycgrT/jsBsAwdxWPzEc7qwad/lRLdylhHnK82 4YIn74eHqtucFj0nGkPU681an2RlZK3znJVt358qWWaXumAzJKEbV+n2JiSSa4WDb3vQl+ EpyMH+M7HfLwlbOpnIBF+oqSZ90KNRw= Received: from mail-qk1-f200.google.com (mail-qk1-f200.google.com [209.85.222.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-661-Pn6ICFOuOH6V-UOxfV_UdQ-1; Wed, 03 Dec 2025 08:07:58 -0500 X-MC-Unique: Pn6ICFOuOH6V-UOxfV_UdQ-1 X-Mimecast-MFC-AGG-ID: Pn6ICFOuOH6V-UOxfV_UdQ_1764767278 Received: by mail-qk1-f200.google.com with SMTP id af79cd13be357-8b30b6abb7bso1280532985a.1 for ; Wed, 03 Dec 2025 05:07:58 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1764767278; x=1765372078; h=in-reply-to:content-language:from:references:cc:to:subject :user-agent:mime-version:date:message-id:x-gm-gg:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=ejyU8qrI7NbYDKLeKhaLjpI8ZbFCFgCr1UJY96Vf4RQ=; b=EZ0qE/BK7NygnDlWfy/yQNaTnjGhx08DE8cgjJsTuJI50KsTbQ7eLx2Qi83EoH5G8e oh7iXJAaxQikOgLQeI2hQqWY7sEvTD4rVVYoK5r85jTJZGV6cIKX0piloWXIRdJ5FSNS m2I57FyeTabHzEcZPZQVNaOKUKn4vQdF5vl/AIVI6kZ40Cmk5HILga5eLWBdZoDoN21t nVJaIofyFwCVB6cXM9MHyzPZBvhLOvab9hcWemA3l1Bf3C37wfKLGmj3kta8TACVPfdg 5NMaWw6iuXviuezIu1CI9qgOMEYBghG4OR3wI9lxsNYHG5eIkvp3r7aPR1ae6tAh5fu0 C7Eg== X-Gm-Message-State: AOJu0YxG4be+lYtccOVUmd66MNjYsPf1L0DeVYyMUTm3A7IXvyeJdBC1 st0E5vKGXz4fRzqxUsfsqYx5Oi/rpYTo+K9SRZKWrc69TtuNFogZGLbgxA2aPM06BH8vJxlDR4v trxvOo5zAArfXAYA8iFcTGSHOY03FfibwrUyxe0/ok+Z2SUx+89ZQH2fJ5CQW2eU= X-Gm-Gg: ASbGncvT8Ch1oKByZRR1ATDBIX03WXPyJUvMyjxtNfPM9GCGcGXNAT6Nzlk4dNlI9l+ y71mTvQptx63/basTNtDocbGQm5j2o71gmd05U7dFWuZCO/r+iDuKVXssCyuuJn8SoKwTyUYOlD CtOqS9RxP9LqbRWaoe75L2MOVZvJMjAVJ29IvKUqnFlLMUM2XOZJs6JfAMMKtswKbR5RAltjDaC ORfEeUoXPzMIH/kHJBpR4T+QaUm1hPG8FY2SCo36oO3WdcBgY/TOyHhgjspjcJB2OUEhLg4z5i/ pExajHX3ZcSLJePVgJ83xeGBYAsbGU4oBRKZnPtqLVvsX4sxgPTo7kMdeBO3OLkFpPEvcm92exr Bii1raQ9WPIY66XeeWXBYbg== X-Received: by 2002:a05:620a:46a9:b0:8b2:eae0:bc02 with SMTP id af79cd13be357-8b5e77339bfmr317276285a.88.1764767277774; Wed, 03 Dec 2025 05:07:57 -0800 (PST) X-Google-Smtp-Source: AGHT+IE3OXGagu9ZUGZICWLAG5j5zhQqyYy1ghrq+qvDyXsIYR0+J/i1Db3+jCwgSQHbQLMffJwKcA== X-Received: by 2002:a05:620a:46a9:b0:8b2:eae0:bc02 with SMTP id af79cd13be357-8b5e77339bfmr317266785a.88.1764767277100; Wed, 03 Dec 2025 05:07:57 -0800 (PST) Received: from ?IPV6:2804:14d:8084:9a69::1002? ([2804:14d:8084:9a69::1002]) by smtp.gmail.com with ESMTPSA id af79cd13be357-8b52a1b7da4sm1321569485a.34.2025.12.03.05.07.55 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 03 Dec 2025 05:07:56 -0800 (PST) Message-ID: Date: Wed, 3 Dec 2025 10:07:53 -0300 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH] gdb: add tutorial command To: Eli Zaretskii , Simon Marchi Cc: gdb-patches@sourceware.org References: <20251201170819.1573624-1-guinevere@redhat.com> <864iq93qyw.fsf@gnu.org> <867bv33fd1.fsf@gnu.org> From: Guinevere Larsen In-Reply-To: <867bv33fd1.fsf@gnu.org> X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: CqESo1Rvn7c5tym0pLsuzLVLptZFgabhueN-qXUE4c0_1764767278 X-Mimecast-Originator: redhat.com Content-Type: multipart/alternative; boundary="------------PpjNX73D0RyZ2bXx50t7IYmx" Content-Language: en-US X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces~public-inbox=simark.ca@sourceware.org This is a multi-part message in MIME format. --------------PpjNX73D0RyZ2bXx50t7IYmx Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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 >> >>> 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 --------------PpjNX73D0RyZ2bXx50t7IYmx Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 7bit
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
--------------PpjNX73D0RyZ2bXx50t7IYmx--