When a new object file is read, gdb looks for
a file named objfile-gdb.py (we call it script-name below),
where objfile is the object file's real name, formed by ensuring
that the file name is absolute, following all symlinks, and resolving
.. components. If this file exists and is
readable, gdb will evaluate it as a Python script.
If this file does not exist, then gdb will look for script-name file in all of the directories as specified below.
Note that loading of this script file also requires accordingly configured
auto-load safe-path (see Auto-loading safe path).
For object files using .exe suffix gdb tries to load first the scripts normally according to its .exe filename. But if no scripts are found gdb also tries script filenames matching the object file without its .exe suffix. This .exe stripping is case insensitive and it is attempted on any platform. This makes the script filenames compatible between Unix and MS-Windows hosts.
set auto-load scripts-directory[directories]
Each entry here needs to be covered also by the security setting
set auto-load safe-path (see set auto-load safe-path).
This variable defaults to $debugdir:$datadir/auto-load. The default
set auto-load safe-path value can be also overriden by gdb
configuration option --with-auto-load-dir.
Any reference to $debugdir will get replaced by debug-file-directory value (see Separate Debug Files) and any reference to $datadir will get replaced by data-directory which is determined at gdb startup (see Data Files). $debugdir and $datadir must be placed as a directory component — either alone or delimited by / or \ directory separators, depending on the host platform.
The list of directories uses path separator (‘:’ on GNU and Unix systems, ‘;’ on MS-Windows and MS-DOS) to separate directories, similarly to the PATH environment variable.
show auto-load scripts-directory
gdb does not track which files it has already auto-loaded this way. gdb will load the associated script every time the corresponding objfile is opened. So your -gdb.py file should be careful to avoid errors if it is evaluated more than once.