forked from Imagelibrary/binutils-gdb
effcf7b144
Compared to the previous version, this version fixes the comments reported by
Tom Tromey and ensures that the 'help some-user-documented-alias'
shows the alias definition to ensure the user understands this is an
alias even if specifically documented.
When using 'help ALIASNAME', GDB shows the help of the aliased command.
This is a good default behaviour.
However, GDB alias command allows to define aliases with arguments
possibly changing or tuning significantly the behaviour of
the aliased command. In such a case, showing the help of the aliased
command might not be ideal.
This is particularly true when defining an alias as a set of
nested 'with' followed by a last command to launch, such as:
(gdb) alias pp10 = with print pretty -- with print elements 10 -- print
Asking 'help pp10' shows the help of the 'with' command, which is
not particularly useful:
(gdb) help pp10
with, pp10, w
alias pp10 = with print pretty -- with print elements 10 -- print
Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
Usage: with SETTING [VALUE] [-- COMMAND]
....
Such an alias can now be documented by the user:
(gdb) document pp10
>Pretty printing an expressiong, printing 10 elements.
>Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
>See 'help print' for more information.
>end
(gdb) help pp10
alias pp10 = with print pretty -- with print elements 10 -- print
Pretty printing an expressiong, printing 10 elements.
Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
See 'help print' for more information.
(gdb)
When a user-defined alias is documented specifically, help and apropos
use the provided alias documentation instead of the documentation of
the aliased command.
Such a documented alias is also not shown anymore in the help of the
aliased command, and the alias is not listed anymore in the help
of the aliased command. In particular for cases such as pp10 example above,
indicating that pp10 is an alias of the 'with' command is confusing.
176 lines
8.4 KiB
Plaintext
176 lines
8.4 KiB
Plaintext
# Copyright 1988-2022 Free Software Foundation, Inc.
|
|
|
|
# This program is free software; you can redistribute it and/or modify
|
|
# it under the terms of the GNU General Public License as published by
|
|
# the Free Software Foundation; either version 3 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
# This file was written by Rob Savoye. (rob@cygnus.com)
|
|
|
|
# Test basic help functionality.
|
|
# This is not intended to test the help text of every command,
|
|
# or even more than a few commands - too much of a maintenance burden.
|
|
|
|
gdb_start
|
|
|
|
# Disable pagination.
|
|
gdb_test_no_output "set height 0" "disable pagination"
|
|
|
|
# Test all the help classes.
|
|
test_class_help "aliases" {"User-defined aliases of other commands\.\[\r\n\]+"}
|
|
test_class_help "breakpoints" {
|
|
"Making program stop at certain points\.\[\r\n\]+"
|
|
}
|
|
with_read1_timeout_factor 10 {
|
|
test_class_help "data" {"Examining data\.\[\r\n\]+"}
|
|
test_class_help "files" {"Specifying and examining files\.\[\r\n\]+"}
|
|
test_class_help "internals" {
|
|
"Maintenance commands\.\[\r\n\]+"
|
|
"Some gdb commands are provided just for use by gdb maintainers\.\[\r\n\]+"
|
|
"These commands are subject to frequent change, and may not be as\[\r\n\]+"
|
|
"well documented as user commands\.\[\r\n\]+"
|
|
}
|
|
}
|
|
test_class_help "obscure" {"Obscure features\.\[\r\n\]+"}
|
|
test_class_help "running" {"Running the program\.\[\r\n\]+"}
|
|
test_class_help "stack" {
|
|
"Examining the stack\..*\[\r\n\]+"
|
|
"When the program being debugged stops, gdb selects the innermost frame\.\[\r\n\]+"
|
|
"The commands below can be used to select other frames by number or address\.\[\r\n\]+"
|
|
}
|
|
with_read1_timeout_factor 10 {
|
|
test_class_help "status" {
|
|
"Status inquiries\.\[\r\n\]+"
|
|
}
|
|
test_class_help "support" {"Support facilities\.\[\r\n\]+"}
|
|
test_class_help "tracepoints" {
|
|
"Tracing of program execution without stopping the program\.\[\r\n\]+"
|
|
}
|
|
}
|
|
|
|
with_read1_timeout_factor 10 {
|
|
test_user_defined_class_help
|
|
|
|
# Test help of an abbreviated command. "break" is picked at random.
|
|
set help_breakpoint_text "Set breakpoint at specified location\..*"
|
|
# Test help breakpoint "b" abbreviation.
|
|
gdb_test "help b" $help_breakpoint_text "help breakpoint \"b\" abbreviation"
|
|
# Test help breakpoint "br" abbreviation.
|
|
gdb_test "help br" $help_breakpoint_text "help breakpoint \"br\" abbreviation"
|
|
# Test help breakpoint "bre" abbreviation;
|
|
gdb_test "help bre" $help_breakpoint_text "help breakpoint \"bre\" abbreviation"
|
|
# Test help breakpoint "brea" abbreviation.
|
|
}
|
|
gdb_test "help brea" $help_breakpoint_text "help breakpoint \"brea\" abbreviation"
|
|
# Test help breakpoint "break" abbreviation.
|
|
gdb_test "help break" $help_breakpoint_text "help breakpoint \"break\" abbreviation"
|
|
|
|
# Test help of an aliased command. "bt" is picked at random.
|
|
set help_backtrace_text "Print backtrace of all stack frames, or innermost COUNT frames\..*"
|
|
# Test help backtrace "bt" abbreviation.
|
|
gdb_test "help bt" $help_backtrace_text "help backtrace \"bt\" abbreviation"
|
|
# Test help backtrace.
|
|
gdb_test "help backtrace" $help_backtrace_text
|
|
|
|
# Test help commands.
|
|
gdb_test "help commands" "Set commands to be executed when the given breakpoints are hit\.\[\r\n\]+Give a space-separated breakpoint list as argument after \"commands\"\.\[\r\n\]+A list element can be a breakpoint number \\(e.g. `5'\\) or a range of numbers\[\r\n\]+\\(e.g. `5-7'\\)\.\[\r\n\]+With no argument, the targeted breakpoint is the last one set\.\[\r\n\]+The commands themselves follow starting on the next line\.\[\r\n\]+Type a line containing \"end\" to indicate the end of them\.\[\r\n\]+Give \"silent\" as the first line to make the breakpoint silent;\[\r\n\]+then no output is printed when it is hit, except what the commands print\."
|
|
|
|
# Test a prefix command. "delete" is picked at random.
|
|
# Test help delete "d" abbreviation.
|
|
set expected_help_delete {
|
|
"Delete all or some breakpoints\.\[\r\n\]+"
|
|
"Usage: delete \\\[BREAKPOINTNUM\\\]...\[\r\n\]+"
|
|
"Arguments are breakpoint numbers with spaces in between\.\[\r\n\]+"
|
|
"To delete all breakpoints, give no argument\.\[\r\n\]+"
|
|
"Also a prefix command for deletion of other GDB objects\.\[\r\n\]+"
|
|
}
|
|
test_prefix_command_help {"d" "delete"} $expected_help_delete "help delete \"d\" abbreviation"
|
|
# Test help delete.
|
|
test_prefix_command_help "delete" $expected_help_delete
|
|
|
|
# Make sure help for help itself is present.
|
|
# Test help help "h" abbreviation.
|
|
gdb_test "help h" "Print list of commands\." "help help \"h\" abbreviation"
|
|
# Test help help.
|
|
gdb_test "help help" "Print list of commands\."
|
|
|
|
# The startup banner refers to "show copying" and "show warranty",
|
|
# might as well test for them.
|
|
# Test help info copying.
|
|
gdb_test "help show copying" "Conditions for redistributing copies of GDB\."
|
|
# Test help info warranty.
|
|
gdb_test "help show warranty" "Various kinds of warranty you do not have\."
|
|
|
|
# Test a few other random "help show" commands.
|
|
# Test help show commands.
|
|
gdb_test "help show commands" "Show the history of commands you typed\.\[\r\n\]+You can supply a command number to start with, or a `\[+\]' to start after\[\r\n\]+the previous command number shown\."
|
|
# Test help show confirm.
|
|
gdb_test "help show confirm" "Show whether to confirm potentially dangerous operations\."
|
|
|
|
# Test help info bogus-gdb-command.
|
|
gdb_test "help info bogus-gdb-command" "Undefined info command: \"bogus-gdb-command\"\. Try \"help info\"\."
|
|
# Test help gotcha.
|
|
gdb_test "help gotcha" "Undefined command: \"gotcha\"\. Try \"help\"\."
|
|
|
|
# Test apropos regex.
|
|
gdb_test "apropos \\\(print\[\^\[ bsiedf\\\".-\]\\\)" "handle -- Specify how to handle signals\."
|
|
# Test apropos >1 word string.
|
|
gdb_test "apropos handle signal" "handle -- Specify how to handle signals\."
|
|
# Test apropos apropos.
|
|
gdb_test "apropos apropos" "apropos -- Search for commands matching a REGEXP.*"
|
|
|
|
# Test apropos for commands having aliases.
|
|
gdb_test_no_output "alias mybt = backtrace" "define mybt alias"
|
|
gdb_test_no_output "alias mybt10 = backtrace 10" "define mybt10 alias"
|
|
|
|
gdb_test "apropos Print backtrace of all stack frames, or innermost COUNT frames\." \
|
|
"backtrace, mybt10, mybt, where, bt -- Print backtrace of all stack frames, or innermost COUNT frames\.\[\r\n\]+ alias mybt10 = backtrace 10"
|
|
|
|
# Test help for commands having aliases.
|
|
gdb_test "help bt" "backtrace, mybt10, mybt, where, bt\[\r\n\]+ alias mybt10 = backtrace 10\[\r\n\]+Print backtrace of all stack frames, or innermost COUNT frames\..*"
|
|
|
|
# Document the aliases. The apropos and help commands should then consider them
|
|
# as "standalone" commands.
|
|
gdb_test_multiple "document mybt" "document alias: mybt" {
|
|
-re "Type documentation for \"mybt\".\r\nEnd with a line saying just \"end\".\r\n>$" {
|
|
gdb_test "An alias of command backtrace without any args.\nend" \
|
|
"" \
|
|
"document alias: mybt"
|
|
}
|
|
}
|
|
gdb_test_multiple "document mybt10" "document alias: mybt10" {
|
|
-re "Type documentation for \"mybt10\".\r\nEnd with a line saying just \"end\".\r\n>$" {
|
|
gdb_test "An alias of command backtrace with arg 10.\nend" \
|
|
"" \
|
|
"document alias: mybt10"
|
|
}
|
|
}
|
|
|
|
# As the aliases are now documented, they do not appear in apropos/help backtrace output anymore.
|
|
gdb_test "apropos Print backtrace of all stack frames, or innermost COUNT frames\." \
|
|
"backtrace, where, bt -- Print backtrace of all stack frames, or innermost COUNT frames\." \
|
|
"apropos after documenting aliases"
|
|
|
|
gdb_test "help bt" "backtrace, where, bt\[\r\n\]+Print backtrace of all stack frames, or innermost COUNT frames\..*" \
|
|
"help after documenting aliases"
|
|
|
|
# Check apropos and help use the alias documentation.
|
|
gdb_test "apropos An alias of command backtrace with arg 10" \
|
|
"mybt10 -- An alias of command backtrace with arg 10\." \
|
|
"apropos after documenting aliases showing mybt10 doc"
|
|
|
|
gdb_test "help mybt" " alias mybt = backtrace \[\r\n\]+An alias of command backtrace without any args\." \
|
|
"help mybt after documenting aliases showing mybt doc"
|
|
|
|
# Check pre-defined aliases cannot be documented.
|
|
gdb_test "document where" "Alias \"where\" is built-in.*" \
|
|
"documenting builtin where alias disallowed"
|