Re: [PATCH v2] Add gstack script

[Eli Zaretskii <eliz@gnu.org>]

> From: Keith Seitz <keiths@redhat.com>
> Date: Thu, 12 Dec 2024 13:07:41 -0800
> 
> --- Changes in v2
> - Review feedback from Andrew Burgess
>   o Don't chmod gstack.in in configure.ac.
>   o Fix testsuite issues which could mislead users into thinking
>     that tests succeeded when they did not.
> ---

Thanks.

> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -62,6 +62,9 @@
>  * Support for process record/replay and reverse debugging on loongarch*-linux*
>    targets has been added.
>  
> +* Newly installed $prefix/bin/gstack uses GDB to print stack traces of
> +  running processes.

This is okay, but please say that gstack is a Bash shell script.

Also, what did you want to say by the "newly installed" part?

> +@node gstack man
> +@heading gstack
> +
> +@c man title gstack Print a stack trace of a running program
> +
> +@format
> +@c man begin SYNOPSIS gstack
> +gstack [-h | --help] [-v | --version] @var{pid}
> +@c man end
> +@end format
> +
> +@c man begin DESCRIPTION gstack
> +Print a stack trace of a running program with process ID @var{pid}.  If the process
> +is multi-threaded, @command{gstack} outputs backtraces for every thread which exists
> +in the process.
> +@c man end
> +
> +@c man begin OPTIONS gstack
> +@table @env
> +@item --help
> +@itemx -h
> +List all options, with brief explanations.
> +
> +@item --version
> +@itemx -v
> +Print version information and then exit.
> +@end table
> +@c man end
> +
> +@c man begin SEEALSO gstack
> +@ifset man
> +The full documentation for @value{GDBN} is maintained as a Texinfo manual.
> +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
> +documentation are properly installed at your site, the command
> +
> +@smallexample
> +info gdb
> +@end smallexample
> +
> +@noindent
> +should give you access to the complete manual.
> +
> +@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
> +Richard M. Stallman and Roland H. Pesch, July 1991.
> +@end ifset
> +@c man end

Is that all we want to tell in the manual about the script?  Even for
a man page this is quite terse.  Can we expand on this some more?  At
the very least I think we should tell that the script invokes G|DB to
attach to the program and produce the backtraces, then detaches from
the program.  Also, perhaps tell what happens if PID identifies a
non-existent process?

> +awk -- "$awk_script"

What if the system has only gawk or nawk or mawk?  Should the literal
"awk" be a variable?

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