From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id K5BNE9QbL2lL9hAAWB0awg (envelope-from ) for ; Tue, 02 Dec 2025 12:03:16 -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=BowpBOEs; dkim-atps=neutral Received: by simark.ca (Postfix, from userid 112) id 3C4FB1E0B3; Tue, 02 Dec 2025 12:03:16 -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,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 8E1781E08D for ; Tue, 02 Dec 2025 12:03:15 -0500 (EST) Received: from vm01.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 07A324BB58EB for ; Tue, 2 Dec 2025 17:03:15 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 07A324BB58EB 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=BowpBOEs 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 523DD4B9DB6A for ; Tue, 2 Dec 2025 17:02:49 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 523DD4B9DB6A 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 523DD4B9DB6A 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=1764694969; cv=none; b=CeNz+bgDPCUWDrmDit5slInFqGgefI5Nzj1+KdQkYib6nra8qO09VKsV0FLqdNLKq49DVv4V4YLBYTL6k7Va3sk7gvTsZlVKxPxnmb3xFRncXa9+dc+CDSlGVgidw1Xklo9oBiE96EF0iD1nzNeA2TgsWm2OU37q0QcuPgM8mhY= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1764694969; c=relaxed/simple; bh=E0o6IY2vgqEkM6VSMn+1+XryVvNCRuGAMOi6p5hSTCk=; h=DKIM-Signature:Message-ID:Date:MIME-Version:Subject:To:From; b=BxT2IUDuve+Dq2FCdLLxUrXttsryMsHlmQBVLRGIWXxbNHg1Mnt8+wZiYr8Ou3a48um5x4U9qULm+PaPo6qXYpe9UPSNAK+R6oanR7XxpIufG7as8wDHIRlxLduJTgbx9+lXwgLtYWUiHocEfN/vxhvm6MdD2wvpsQwysuGgjJ4= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 523DD4B9DB6A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1764694969; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jTmi0z80LzXNgd9OfBKvn7Ornw/v/rs4/fwZDsW+HFs=; b=BowpBOEsH6VGR2h0oo5PvrltNbkEo+AmJQx0PC59xHpjkEi1onIrlpJNOM/pXNzv0UWiLW 3+XNApRalsnAMVmBJ9WbjSsnbfAwhMsSq2ontsKqe/S+lkXhEb4hN7jKMIWh178SQ5CiDc ZEhDsnEbyL4Qu8wxL63uSpHnVSLP1T0= Received: from mail-qk1-f199.google.com (mail-qk1-f199.google.com [209.85.222.199]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-621-DPi-b-sXP8aWSQOieXTYcw-1; Tue, 02 Dec 2025 12:02:47 -0500 X-MC-Unique: DPi-b-sXP8aWSQOieXTYcw-1 X-Mimecast-MFC-AGG-ID: DPi-b-sXP8aWSQOieXTYcw_1764694967 Received: by mail-qk1-f199.google.com with SMTP id af79cd13be357-8b2e9b2608dso963668985a.3 for ; Tue, 02 Dec 2025 09:02:47 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1764694967; x=1765299767; h=content-transfer-encoding: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=jTmi0z80LzXNgd9OfBKvn7Ornw/v/rs4/fwZDsW+HFs=; b=LhnKkwu0tUuJ5B/qVPMtMfAvCSKox90RZffQQ8I3iRPa0WCgIYReH/l4ziYJB6VP8R h3/3T3sHCyy3ytvc7XIitPa0uABPg/6+Xl8pGq6NhlSkLupzp27odfAYeZQTKbm8wiHl +v9e1rzuWWpOuFCjF/ul3q2nqNMuVelM2BpcTJsgF64MQ9vCk+jTSXiepQaItrs/vrvy JUMYHwkIuWNXoanVVMh9C6L1LhZLI7CHaQhwRlQ4Z5Ctcx7hWBXWKR9yri5DFLF9av8h SIFo+WD27F3qmuFKcMrwVX7amD4Omde5lar5WcoYZ6ojgY9fHc3GB/q2yWHZGBErV2gx JsVw== X-Gm-Message-State: AOJu0Yx4X4xmHZB3kxZpOlQRrfCplRleP06yS8RImH8tylZndbIejtpS HeUkrukEQTWseJ2qm9zLP1tr6S4LogRPo/4Jq0HunmNm48Yp+H/Tf3X3qs2mmZQD7oQux407skZ fxe8wYCMu9dQVLr/p2gnEPe45kTGLuru2nU8kuEcBwoQN5hnm+2uaB7OvsVZ/6qU= X-Gm-Gg: ASbGncsksGjUqe22h4zHpOrnkOqePADhIvc5hRFk6mO3MLlhN2N8icc6R1cuKq6y/ZU bruLWnAtY/+DmQZgbQbpT5Nh8qc5h1dT08qFpCQF2DiK4PHgEc6CRDMn9gGtwXhrMk8NuVDkwSY IzYcSNrF8sO0NE/cBUE283Tz7XjKEWn15L5AerNT1Qh/UQiWa/eIskGyu3Ntc/w+KKANCkbLjLC U/5vHhrcHy/NyKpCzAfwye76ciULOjSxO0zHK0nNPBDM/LcRggWRzAuDQYCgDMZP/az0fDcREgu 4de7gALfxx1WuGCgCpr5yjTrLmv8fOGaa9vf79YTi4I9Il1p3aJYH7lgs4SccE8p1i7nXvdRo8M Yv9Rf7hdFzfWTLnSlcLvkyA== X-Received: by 2002:a05:620a:19a5:b0:8b2:db27:425f with SMTP id af79cd13be357-8b4ebdae8cbmr3963297285a.58.1764694966705; Tue, 02 Dec 2025 09:02:46 -0800 (PST) X-Google-Smtp-Source: AGHT+IGWuaGXBxl+uDE/NY5o+obktQbf1lNarMK4MADIJluXmX7rBZXhtFd5BHx/moa79W6qyZu0Ug== X-Received: by 2002:a05:620a:19a5:b0:8b2:db27:425f with SMTP id af79cd13be357-8b4ebdae8cbmr3963291985a.58.1764694966048; Tue, 02 Dec 2025 09:02:46 -0800 (PST) Received: from ?IPV6:2804:14d:8084:9a69::1000? ([2804:14d:8084:9a69::1000]) by smtp.gmail.com with ESMTPSA id af79cd13be357-8b52a1b6cdcsm1116520385a.32.2025.12.02.09.02.44 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 02 Dec 2025 09:02:45 -0800 (PST) Message-ID: <177b3d7c-f765-4e47-8def-f113487f9262@redhat.com> Date: Tue, 2 Dec 2025 14:02:42 -0300 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH] gdb: add tutorial command To: Eli Zaretskii Cc: gdb-patches@sourceware.org References: <20251201170819.1573624-1-guinevere@redhat.com> <864iq93qyw.fsf@gnu.org> From: Guinevere Larsen In-Reply-To: <864iq93qyw.fsf@gnu.org> X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: d8a1C8GE45s4GDRSb1FrnSxo4gG1gHDB4FoASMJnZ0E_1764694967 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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 On 12/2/25 11:20 AM, Eli Zaretskii wrote: >> From: Guinevere Larsen >> Cc: Guinevere Larsen >> 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 > -- Cheers, Guinevere Larsen It/she