+@c Guile docs live in a separate file.
+@include guile.texi
+
+@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
+@item @file{@var{objfile}-gdb.scm}
+Guile
+@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
+For Guile scripts, replace @code{.byte 1} with @code{.byte 3}.
+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 Multiple Extension Languages
+@section Multiple Extension Languages
+
+The Guile and Python extension languages do not share any state,
+and generally do not interfere with each other.
+There are some things to be aware of, however.
+
+@subsection Python comes first
+
+Python was @value{GDBN}'s first extension language, and to avoid breaking
+existing behaviour Python comes first. This is generally solved by the
+``first one wins'' principle. @value{GDBN} maintains a list of enabled
+extension languages, and when it makes a call to an extension language,
+(say to pretty-print a value), it tries each in turn until an extension
+language indicates it has performed the request (e.g., has returned the
+pretty-printed form of a value).
+This extends to errors while performing such requests: If an error happens
+while, for example, trying to pretty-print an object then the error is
+reported and any following extension languages are not tried.
+
projects / deliverable / binutils-gdb.git / blobdiff