[PATCH 2/2] gdb/python: improve formatting of help text for user defined commands

[Carl Love]

Andrew:

On Sat, 2022-05-28 at 11:11 +0100, Andrew Burgess via Gdb-patches
wrote:
> Tom Tromey <tom@tromey.com> writes:
> 
> > > > > > > "Andrew" == Andrew Burgess via Gdb-patches <
> > > > > > > gdb-patches@sourceware.org> writes:
> > 
> > Andrew> Thanks to Eli and Lancelot for their feedback.
> > 
> > Andrew> In this revision I have:
> > Andrew>   - Updated the NEWS entry in line with Eli's feedback,
> > Andrew>   - Updated some comments that Lancelot identified as being
> > out of date,
> > Andrew>   - Added an additional comment into the test script to
> > justify some
> > Andrew>     'verbose -log' lines.
> > Andrew>   - There's no functional change to the code.
> > 
> > This looks ok to me, thank you.
> 
> Thanks, pushed.
> 
> Andrew
> 

I am seeing failures with the new test gdb/testsuite/gdb.python/py-doc-
reformat.exp on X86-64 and Power.  The errors show up in the full
regression run and when just this test is run.  When running just this
test I see in the gdb/testsuite/gdb.log file the following issues.

There are a couple of errors about "Undefined command "source
/home/...".  

Then later I see the a series of FAILS for numerous tests. 

   ....
   (gdb) set height 0
   (gdb) set width 0
   (gdb) dir
   Reinitialize source path to empty? (y or n) y
   Source directories searched: $cdir:$cwd
   (gdb) dir /home/carll/GDB/build-current/gdb/testsuite/../../../binutils-gdb-current/gdb/testsuite/gdb.python
   Source directories searched: /home/carll/GDB/build-current/gdb/testsuite/../../../binutils-gdb-current/gdb/testsuite/gdb.python:$cdir:$cwd
   (gdb) source /home/carll/GDB/build-current/gdb/testsuite/outputs/gdb.python/py-doc-reformat/py-doc-reformat-0.py
   /home/carll/GDB/build-current/gdb/testsuite/outputs/gdb.python/py-doc-reformat/py-doc-reformat-0.py:1: Error in sourced command file:
   Undefined command: "class".  Try "help".
   (gdb) ERROR: Undefined command "source /home/carll/GDB/build-current/gdb/testsuite/outputs/gdb.python/py-doc-reformat/py-doc-reformat-0.py".
   UNRESOLVED: gdb.python/py-doc-reformat.exp: test 0: source python command file
   help test-cmd
   Undefined command: "test-cmd".  Try "help".
   (gdb) ERROR: Undefined command "help test-cmd".
   UNRESOLVED: gdb.python/py-doc-reformat.exp: test 0: help test-cmd
   help set test-param
   Evaluate expression EXP and assign result to variable VAR.
   Usage: set VAR = EXP
   This uses assignment syntax appropriate for the current language
   (VAR = EXP or VAR := EXP for example).
   VAR may be a debugger "convenience" variable (names starting
   with $), a register (a few standard names starting with $), or an actual
   variable in the program being debugged.  EXP is any valid expression.
   Use "set variable" for variables with names identical to set subcommands.

   With a subcommand, this command modifies parts of the gdb environment.
   You can see these environment settings with the "show" command.

   List of set subcommands:

   set ada -- Prefix command for changing Ada-specific settings.
   ...
   set use-deprecated-index-sections -- Set whether to use deprecated gdb_index sections.
   set variable, set var -- Evaluate expression EXP and assign result to variable VAR.
   set verbose -- Set verbosity.
   set watchdog -- Set watchdog timer.
   set width -- Set number of characters where GDB should wrap lines of its output.
   set write -- Set writing into executable and core files.
   Type "help set" followed by set subcommand name for full documentation.
   Type "apropos word" to search for commands related to "word".
   Type "apropos -v word" for full documentation of commands related to "word".
   Command name abbreviations are allowed if unambiguous.
   (gdb) FAIL: gdb.python/py-doc-reformat.exp: test 1: help set test-param
   help show test-param
   Undefined show command: "test-param".  Try "help show".
   (gdb) FAIL: gdb.python/py-doc-reformat.exp: test 1: help show test-param
   Start of: test_cmd 2
   ...

Note, these two failures for test 1, repeat for each of the following
tests 10, 11, 12, 13, 14, 15, 16, 17, 18.

   ...

   Input:
     """
     This is the first line.
       Indented second line.
     This is the third line."""
   builtin_spawn /home/carll/bin/gdb -nw -nx -iex set height 0 -iex set width 0
   GNU gdb (GDB) 13.0.50.20220529-git
   ...
                  === gdb Summary ===

   # of unexpected failures        44
   # of unresolved testcases       44

Then final error count across all of the tests is 44.  

I tried doing the commands manually:

   (gdb)  help set test-param                                     <- this should be test 1, which in the regression
                                                                     run is listed as a failure but seemed to work
   	                                                          manually.  Wondering if there is an issue in
                                                                     the error reporting.
   Evaluate expression EXP and assign result to variable VAR.
   Usage: set VAR = EXP
   This uses assignment syntax appropriate for the current language
   (VAR = EXP or VAR := EXP for example).
   VAR may be a debugger "convenience" variable (names starting
   with $), a register (a few standard names starting with $), or an actual
   variable in the program being debugged.  EXP is any valid expression.
   Use "set variable" for variables with names identical to set subcommands.

   With a subcommand, this command modifies parts of the gdb environment.
   You can see these environment settings with the "show" command.

   List of set subcommands:

   set ada -- Prefix command for changing Ada-specific settings.
   set agent -- Set debugger's willingness to use agent as a helper.
   set annotate -- Set annotation_level.
   set architecture, set processor -- Set architecture of target.
   set args -- Set argument list to give program being debugged when it is started.
   set auto-connect-native-target -- Set whether GDB may automatically connect to the native target.
   set auto-load -- Auto-loading specific settings.
   set auto-solib-add -- Set autoloading of shared library symbols.
   set backtrace -- Set backtrace specific variables.
   set basenames-may-differ -- Set whether a source file may have multiple base names.
   set breakpoint -- Breakpoint specific settings.
   set can-use-hw-watchpoints -- Set debugger's willingness to use watchpoint hardware.
   set case-sensitive -- Set case sensitivity in name search (on/off/auto).
   set charset -- Set the host and target character sets.
   set check, set ch, set c -- Set the status of the type/range checker.
   set circular-trace-buffer -- Set target's use of circular trace buffer.
   set code-cache -- Set cache use for code segment access.
   set coerce-float-to-double -- Set coercion of floats to doubles when calling functions.
   set compile-args -- Set compile command GCC command-line arguments.
   set compile-gcc -- Set compile command GCC driver filename.
   set complaints -- Set max number of complaints about incorrect symbols.
   set confirm -- Set whether to confirm potentially dangerous operations.
   set cp-abi -- Set the ABI used for inspecting C++ objects.
   set cwd -- Set the current working directory to be used when the inferior is started.
   set data-directory -- Set GDB's data directory.
   set dcache -- Use this command to set number of lines in dcache and line-size.
   set debug -- Generic command for setting gdb debugging flags.
   set debug-file-directory -- Set the directories where separate debug symbols are searched for.
   set debuginfod -- Set debuginfod options.
   set default-collect -- Set the list of expressions to collect by default.
   set demangle-style -- Set the current C++ demangling style.
   set detach-on-fork -- Set whether gdb will detach the child of a fork.
   set directories -- Set the search path for finding source files.
   set disable-randomization -- Set disabling of debuggee's virtual address space randomization.
   set disassemble-next-line -- Set whether to disassemble next source line or insn when execution stops.
   --Type <RET> for more, q to quit, c to continue without paging--q
   Quit
   (gdb) help show test-param
   Undefined show command: "test-param".  Try "help show".                             <- failure

I haven't found any specific system setup errors to explain the fails. 
Please let me know if I can help further with these failures.  

                            Carl Love