[PATCH] gdb: Make startup message more user friendly

Guinevere Larsen
2025-09-15T16:40:07Z

Currently, on startup, GDB prints a lot of licensing information and
then a few hints for new users. While there is an attempt to separate
the hints from the rest of the text, my user testing showed that it is
not good enough, and most unfamiliar users will just skip the
information. Especially considering that the documentation link happens
before the separation.

This commit attempts to make the startup message more friendly to new
users by using ascii art separators. If there is enough space availabe,
an ascii art box is printed containing the hints, otherwise a simple
separator is printed. The code deems "enough space available" when
there is enough space to print the documentation URL inside the box,
since the other hints will be broken into multiple lines if necessary.
Here are examples of the 2 possible startups, with enough space:

+-----------------------------------------------------------------+
| Find the GDB manual online at: |
| http://www.gnu.org/software/gdb/documentation/ |
| For help, type "help". |
| Type "apropos <word>" to search for commands related to "word". |
+-----------------------------------------------------------------+

And with limited space:

---------------------------------------------
Find the GDB manual documentation resources o
nline at:
<http://www.gnu.org/software/gdb/document
ation/>.
For help, type "help".
Type "apropos word" to search for commands re
lated to "word".

Unfortunately, I was not able to think of a way in which the code could
break a line if necessary and also include styled code for URLs and
commands, so, since I believe it is more important to have the box as
available as possible, I opted to not include any styling options.
---
gdb/main.c | 2 ++
gdb/top.c | 86 +++++++++++++++++++++++++++++++++++++++++++++++-------
gdb/top.h | 4 +++
3 files changed, 81 insertions(+), 11 deletions(-)

diff --git a/gdb/main.c b/gdb/main.c
index e1ef537c357..114b918bb39 100644
--- a/gdb/main.c
+++ b/gdb/main.c
@@ -1163,6 +1163,8 @@ captured_main_1 (struct captured_main_args *context)
/* Print all the junk at the top, with trailing "..." if we are
about to read a symbol file (possibly slowly). */
print_gdb_version (gdb_stdout, true);
+ gdb_printf ("\n");
+ print_gdb_hints (gdb_stdout);
if (symarg)
gdb_printf ("..");
gdb_printf ("\n");
diff --git a/gdb/top.c b/gdb/top.c
index f5b9fdc3034..81ac6476d9b 100644
--- a/gdb/top.c
+++ b/gdb/top.c
@@ -1357,17 +1357,81 @@ There is NO WARRANTY, to the extent permitted by law.",
styled_string (file_name_style.style (),
REPORT_BUGS_TO));
}
- gdb_printf (stream,
- _("Find the GDB manual and other documentation \
-resources online at:\n <%ps>."),
- styled_string (file_name_style.style (),
- "http://www.gnu.org/software/gdb/documentation/"));
- gdb_printf (stream, "\n\n");
- gdb_printf (stream, _("For help, type \"%ps\".\n"),
- styled_string (command_style.style (), "help"));
- gdb_printf (stream,
- _("Type \"%ps\" to search for commands related to \"word\"."),
- styled_string (command_style.style (), "apropos word"));
+}
+
+/* Print MESSAGE to STREAM in lines of maximum size WIDTH, so that it fits
+ in an ascii art box of width WIDTH+4. Messages may be broken on
+ spaces. */
+static void
+box_one_message (ui_file *stream, std::string message, int width)
+{
+ while (!message.empty ())
+ {
+ std::string line;
+ if (message.length () > width)
+ {
+ line = message.substr (0, message.rfind (" ", width));
+ message = message.substr (line.length ());
+ }
+ else
+ {
+ line = message;
+ message = "";
+ }
+
+ if (line.length () < width)
+ line.append (width - line.length (), ' ');
+
+ gdb_printf (stream, "| %s |\n", line.c_str ());
+ }
+}
+
+/* Print some hints about how to use GDB in a very visible manner. */
+void
+print_gdb_hints (struct ui_file *stream)
+{
+ int width = get_chars_per_line ();
+
+ /* Arbitrarily setting maximum width to 80 characters, so that
+ things are big and visible but not overwhelming. */
+ if (80 < width)
+ width = 80;
+
+ std::string docs_url = "http://www.gnu.org/software/gdb/documentation/";
+ /* If there isn't enough space to display the longest URL in a boxed
+ style, use the simple styling of a singular visual break. The longest
+ URL is used because the other messages may be broken into multiple
+ lines, but URLs can't. */
+ if (width - 3 <= docs_url.length ())
+ {
+ std::string sep (width, '-');
+ gdb_printf (stream, "%s\n", sep.c_str ());
+ gdb_printf (stream,
+ _("Find the GDB manual documentation resources online at:\
+\n <%ps>.\n"),
+ styled_string (file_name_style.style (), docs_url.c_str ()));
+ gdb_printf (stream, _("For help, type \"%ps\".\n"),
+ styled_string (command_style.style (), "help"));
+ gdb_printf (stream,
+ _("Type \"%ps\" to search for commands related to \"word\"."),
+ styled_string (command_style.style (), "apropos word"));
+ return;
+ }
+ else
+ {
+ std::string sep (width-2, '-');
+ /* Account for opening and closing of the box. */
+ width -= 4;
+
+ gdb_printf (stream, "+%s+\n", sep.c_str ());
+ box_one_message (stream, "Find the GDB manual online at:", width);
+ box_one_message (stream, docs_url.c_str (), width);
+ box_one_message (stream, "For help, type \"help\".", width);
+ box_one_message (stream, "Type \"apropos <word>\" to search for"
+ " commands related to \"word\".",
+ width);
+ gdb_printf (stream, "+%s+\n", sep.c_str ());
+ }
}

/* Print the details of GDB build-time configuration. */
diff --git a/gdb/top.h b/gdb/top.h
index 41af51acecf..f90515ea740 100644
--- a/gdb/top.h
+++ b/gdb/top.h
@@ -36,6 +36,10 @@ extern auto_boolean interactive_mode;
mentioned. */
extern void print_gdb_version (struct ui_file *stream, bool interactive);

+/* Print some hints for an inexperienced user on how to get more
+ information about using GDB. */
+extern void print_gdb_hints (struct ui_file *stream);
+
extern void print_gdb_configuration (struct ui_file *);

extern void read_command_file (FILE *);

base-commit: 84c1e5cec0ec7d80d460db2b823d329e9759c642
--
2.51.0