[PATCH v2 0/2] Add warning if the native target is not supported

[PATCH v2 0/2] Add warning if the native target is not supported

[Guinevere Larsen]

Recently I was trying to conduct a new-user test, to figure out what
things were stumbling blocks, and one of the users had a macbook.  The
user on their own would not have been able to understand what was the
reason that they couldn't execute the inferior to debug it.

This series aims to make it a little more obvious, by warning the user
when GDB starts that there is no native target, and instructs the user
on how to get a list of supported architectures, to know what they'll be
able to remotely debug.

For v2, instead of adding a new command, this series changes the help
command, to make it print all available options if a command only
accepts specific options.

Guinevere Larsen (2):
  gdb: improve help text for set commands with limited options
  gdb: add warning when no native target is available

 gdb/cli/cli-decode.c | 10 ++++++++++
 gdb/main.c           |  5 +++++
 2 files changed, 15 insertions(+)


base-commit: 0a48989147868b4c5afdb0f5b90696b543768381
-- 
2.52.0

[PATCH v2 1/2] gdb: improve help text for set commands with limited options

[Guinevere Larsen]

Some "set" commands only allow a select few options, such as the "set
architecture" command, however, there is no way for a user to know which
options are allowed without trying to set something and getting an
error. This commit improves the situation by making the help command list
all the available options.
---
 gdb/cli/cli-decode.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
index 04935575b67..06313ba6c49 100644
--- a/gdb/cli/cli-decode.c
+++ b/gdb/cli/cli-decode.c
@@ -1884,6 +1884,16 @@ help_cmd (const char *command, struct ui_file *stream)
       /* Be sure to expand TABs in the documentation.  */
       tab_expansion_file expander (stream);
       gdb_puts (c->doc, &expander);
+      if (c->enums != nullptr)
+	{
+	  gdb_puts ("Available options are:\n", &expander);
+	  const char * const *opt = c->enums;
+	  while (opt != nullptr)
+	    {
+	      gdb_printf (&expander, "%s\n", *opt);
+	      opt ++;
+	    }
+	}
     }
   else
     {
-- 
2.52.0

Re: [PATCH v2 1/2] gdb: improve help text for set commands with limited options

[Andrew Burgess]

Guinevere Larsen <guinevere@redhat.com> writes:

> Some "set" commands only allow a select few options, such as the "set
> architecture" command, however, there is no way for a user to know which
> options are allowed without trying to set something and getting an
> error. This commit improves the situation by making the help command list
> all the available options.
> ---
>  gdb/cli/cli-decode.c | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c
> index 04935575b67..06313ba6c49 100644
> --- a/gdb/cli/cli-decode.c
> +++ b/gdb/cli/cli-decode.c
> @@ -1884,6 +1884,16 @@ help_cmd (const char *command, struct ui_file *stream)
>        /* Be sure to expand TABs in the documentation.  */
>        tab_expansion_file expander (stream);
>        gdb_puts (c->doc, &expander);
> +      if (c->enums != nullptr)
> +	{
> +	  gdb_puts ("Available options are:\n", &expander);
> +	  const char * const *opt = c->enums;
> +	  while (opt != nullptr)
> +	    {
> +	      gdb_printf (&expander, "%s\n", *opt);

Have you tried this on a build of GDB with all-targets enabled?  I
suspect this is going to result in rather a long list.  It might be
better if the options were printed as a comma separated list maybe?

Thanks,
Andrew


> +	      opt ++;
> +	    }
> +	}
>      }
>    else
>      {
> -- 
> 2.52.0

[PATCH v2 2/2] gdb: add warning when no native target is available

[Guinevere Larsen]

When a user starts GDB, they have no way of knowing if native debugging
will be supported or not.  This is most relevant for Mac users, since
GDB hasn't been ported to Apple's CPUs yet.

This patch adds a warning if, after initializing all files, GDB was
unable to find an appropriate native target for the session, informing
the user that they will only be able to debug remotely.
---
 gdb/main.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gdb/main.c b/gdb/main.c
index 296f59b0b57..132a2eb2048 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -1210,6 +1210,11 @@ captured_main_1 (struct captured_main_args *context)
   tmp_warn_preprint.reset ();
   warning_pre_print = "\n";
 
+  if (get_native_target () == nullptr)
+    warning (_("No native target, only remote debugging is supported.\n"
+	       "Use \"%ps\" to check which architectures are supported."),
+	    styled_string (command_style.style (), "help set architecture"));
+
   /* Read and execute the system-wide gdbinit file, if it exists.
      This is done *before* all the command line arguments are
      processed; it sets global parameters, which are independent of
-- 
2.52.0

RE: [PATCH v2 2/2] gdb: add warning when no native target is available

[Ciaran Woodward]

> -----Original Message-----
> From: Guinevere Larsen <guinevere@redhat.com>
> 
> When a user starts GDB, they have no way of knowing if native debugging
> will be supported or not.  This is most relevant for Mac users, since
> GDB hasn't been ported to Apple's CPUs yet.
> 
> This patch adds a warning if, after initializing all files, GDB was
> unable to find an appropriate native target for the session, informing
> the user that they will only be able to debug remotely.

Thanks for continuing to focus on usability :)

I thought I would add my perspective as a primarily embedded developer. Most
of the GDBs I use are "cross GDBs", for debugging embedded targets that
can't run GDB themselves. These get configured by having a different HOST
and TARGET in the build config, and I tend to think that usually its quite
clear that you're using one instead of your system GDB.

I think for such debuggers, it would be good to have this warning suppressed,
since users usually obtain it as part of a tool suite for that same platform,
so wouldn't be expected to get reminded that they can't use it to debug host
programs.

Thanks,
Ciaran

Re: [PATCH v2 2/2] gdb: add warning when no native target is available

[Guinevere Larsen]

On 1/9/26 9:36 AM, Ciaran Woodward wrote:
>> -----Original Message-----
>> From: Guinevere Larsen <guinevere@redhat.com>
>>
>> When a user starts GDB, they have no way of knowing if native debugging
>> will be supported or not.  This is most relevant for Mac users, since
>> GDB hasn't been ported to Apple's CPUs yet.
>>
>> This patch adds a warning if, after initializing all files, GDB was
>> unable to find an appropriate native target for the session, informing
>> the user that they will only be able to debug remotely.
> Thanks for continuing to focus on usability :)
>
> I thought I would add my perspective as a primarily embedded developer. Most
> of the GDBs I use are "cross GDBs", for debugging embedded targets that
> can't run GDB themselves. These get configured by having a different HOST
> and TARGET in the build config, and I tend to think that usually its quite
> clear that you're using one instead of your system GDB.
>
> I think for such debuggers, it would be good to have this warning suppressed,
> since users usually obtain it as part of a tool suite for that same platform,
> so wouldn't be expected to get reminded that they can't use it to debug host
> programs.
>
> Thanks,
> Ciaran
>
Hmmm, that's a good point. I think I can add a switch to this, to be 
added to the gdbinit (or maybe gdbearlyinit), will cook a v3 in a moment.

-- 
Cheers,
Guinevere Larsen
It/she

RE: [PATCH v2 2/2] gdb: add warning when no native target is available

[Ciaran Woodward]

> Hmmm, that's a good point. I think I can add a switch to this, to be
> added to the gdbinit (or maybe gdbearlyinit), will cook a v3 in a moment.

Would you object to making it configure-time, or would that break your
intended use case?

Thanks,
Ciaran

Re: [PATCH v2 2/2] gdb: add warning when no native target is available

[Guinevere Larsen]

On 1/9/26 11:16 AM, Ciaran Woodward wrote:
>> Hmmm, that's a good point. I think I can add a switch to this, to be
>> added to the gdbinit (or maybe gdbearlyinit), will cook a v3 in a moment.
> Would you object to making it configure-time, or would that break your
> intended use case?

I think making it configure-time would essentially render this change 
useless

I can't imagine anyone distributing GDB without native support where the 
distributor doesn't do it on purpose, so from their PoV it makes sense 
to disable the warning. However, a user in a Mac using M-series CPUs 
might not recognize or understand what they're reading, so this warning 
would be important but disabled for them.

What I'm thinking is making -q suppress this warning, would that be 
enough for you?

>
> Thanks,
> Ciaran
>

-- 
Cheers,
Guinevere Larsen
It/she

RE: [PATCH v2 2/2] gdb: add warning when no native target is available

[Ciaran Woodward]

> I think making it configure-time would essentially render this change
> useless
> 
> I can't imagine anyone distributing GDB without native support where the
> distributor doesn't do it on purpose, so from their PoV it makes sense
> to disable the warning. However, a user in a Mac using M-series CPUs
> might not recognize or understand what they're reading, so this warning
> would be important but disabled for them.

To me this sounds like there will be many people who would get frustrated
to have the extra text then - if they are going to look for ways to disable
it.

My other experience is that new users don't necessarily read the intro blurb
that much.

> What I'm thinking is making -q suppress this warning, would that be
> enough for you?

If you do end up merging this change, I think that would be required, yes.
Although personally I still don't think this will be a helpful message
for many of the people that will see it.

What about moving the warning to the place that the user makes the error?

i.e. when they try to attach to/start a native program. it provides some of
this information.

That would be useful to everyone, and users are also more motivated to read
just after something has failed to work. Right now I get "Don't know how to
run. try help target", which is not as helpful as your new text imo.

Cheers,
Ciaran

Re: [PATCH v2 2/2] gdb: add warning when no native target is available

[Andrew Burgess]

Guinevere Larsen <guinevere@redhat.com> writes:

> On 1/9/26 11:16 AM, Ciaran Woodward wrote:
>>> Hmmm, that's a good point. I think I can add a switch to this, to be
>>> added to the gdbinit (or maybe gdbearlyinit), will cook a v3 in a moment.
>> Would you object to making it configure-time, or would that break your
>> intended use case?

Currently, if a user tries to 'run' when there's no native target
support, GDB gives an error like:

  Don't know how to run.  Try "help target".

Would your new text be better emitted around the time this error is
produced?  The actual output of 'help target' is pretty unhelpful for a
confused user I think, it's mostly just a list of the various target
sub-commands.  But there is some introductory text at the top, maybe we
could do something smart and inject your new warning there for GDB's
without a native target?

Both of these would defer the additional text to the point where the
user has tried to do the wrong thing, at which point, printing more text
is OK.

Just a thought.

Thanks,
Andrew

Re: [PATCH v2 2/2] gdb: add warning when no native target is available

[Guinevere Larsen]

On 1/12/26 12:33 PM, Andrew Burgess wrote:
> Guinevere Larsen <guinevere@redhat.com> writes:
>
>> On 1/9/26 11:16 AM, Ciaran Woodward wrote:
>>>> Hmmm, that's a good point. I think I can add a switch to this, to be
>>>> added to the gdbinit (or maybe gdbearlyinit), will cook a v3 in a moment.
>>> Would you object to making it configure-time, or would that break your
>>> intended use case?
> Currently, if a user tries to 'run' when there's no native target
> support, GDB gives an error like:
>
>    Don't know how to run.  Try "help target".
>
> Would your new text be better emitted around the time this error is
> produced?  The actual output of 'help target' is pretty unhelpful for a
> confused user I think, it's mostly just a list of the various target
> sub-commands.  But there is some introductory text at the top, maybe we
> could do something smart and inject your new warning there for GDB's
> without a native target?
>
> Both of these would defer the additional text to the point where the
> user has tried to do the wrong thing, at which point, printing more text
> is OK.

Yeah, that was Ciaran's latest feedback, and I think this is a good idea 
(setting the warning when "Don't know how to run")

I don't necessarily think there's much to be gained by injecting the 
warning in the "help target" message, but I think "help target native" 
could be much more informative, and since the "don't know how to run" 
message explicitly looks for a native target, the hint could be more 
specific as well.

I'll look into this for v3

-- 
Cheers,
Guinevere Larsen
It/she

>
> Just a thought.
>
> Thanks,
> Andrew
>