From 92e4e97a9f569bf23b0f74479f32280c1f24cc6b Mon Sep 17 00:00:00 2001 From: Andrew Burgess Date: Fri, 25 Sep 2020 16:28:05 +0100 Subject: gdb: process early initialization files and command line options Adds the ability to process commands at a new phase during GDB's startup. This phase is earlier than the current initialisation file processing, before GDB has produced any output. The number of commands that can be processed at this early stage will be limited, and it is expected that the only commands that would be processed at this stage will relate to some of the fundamentals of how GDB starts up. Currently the only commands that it makes sense to add to this early initialization file are those like 'set style version ....' as the version string is displayed during startup before the standard initialization files are parsed. As such this commit fully resolved bug cli/25956. This commit adds a mechanism to execute these early initialization files from a users HOME directory, as well as some corresponding command line flags for GDB. The early initialization files that GDB will currently check for are ~/.config/gdb/gdbearlyinit (on Linux like systems) or ~/.gdbearlyinit if the former is not found. The output of 'gdb --help' has been extended to include a list of the early initialization files being processed. gdb/ChangeLog: PR cli/25956 * NEWS: Mention new early init files and command line options. * config.in: Regenerate. * configure: Regenerate. * configure.ac: Define GDBEARLYINIT. * main.c (get_earlyinit_files): New function. (enum cmdarg_kind): Add CMDARG_EARLYINIT_FILE and CMDARG_EARLYINIT_COMMAND. (captured_main_1): Add support for new command line flags, and for processing startup files. (print_gdb_help): Include startup files in the output. gdb/doc/ChangeLog: PR cli/25956 * gdb.texinfo (File Options): Mention new command line options. (Startup): Discuss when early init files are processed. (Initialization Files): Add description of early init files. (Output Styling): Update description of 'version' style. (gdb man): Mention early init files. gdb/testsuite/ChangeLog: PR cli/25956 * gdb.base/early-init-file.c: New file. * gdb.base/early-init-file.exp: New file. * lib/gdb-utils.exp (style): Handle style 'none'. --- gdb/doc/ChangeLog | 9 ++++ gdb/doc/gdb.texinfo | 121 +++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 120 insertions(+), 10 deletions(-) (limited to 'gdb/doc') diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 2482c54..b27bd18 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,12 @@ +2021-04-15 Andrew Burgess + + PR cli/25956 + * gdb.texinfo (File Options): Mention new command line options. + (Startup): Discuss when early init files are processed. + (Initialization Files): Add description of early init files. + (Output Styling): Update description of 'version' style. + (gdb man): Mention early init files. + 2021-04-14 Andrew Burgess * gdb.texinfo (GDB/MI Miscellaneous Commands): Add missing diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 51e1c64..4351378 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1040,6 +1040,20 @@ Execute a single @value{GDBN} command before loading the inferior (but after loading gdbinit files). @xref{Startup}. +@item -early-init-command @var{file} +@itemx -eix @var{file} +@cindex @code{--early-init-command} +@cindex @code{-eix} +Execute commands from @var{file} very early in the initialization +process, before any output is produced. @xref{Startup}. + +@item -early-init-eval-command @var{command} +@itemx -eiex @var{command} +@cindex @code{--early-init-eval-command} +@cindex @code{-eiex} +Execute a single @value{GDBN} command very early in the initialization +process, before any output is produced. + @item -directory @var{directory} @itemx -d @var{directory} @cindex @code{--directory} @@ -1291,6 +1305,23 @@ important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}). Here's the description of what @value{GDBN} does during session startup: @enumerate + +@item +Performs minimal setup required to initialize basic internal state. + +@item +@cindex early initialization file +Reads commands from the early initialization file (if any) in your +home directory. Only a restricted set of commands can be placed into +an early initialization file, see @ref{Initialization Files}, for +details. + +@item +Executes commands and command files specified by the @samp{-eiex} and +@samp{-eix} command line options in their specified order. Only a +restricted set of commands can be used with @samp{-eiex} and +@samp{eix}, see @ref{Initialization Files}, for details. + @item Sets up the command interpreter as specified by the command line (@pxref{Mode Options, interpreter}). @@ -1367,13 +1398,82 @@ To display the list of initialization files loaded by @value{GDBN} at startup, in the order they will be loaded, you can use @kbd{gdb --help}. +@cindex early initialization +The @dfn{early initialization} file is loaded very early in +@value{GDBN}'s initialization process, before the interpreter +(@pxref{Interpreters}) has been initialized, and before the default +target (@pxref{Targets}) is initialized. Only @code{set} or +@code{source} commands should be placed into an early initialization +file, and the only @code{set} commands that can be used are those that +control how @value{GDBN} starts up. + +Commands that can be placed into an early initialization file will be +documented as such throughout this manual. Any command that is not +documented as being suitable for an early initialization file should +instead be placed into a general initialization file. Command files +passed to @code{--early-init-command} or @code{-eix} are also early +initialization files, with the same command restrictions. Only +commands that can appear in an early initialization file should be +passed to @code{--early-init-eval-command} or @code{-eiex}. + +@cindex general initialization +In contrast, the @dfn{general initialization} files are processed +later, after @value{GDBN} has finished its own internal initialization +process, any valid command can be used in these files. + +@cindex initialization file +Throughout the rest of this document the term @dfn{initialization +file} refers to one of the general initialization files, not the early +initialization file. Any discussion of the early initialization file +will specifically mention that it is the early initialization file +being discussed. + As the system wide and home directory initialization files are processed before most command line options, changes to settings (e.g. @samp{set complaints}) can affect subsequent processing of command line options and operands. -The following sections describe where @value{GDBN} looks for the -initialization and the order that the files are searched for. +The following sections describe where @value{GDBN} looks for the early +initialization and initialization files, and the order that the files +are searched for. + +@subsubsection Home directory early initialization files + +@value{GDBN} initially looks for an early initialization file in the +users home directory@footnote{On DOS/Windows systems, the home +directory is the one pointed to by the @code{HOME} environment +variable.}. There are a number of locations that @value{GDBN} will +search in the home directory, these locations are searched in order +and @value{GDBN} will load the first file that it finds, and +subsequent locations will not be checked. + +On non-macOS hosts the locations searched are: +@itemize +@item +The file @file{gdb/gdbearlyinit} within the directory pointed to by the +environment variable @env{XDG_CONFIG_HOME}, if it is defined. +@item +The file @file{.config/gdb/gdbearlyinit} within the directory pointed to +by the environment variable @env{HOME}, if it is defined. +@item +The file @file{.gdbearlyinit} within the directory pointed to by the +environment variable @env{HOME}, if it is defined. +@end itemize + +By contrast, on macOS hosts the locations searched are: +@itemize +@item +The file @file{Library/Preferences/gdb/gdbearlyinit} within the +directory pointed to by the environment variable @env{HOME}, if it is +defined. +@item +The file @file{.gdbearlyinit} within the directory pointed to by the +environment variable @env{HOME}, if it is defined. +@end itemize + +It is possible to prevent the home directory early initialization file +from being loaded using the @samp{-nx} or @samp{-nh} command line +options, @pxref{Mode Options,,Choosing Modes}. @anchor{System Wide Init Files} @subsubsection System wide initialization files @@ -25954,11 +26054,10 @@ default, this style's foreground color is magenta and it has bold intensity. The version number is displayed in two places, the output of @command{show version}, and when @value{GDBN} starts up. -Currently the version string displayed at startup is printed before -@value{GDBN} has parsed any command line options, or parsed any -command files, so there is currently no way to control the styling of -this string. However, @value{GDBN}'s @code{--quiet} command line option -can be used to disable printing of the version string on startup. +In order to control how @value{GDBN} styles the version number at +startup, add the @code{set style version} family of commands to the +early initialization command file (@pxref{Initialization +Files}). @item title Control the styling of titles. These are managed with the @@ -46877,12 +46976,14 @@ Execute given @value{GDBN} @var{command}. Add @var{directory} to the path to search for source files. @item -nh -Do not execute commands from @file{~/.config/gdb/gdbinit} or -@file{~/.gdbinit}. +Do not execute commands from @file{~/.config/gdb/gdbinit}, +@file{~/.gdbinit}, @file{~/.config/gdb/gdbearlyinit}, or +@file{~/.gdbearlyinit} @item -nx @itemx -n -Do not execute commands from any @file{.gdbinit} initialization files. +Do not execute commands from any @file{.gdbinit} or +@file{.gdbearlyinit} initialization files. @item -quiet @itemx -q -- cgit v1.1