diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 14 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 521 |
2 files changed, 289 insertions, 246 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index e157df8..fcbf7cb 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,17 @@ +2013-12-23 Doug Evans <xdje42@gmail.com> + + * gdb.texinfo (Auto-loading): Move menu up. Move discussion of + auto-loaded objfile scripts and .debug_gdb_scripts section to their + corresponding section in Extending GDB. + (Extending GDB): Move menu up. New menu item "Auto-loading + extensions". + (Sequences): New menu item "Auto-loading sequences". + (Auto-loading sequences): New node. + (Python): Rename section from Scripting GDB to Extending GDB. + (Python Auto-loading): Update xref, refer to "Auto-loading extensions". + Move docs on ways to auto-load extensions to ... + (Auto-loading extensions): ... here. New node. + 2013-12-23 Joel Brobecker <brobecker@adacore.com> * gdb.texinfo (GDB/MI): Add "GDB/MI Support Commands" entry diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 29f1cfc..7560152 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -22150,6 +22150,18 @@ without being explicitly told so by the user. We call this feature results or introduce security risks (e.g., if the file comes from untrusted sources). +@menu +* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit} +* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db} + +* Auto-loading safe path:: @samp{set/show/info auto-load safe-path} +* Auto-loading verbose mode:: @samp{set/show debug auto-load} +@end menu + +There are various kinds of files @value{GDBN} can automatically load. +In addition to these files, @value{GDBN} supports auto-loading code written +in various extension languages. @xref{Auto-loading extensions}. + Note that loading of these associated files (including the local @file{.gdbinit} file) requires accordingly configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). @@ -22214,23 +22226,6 @@ Yes /home/user/gdb/gdb-gdb.py @end smallexample @end table -These are various kinds of files @value{GDBN} can automatically load: - -@itemize @bullet -@item -@xref{objfile-gdb.py file}, controlled by @ref{set auto-load python-scripts}. -@item -@xref{objfile-gdb.gdb file}, controlled by @ref{set auto-load gdb-scripts}. -@item -@xref{dotdebug_gdb_scripts section}, -controlled by @ref{set auto-load python-scripts}. -@item -@xref{Init File in the Current Directory}, -controlled by @ref{set auto-load local-gdbinit}. -@item -@xref{libthread_db.so.1 file}, controlled by @ref{set auto-load libthread-db}. -@end itemize - These are @value{GDBN} control commands for the auto-loading: @multitable @columnfractions .5 .5 @@ -22276,15 +22271,6 @@ These are @value{GDBN} control commands for the auto-loading: @tab Add directory trusted for automatic loading. @end multitable -@menu -* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit} -* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db} -* objfile-gdb.gdb file:: @samp{set/show/info auto-load gdb-script} -* Auto-loading safe path:: @samp{set/show/info auto-load safe-path} -* Auto-loading verbose mode:: @samp{set/show debug auto-load} -@xref{Python Auto-loading}. -@end menu - @node Init File in the Current Directory @subsection Automatically loading init file in the current directory @cindex auto-loading init file in the current directory @@ -22354,43 +22340,6 @@ Print the list of all loaded inferior specific thread debugging libraries and for each such library print list of inferior @var{pid}s using it. @end table -@node objfile-gdb.gdb file -@subsection The @file{@var{objfile}-gdb.gdb} file -@cindex auto-loading @file{@var{objfile}-gdb.gdb} - -@value{GDBN} tries to load an @file{@var{objfile}-gdb.gdb} file containing -canned sequences of commands (@pxref{Sequences}), as long as @samp{set -auto-load gdb-scripts} is set to @samp{on}. - -Note that loading of this script file also requires accordingly configured -@code{auto-load safe-path} (@pxref{Auto-loading safe path}). - -For more background refer to the similar Python scripts auto-loading -description (@pxref{objfile-gdb.py file}). - -@table @code -@anchor{set auto-load gdb-scripts} -@kindex set auto-load gdb-scripts -@item set auto-load gdb-scripts [on|off] -Enable or disable the auto-loading of canned sequences of commands scripts. - -@anchor{show auto-load gdb-scripts} -@kindex show auto-load gdb-scripts -@item show auto-load gdb-scripts -Show whether auto-loading of canned sequences of commands scripts is enabled or -disabled. - -@anchor{info auto-load gdb-scripts} -@kindex info auto-load gdb-scripts -@cindex print list of auto-loaded canned sequences of commands scripts -@item info auto-load gdb-scripts [@var{regexp}] -Print the list of all canned sequences of commands scripts that @value{GDBN} -auto-loaded. -@end table - -If @var{regexp} is supplied only canned sequences of commands scripts with -matching names are printed. - @node Auto-loading safe path @subsection Security restriction for auto-loading @cindex auto-loading safe-path @@ -22915,14 +22864,22 @@ Displays whether the debugger is operating in interactive mode or not. @chapter Extending @value{GDBN} @cindex extending GDB -@value{GDBN} provides three mechanisms for extension. The first is based -on composition of @value{GDBN} commands, the second is based on the -Python scripting language, and the third is for defining new aliases of -existing commands. +@value{GDBN} provides several mechanisms for extension. +@value{GDBN} also provides the ability to automatically load +extensions when it reads a file for debugging. This allows the +user to automatically customize @value{GDBN} for the program +being debugged. + +@menu +* Sequences:: Canned Sequences of @value{GDBN} Commands +* Python:: Extending @value{GDBN} using Python +* Auto-loading extensions:: Automatically loading extensions +* Aliases:: Creating new spellings of existing commands +@end menu -To facilitate the use of the first two extensions, @value{GDBN} is capable +To facilitate the use of extension languages, @value{GDBN} is capable of evaluating the contents of a file. When doing so, @value{GDBN} -can recognize which scripting language is being used by looking at +can recognize which extension language is being used by looking at the filename extension. Files with an unrecognized filename extension are always treated as a @value{GDBN} Command Files. @xref{Command Files,, Command files}. @@ -22952,12 +22909,6 @@ Display the current value of the @code{script-extension} option. @end table -@menu -* Sequences:: Canned Sequences of Commands -* Python:: Scripting @value{GDBN} using Python -* Aliases:: Creating new spellings of existing commands -@end menu - @node Sequences @section Canned Sequences of Commands @@ -22971,6 +22922,7 @@ files. * Hooks:: Hooks for user-defined commands * Command Files:: How to write scripts of commands to be stored in a file * Output:: Commands for controlled output +* Auto-loading sequences:: Controlling auto-loaded command files @end menu @node Define @@ -23456,12 +23408,47 @@ the string @var{template} to a command line, and call it. @end table +@node Auto-loading sequences +@subsection Controlling auto-loading native @value{GDBN} scripts +@cindex native script auto-loading + +When a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library), +@value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}. +@xref{Auto-loading extensions}. + +Auto-loading can be enabled or disabled, +and the list of auto-loaded scripts can be printed. + +@table @code +@anchor{set auto-load gdb-scripts} +@kindex set auto-load gdb-scripts +@item set auto-load gdb-scripts [on|off] +Enable or disable the auto-loading of canned sequences of commands scripts. + +@anchor{show auto-load gdb-scripts} +@kindex show auto-load gdb-scripts +@item show auto-load gdb-scripts +Show whether auto-loading of canned sequences of commands scripts is enabled or +disabled. + +@anchor{info auto-load gdb-scripts} +@kindex info auto-load gdb-scripts +@cindex print list of auto-loaded canned sequences of commands scripts +@item info auto-load gdb-scripts [@var{regexp}] +Print the list of all canned sequences of commands scripts that @value{GDBN} +auto-loaded. +@end table + +If @var{regexp} is supplied only canned sequences of commands scripts with +matching names are printed. + @node Python -@section Scripting @value{GDBN} using Python +@section Extending @value{GDBN} using Python @cindex python scripting @cindex scripting with python -You can script @value{GDBN} using the @uref{http://www.python.org/, +You can extend @value{GDBN} using the @uref{http://www.python.org/, Python programming language}. This feature is available only if @value{GDBN} was configured using @option{--with-python}. @@ -27627,9 +27614,8 @@ instruction in bytes. When a new object file is read (for example, due to the @code{file} command, or because the inferior has loaded a shared library), @value{GDBN} will look for Python support scripts in several ways: -@file{@var{objfile}-gdb.py} (@pxref{objfile-gdb.py file}) -and @code{.debug_gdb_scripts} section -(@pxref{dotdebug_gdb_scripts section}). +@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section. +@xref{Auto-loading extensions}. The auto-loading feature is useful for supplying application-specific debugging commands and scripts. @@ -27679,172 +27665,6 @@ When reading an auto-loaded file, @value{GDBN} sets the function (@pxref{Objfiles In Python}). This can be useful for registering objfile-specific pretty-printers and frame-filters. -@menu -* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file -* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section -* Which flavor to choose?:: -@end menu - -@node objfile-gdb.py file -@subsubsection The @file{@var{objfile}-gdb.py} file -@cindex @file{@var{objfile}-gdb.py} - -When a new object file is read, @value{GDBN} looks for -a file named @file{@var{objfile}-gdb.py} (we call it @var{script-name} below), -where @var{objfile} is the object file's real name, formed by ensuring -that the file name is absolute, following all symlinks, and resolving -@code{.} and @code{..} components. If this file exists and is -readable, @value{GDBN} will evaluate it as a Python script. - -If this file does not exist, then @value{GDBN} will look for -@var{script-name} file in all of the directories as specified below. - -Note that loading of this script file also requires accordingly configured -@code{auto-load safe-path} (@pxref{Auto-loading safe path}). - -For object files using @file{.exe} suffix @value{GDBN} tries to load first the -scripts normally according to its @file{.exe} filename. But if no scripts are -found @value{GDBN} also tries script filenames matching the object file without -its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it -is attempted on any platform. This makes the script filenames compatible -between Unix and MS-Windows hosts. - -@table @code -@anchor{set auto-load scripts-directory} -@kindex set auto-load scripts-directory -@item set auto-load scripts-directory @r{[}@var{directories}@r{]} -Control @value{GDBN} auto-loaded scripts location. Multiple directory entries -may be delimited by the host platform path separator in use -(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). - -Each entry here needs to be covered also by the security setting -@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). - -@anchor{with-auto-load-dir} -This variable defaults to @file{$debugdir:$datadir/auto-load}. The default -@code{set auto-load safe-path} value can be also overriden by @value{GDBN} -configuration option @option{--with-auto-load-dir}. - -Any reference to @file{$debugdir} will get replaced by -@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any -reference to @file{$datadir} will get replaced by @var{data-directory} which is -determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and -@file{$datadir} must be placed as a directory component --- either alone or -delimited by @file{/} or @file{\} directory separators, depending on the host -platform. - -The list of directories uses path separator (@samp{:} on GNU and Unix -systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly -to the @env{PATH} environment variable. - -@anchor{show auto-load scripts-directory} -@kindex show auto-load scripts-directory -@item show auto-load scripts-directory -Show @value{GDBN} auto-loaded scripts location. -@end table - -@value{GDBN} does not track which files it has already auto-loaded this way. -@value{GDBN} will load the associated script every time the corresponding -@var{objfile} is opened. -So your @file{-gdb.py} file should be careful to avoid errors if it -is evaluated more than once. - -@node dotdebug_gdb_scripts section -@subsubsection The @code{.debug_gdb_scripts} section -@cindex @code{.debug_gdb_scripts} section - -For systems using file formats like ELF and COFF, -when @value{GDBN} loads a new object file -it will look for a special section named @samp{.debug_gdb_scripts}. -If this section exists, its contents is a list of names of scripts to load. - -@value{GDBN} will look for each specified script file first in the -current directory and then along the source search path -(@pxref{Source Path, ,Specifying Source Directories}), -except that @file{$cdir} is not searched, since the compilation -directory is not relevant to scripts. - -Entries can be placed in section @code{.debug_gdb_scripts} with, -for example, this GCC macro: - -@example -/* Note: The "MS" section flags are to remove duplicates. */ -#define DEFINE_GDB_SCRIPT(script_name) \ - asm("\ -.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ -.byte 1\n\ -.asciz \"" script_name "\"\n\ -.popsection \n\ -"); -@end example - -@noindent -Then one can reference the macro in a header or source file like this: - -@example -DEFINE_GDB_SCRIPT ("my-app-scripts.py") -@end example - -The script name may include directories if desired. - -Note that loading of this script file also requires accordingly configured -@code{auto-load safe-path} (@pxref{Auto-loading safe path}). - -If the macro is put in a header, any application or library -using this header will get a reference to the specified script. - -@node Which flavor to choose? -@subsubsection Which flavor to choose? - -Given the multiple ways of auto-loading Python scripts, it might not always -be clear which one to choose. This section provides some guidance. - -Benefits of the @file{-gdb.py} way: - -@itemize @bullet -@item -Can be used with file formats that don't support multiple sections. - -@item -Ease of finding scripts for public libraries. - -Scripts specified in the @code{.debug_gdb_scripts} section are searched for -in the source search path. -For publicly installed libraries, e.g., @file{libstdc++}, there typically -isn't a source directory in which to find the script. - -@item -Doesn't require source code additions. -@end itemize - -Benefits of the @code{.debug_gdb_scripts} way: - -@itemize @bullet -@item -Works with static linking. - -Scripts for libraries done the @file{-gdb.py} way require an objfile to -trigger their loading. When an application is statically linked the only -objfile available is the executable, and it is cumbersome to attach all the -scripts from all the input libraries to the executable's @file{-gdb.py} script. - -@item -Works with classes that are entirely inlined. - -Some classes can be entirely inlined, and thus there may not be an associated -shared library to attach a @file{-gdb.py} script to. - -@item -Scripts needn't be copied out of the source tree. - -In some circumstances, apps can be built out of large collections of internal -libraries, and the build infrastructure necessary to install the -@file{-gdb.py} scripts in a place where @value{GDBN} can find them is -cumbersome. It may be easier to specify the scripts in the -@code{.debug_gdb_scripts} section as relative paths, and add a path to the -top of the source tree to the source search path. -@end itemize - @node Python modules @subsection Python modules @cindex python modules @@ -28048,6 +27868,215 @@ substitute_prompt (``frame: \f, @end smallexample @end table +@node Auto-loading extensions +@section Auto-loading extensions +@cindex auto-loading extensions + +@value{GDBN} provides two mechanisms for automatically loading extensions +when a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library): +@file{@var{objfile}-gdb.@var{ext}} and the @code{.debug_gdb_scripts} +section of modern file formats like ELF. + +@menu +* objfile-gdb.ext file: objfile-gdbdotext file. The @file{@var{objfile}-gdb.@var{ext}} file +* .debug_gdb_scripts section: dotdebug_gdb_scripts section. The @code{.debug_gdb_scripts} section +* Which flavor to choose?:: +@end menu + +The auto-loading feature is useful for supplying application-specific +debugging commands and features. + +Auto-loading can be enabled or disabled, +and the list of auto-loaded scripts can be printed. +See the @samp{auto-loading} section of each extension language +for more information. +For @value{GDBN} command files see @ref{Auto-loading sequences}. +For Python files see @ref{Python Auto-loading}. + +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +@node objfile-gdbdotext file +@subsection The @file{@var{objfile}-gdb.@var{ext}} file +@cindex @file{@var{objfile}-gdb.gdb} +@cindex @file{@var{objfile}-gdb.py} +@cindex @file{@var{objfile}-gdb.scm} + +When a new object file is read, @value{GDBN} looks for a file named +@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below), +where @var{objfile} is the object file's name and +where @var{ext} is the file extension for the extension language: + +@table @code +@item @file{@var{objfile}-gdb.gdb} +GDB's own command language +@item @file{@var{objfile}-gdb.py} +Python +@end table + +@var{script-name} is formed by ensuring that the file name of @var{objfile} +is absolute, following all symlinks, and resolving @code{.} and @code{..} +components, and appending the @file{-gdb.@var{ext}} suffix. +If this file exists and is readable, @value{GDBN} will evaluate it as a +script in the specified extension language. + +If this file does not exist, then @value{GDBN} will look for +@var{script-name} file in all of the directories as specified below. + +Note that loading of these files requires an accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +For object files using @file{.exe} suffix @value{GDBN} tries to load first the +scripts normally according to its @file{.exe} filename. But if no scripts are +found @value{GDBN} also tries script filenames matching the object file without +its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it +is attempted on any platform. This makes the script filenames compatible +between Unix and MS-Windows hosts. + +@table @code +@anchor{set auto-load scripts-directory} +@kindex set auto-load scripts-directory +@item set auto-load scripts-directory @r{[}@var{directories}@r{]} +Control @value{GDBN} auto-loaded scripts location. Multiple directory entries +may be delimited by the host platform path separator in use +(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). + +Each entry here needs to be covered also by the security setting +@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). + +@anchor{with-auto-load-dir} +This variable defaults to @file{$debugdir:$datadir/auto-load}. The default +@code{set auto-load safe-path} value can be also overriden by @value{GDBN} +configuration option @option{--with-auto-load-dir}. + +Any reference to @file{$debugdir} will get replaced by +@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any +reference to @file{$datadir} will get replaced by @var{data-directory} which is +determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and +@file{$datadir} must be placed as a directory component --- either alone or +delimited by @file{/} or @file{\} directory separators, depending on the host +platform. + +The list of directories uses path separator (@samp{:} on GNU and Unix +systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly +to the @env{PATH} environment variable. + +@anchor{show auto-load scripts-directory} +@kindex show auto-load scripts-directory +@item show auto-load scripts-directory +Show @value{GDBN} auto-loaded scripts location. +@end table + +@value{GDBN} does not track which files it has already auto-loaded this way. +@value{GDBN} will load the associated script every time the corresponding +@var{objfile} is opened. +So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it +is evaluated more than once. + +@node dotdebug_gdb_scripts section +@subsection The @code{.debug_gdb_scripts} section +@cindex @code{.debug_gdb_scripts} section + +For systems using file formats like ELF and COFF, +when @value{GDBN} loads a new object file +it will look for a special section named @code{.debug_gdb_scripts}. +If this section exists, its contents is a list of NUL-terminated names +of scripts to load. Each entry begins with a non-NULL prefix byte that +specifies the kind of entry, typically the extension language. + +@value{GDBN} will look for each specified script file first in the +current directory and then along the source search path +(@pxref{Source Path, ,Specifying Source Directories}), +except that @file{$cdir} is not searched, since the compilation +directory is not relevant to scripts. + +Entries can be placed in section @code{.debug_gdb_scripts} with, +for example, this GCC macro for Python scripts. + +@example +/* Note: The "MS" section flags are to remove duplicates. */ +#define DEFINE_GDB_PY_SCRIPT(script_name) \ + asm("\ +.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ +.byte 1 /* Python */\n\ +.asciz \"" script_name "\"\n\ +.popsection \n\ +"); +@end example + +@noindent +Then one can reference the macro in a header or source file like this: + +@example +DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") +@end example + +The script name may include directories if desired. + +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +If the macro invocation is put in a header, any application or library +using this header will get a reference to the specified script, +and with the use of @code{"MS"} attributes on the section, the linker +will remove duplicates. + +@node Which flavor to choose? +@subsection Which flavor to choose? + +Given the multiple ways of auto-loading extensions, it might not always +be clear which one to choose. This section provides some guidance. + +@noindent +Benefits of the @file{-gdb.@var{ext}} way: + +@itemize @bullet +@item +Can be used with file formats that don't support multiple sections. + +@item +Ease of finding scripts for public libraries. + +Scripts specified in the @code{.debug_gdb_scripts} section are searched for +in the source search path. +For publicly installed libraries, e.g., @file{libstdc++}, there typically +isn't a source directory in which to find the script. + +@item +Doesn't require source code additions. +@end itemize + +@noindent +Benefits of the @code{.debug_gdb_scripts} way: + +@itemize @bullet +@item +Works with static linking. + +Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to +trigger their loading. When an application is statically linked the only +objfile available is the executable, and it is cumbersome to attach all the +scripts from all the input libraries to the executable's +@file{-gdb.@var{ext}} script. + +@item +Works with classes that are entirely inlined. + +Some classes can be entirely inlined, and thus there may not be an associated +shared library to attach a @file{-gdb.@var{ext}} script to. + +@item +Scripts needn't be copied out of the source tree. + +In some circumstances, apps can be built out of large collections of internal +libraries, and the build infrastructure necessary to install the +@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is +cumbersome. It may be easier to specify the scripts in the +@code{.debug_gdb_scripts} section as relative paths, and add a path to the +top of the source tree to the source search path. +@end itemize + @node Aliases @section Creating new spellings of existing commands @cindex aliases for commands |