Reorganize extension language auto-loading docs.
* 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.
This commit is contained in:
Doug Evans
parent
e617b0692b
commit
71b8c8455f
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
To facilitate the use of the first two extensions, @value{GDBN} is capable
|
||||
@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 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue