* [doc RFA] Move docs on auto-loading extensions to Extending GDB section
@ 2013-12-23 17:12 Doug Evans
2013-12-23 17:28 ` Eli Zaretskii
0 siblings, 1 reply; 4+ messages in thread
From: Doug Evans @ 2013-12-23 17:12 UTC (permalink / raw)
To: eliz, gdb-patches
Hi.
This patch is in part a cleanup, and in part sets things up so that
it's easier to add the corresponding docs for Guile scripting.
If you read the section on "Auto-loading" in "Controlling GDB",
you'll see it has a menu of items, and a quasi-menu of other items.
The menu is at the bottom of the page:
---snip---
* Menu:
* Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit'
* libthread_db.so.1 file:: 'set/show/info auto-load libthread-db'
* objfile-gdb.gdb file:: 'set/show/info auto-load gdb-script'
* Auto-loading safe path:: 'set/show/info auto-load safe-path'
* Auto-loading verbose mode:: 'set/show debug auto-load'
*Note Python Auto-loading::.
---snip---
Earlier in the page is what I'm calling a quasi-menu:
[I'm cut-n-pasting these from my emacs buffer so setting aside underlining
and coloring, you see them here exactly as I'm seeing them in emacs.]
---snip---
These are various kinds of files GDB can automatically load:
* *Note objfile-gdb.py file::, controlled by *note set auto-load
python-scripts::.
* *Note objfile-gdb.gdb file::, controlled by *note set auto-load
gdb-scripts::.
* *Note dotdebug_gdb_scripts section::, controlled by *note set
auto-load python-scripts::.
* *Note Init File in the Current Directory::, controlled by *note set
auto-load local-gdbinit::.
* *Note libthread_db.so.1 file::, controlled by *note set auto-load
libthread-db::.
---snip---
Second, the docs on objfile-gdb.gdb are underneath "Controlling GDB" here:
Top > Controlling GDB > Auto-loading > objfile-gdb.gdb file
even though there is a section on native gdb scripting in "Extending GDB",
whereas the docs on objfile-gdb.py are underneath "Extending GDB" here:
Top > Extending GDB > Python > Python Auto-loading > objfile-gdb.py file
This patch creates a new menu entry in "Extending GDB" for
auto-loading extensions:
@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
and moves the high level discussion there, and adds a new menu entry
in "Sequences" (the section on native gdb scripting):
@menu
* Define:: How to define your own commands
* 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
so that native gdb scripting is treated consistently with python
scripting in this regard (compare the new "Auto-loading sequences" section
with "Python Auto-loading").
2013-12-22 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.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..43da8ea 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 @samp{ELF}.
+
+@menu
+* objfile-gdb.ext file:: The @file{@var{objfile}-gdb.@var{ext}} file
+* 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 @xref{Auto-loading sequences}.
+For Python files @xref{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-gdb.ext 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [doc RFA] Move docs on auto-loading extensions to Extending GDB section
2013-12-23 17:12 [doc RFA] Move docs on auto-loading extensions to Extending GDB section Doug Evans
@ 2013-12-23 17:28 ` Eli Zaretskii
2013-12-23 18:04 ` Doug Evans
0 siblings, 1 reply; 4+ messages in thread
From: Eli Zaretskii @ 2013-12-23 17:28 UTC (permalink / raw)
To: Doug Evans; +Cc: gdb-patches
> From: Doug Evans <xdje42@gmail.com>
> Date: Mon, 23 Dec 2013 09:12:09 -0800
>
> This patch is in part a cleanup, and in part sets things up so that
> it's easier to add the corresponding docs for Guile scripting.
If it just moves stuff around without changing any actual content
(menus don't count), then it doesn't need to be reviewed, once we
agree on the restructuring itself (which is fine with me).
I have a couple of comments, which are probably to the text that was
already in the manual (so it is up to you whether to fix them):
> +@file{@var{OBJFILE}-gdb.@var{EXT}} and the @code{.debug_gdb_scripts}
Please don't use upper case in @var, it looks ugly in print.
> +section of modern file formats like @samp{ELF}.
"ELF" is not a programming language symbol, so doesn't need @samp.
Use either @acronym{ELF} or @sc{elf} or just ELF with no markup.
> +@menu
> +* objfile-gdb.ext file:: The @file{@var{objfile}-gdb.@var{ext}} file
Node names cannot contain periods, this confuses some Info readers.
> +For @value{GDBN} command files @xref{Auto-loading sequences}.
> +For Python files @xref{Python Auto-loading}.
@xref is inappropriate in the middle of a sentence, because it
produces a capitalized "Note". Use @pxref or "see @ref" instead.
> +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
^^^
"NULL", right?
Thanks.
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [doc RFA] Move docs on auto-loading extensions to Extending GDB section
2013-12-23 17:28 ` Eli Zaretskii
@ 2013-12-23 18:04 ` Doug Evans
2013-12-23 18:45 ` Eli Zaretskii
0 siblings, 1 reply; 4+ messages in thread
From: Doug Evans @ 2013-12-23 18:04 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: gdb-patches
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Doug Evans <xdje42@gmail.com>
>> Date: Mon, 23 Dec 2013 09:12:09 -0800
>>
>> This patch is in part a cleanup, and in part sets things up so that
>> it's easier to add the corresponding docs for Guile scripting.
>
> If it just moves stuff around without changing any actual content
> (menus don't count), then it doesn't need to be reviewed, once we
> agree on the restructuring itself (which is fine with me).
I did change/add *some* wording, but kept it minimal.
E.g., I added this:
+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}.
because I wanted an xref to "Auto-loading extensions" here.
> I have a couple of comments, which are probably to the text that was
> already in the manual (so it is up to you whether to fix them):
>
>> +@file{@var{OBJFILE}-gdb.@var{EXT}} and the @code{.debug_gdb_scripts}
>
> Please don't use upper case in @var, it looks ugly in print.
Righto.
>> +section of modern file formats like @samp{ELF}.
>
> "ELF" is not a programming language symbol, so doesn't need @samp.
> Use either @acronym{ELF} or @sc{elf} or just ELF with no markup.
Done.
>> +@menu
>> +* objfile-gdb.ext file:: The @file{@var{objfile}-gdb.@var{ext}} file
>
> Node names cannot contain periods, this confuses some Info readers.
I guess the solution here is to use this?
* MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION
[cut-n-pasted from texinfo docs]
If so, I'll use it for this entry too:
* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
>> +For @value{GDBN} command files @xref{Auto-loading sequences}.
>> +For Python files @xref{Python Auto-loading}.
>
> @xref is inappropriate in the middle of a sentence, because it
> produces a capitalized "Note". Use @pxref or "see @ref" instead.
Done.
>> +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
> ^^^
> "NULL", right?
NULL is a zero-valued pointer.
NUL is the common ASCII name for character '\0'.
I grepped for other uses of NUL in the docs and found a few
so figured it was ok to use. E.g.,
---snip---
There is no trailing NUL byte in a remote protocol packet; if the stub
stores packets in a NUL-terminated format, it should allow an extra
byte in its buffer for the NUL. If this stub feature is not supported,
---snip---
Revised patch:
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.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..318c971 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [doc RFA] Move docs on auto-loading extensions to Extending GDB section
2013-12-23 18:04 ` Doug Evans
@ 2013-12-23 18:45 ` Eli Zaretskii
0 siblings, 0 replies; 4+ messages in thread
From: Eli Zaretskii @ 2013-12-23 18:45 UTC (permalink / raw)
To: Doug Evans; +Cc: gdb-patches
> From: Doug Evans <xdje42@gmail.com>
> Cc: gdb-patches@sourceware.org
> Date: Mon, 23 Dec 2013 10:03:52 -0800
>
> I did change/add *some* wording, but kept it minimal.
> E.g., I added this:
>
> +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}.
^^
Two spaces.
> >> +@menu
> >> +* objfile-gdb.ext file:: The @file{@var{objfile}-gdb.@var{ext}} file
> >
> > Node names cannot contain periods, this confuses some Info readers.
>
> I guess the solution here is to use this?
>
> * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION
>
> [cut-n-pasted from texinfo docs]
Yes.
> If so, I'll use it for this entry too:
>
> * dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
Thanks.
> >> +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
> > ^^^
> > "NULL", right?
>
> NULL is a zero-valued pointer.
> NUL is the common ASCII name for character '\0'.
> I grepped for other uses of NUL in the docs and found a few
> so figured it was ok to use. E.g.,
>
> ---snip---
> There is no trailing NUL byte in a remote protocol packet; if the stub
> stores packets in a NUL-terminated format, it should allow an extra
> byte in its buffer for the NUL. If this stub feature is not supported,
> ---snip---
Unicode calls it NULL, but I won't argue.
Thank, you can commit the patch.
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2013-12-23 18:45 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-12-23 17:12 [doc RFA] Move docs on auto-loading extensions to Extending GDB section Doug Evans
2013-12-23 17:28 ` Eli Zaretskii
2013-12-23 18:04 ` Doug Evans
2013-12-23 18:45 ` Eli Zaretskii
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).