* gdb.texinfo (Source Path): Add documentation for new
substitute-path commands.
This commit is contained in:
parent
2f61ca93c2
commit
30daae6caf
|
@ -1,3 +1,8 @@
|
||||||
|
2006-08-08 Joel Brobecker <brobecker@adacore.com>
|
||||||
|
|
||||||
|
* gdb.texinfo (Source Path): Add documentation for new
|
||||||
|
substitute-path commands.
|
||||||
|
|
||||||
2006-08-08 Daniel Jacobowitz <dan@codesourcery.com>
|
2006-08-08 Daniel Jacobowitz <dan@codesourcery.com>
|
||||||
|
|
||||||
* gdb.texinfo (Installing GDB): Update menu. Move text to...
|
* gdb.texinfo (Installing GDB): Update menu. Move text to...
|
||||||
|
|
|
@ -5033,6 +5033,53 @@ To add other directories, use the @code{directory} command.
|
||||||
The search path is used to find both program source files and @value{GDBN}
|
The search path is used to find both program source files and @value{GDBN}
|
||||||
script files (read using the @samp{-command} option and @samp{source} command).
|
script files (read using the @samp{-command} option and @samp{source} command).
|
||||||
|
|
||||||
|
In addition to the source path, @value{GDBN} provides a set of commands
|
||||||
|
that manage a list of source path substitution rules. A @dfn{substitution
|
||||||
|
rule} specifies how to rewrite source directories stored in the program's
|
||||||
|
debug information in case the sources were moved to a different
|
||||||
|
directory between compilation and debugging. A rule is made of
|
||||||
|
two strings, the first specifying what needs to be rewritten in
|
||||||
|
the path, and the second specifying how it should be rewritten.
|
||||||
|
In @ref{set substitute-path}, we name these two parts @var{from} and
|
||||||
|
@var{to} respectively. @value{GDBN} does a simple string replacement
|
||||||
|
of @var{from} with @var{to} at the start of the directory part of the
|
||||||
|
source file name, and uses that result instead of the original file
|
||||||
|
name to look up the sources.
|
||||||
|
|
||||||
|
Using the previous example, suppose the @file{foo-1.0} tree has been
|
||||||
|
moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
|
||||||
|
GDB to replace @file{/usr/src} in all source path names with
|
||||||
|
@file{/mnt/cross}. The first lookup will then be
|
||||||
|
@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
|
||||||
|
of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
|
||||||
|
substitution rule, use the @code{set substitute-path} command
|
||||||
|
(@pxref{set substitute-path}).
|
||||||
|
|
||||||
|
To avoid unexpected substitution results, a rule is applied only if the
|
||||||
|
@var{from} part of the directory name ends at a directory separator.
|
||||||
|
For instance, a rule substituting @file{/usr/source} into
|
||||||
|
@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
|
||||||
|
not to @file{/usr/sourceware/foo-2.0}. And because the substitution
|
||||||
|
is applied only at the begining of the directory name, this rule will
|
||||||
|
not be applied to @file{/root/usr/source/baz.c} either.
|
||||||
|
|
||||||
|
In many cases, you can achieve the same result using the @code{directory}
|
||||||
|
command. However, @code{set substitute-path} can be more efficient in
|
||||||
|
the case where the sources are organized in a complex tree with multiple
|
||||||
|
subdirectories. With the @code{directory} command, you need to add each
|
||||||
|
subdirectory of your project. If you moved the entire tree while
|
||||||
|
preserving its internal organization, then @code{set substitute-path}
|
||||||
|
allows you to direct the debugger to all the sources with one single
|
||||||
|
command.
|
||||||
|
|
||||||
|
@code{set substitute-path} is also more than just a shortcut command.
|
||||||
|
The source path is only used if the file at the original location no
|
||||||
|
longer exists. On the other hand, @code{set substitute-path} modifies
|
||||||
|
the debugger behavior to look at the rewritten location instead. So, if
|
||||||
|
for any reason a source file that is not relevant to your executable is
|
||||||
|
located at the original location, a substitution rule is the only
|
||||||
|
method available to point GDB at the new location.
|
||||||
|
|
||||||
@table @code
|
@table @code
|
||||||
@item directory @var{dirname} @dots{}
|
@item directory @var{dirname} @dots{}
|
||||||
@item dir @var{dirname} @dots{}
|
@item dir @var{dirname} @dots{}
|
||||||
|
@ -5068,6 +5115,61 @@ Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems).
|
||||||
@item show directories
|
@item show directories
|
||||||
@kindex show directories
|
@kindex show directories
|
||||||
Print the source path: show which directories it contains.
|
Print the source path: show which directories it contains.
|
||||||
|
|
||||||
|
@anchor{set substitute-path}
|
||||||
|
@item set substitute-path @var{from} @var{to}
|
||||||
|
@kindex set substitute-path
|
||||||
|
Define a source path substitution rule, and add it at the end of the
|
||||||
|
current list of existing substitution rules. If a rule with the same
|
||||||
|
@var{from} was already defined, then the old rule is also deleted.
|
||||||
|
|
||||||
|
For example, if the file @file{/foo/bar/baz.c} was moved to
|
||||||
|
@file{/mnt/cross/baz.c}, then the command
|
||||||
|
|
||||||
|
@smallexample
|
||||||
|
(@value{GDBP}) set substitute-path /usr/src /mnt/cross
|
||||||
|
@end smallexample
|
||||||
|
|
||||||
|
@noindent
|
||||||
|
will tell @value{GDBN} to replace @samp{/usr/src} with
|
||||||
|
@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
|
||||||
|
@file{baz.c} even though it was moved.
|
||||||
|
|
||||||
|
In the case when more than one substitution rule have been defined,
|
||||||
|
the rules are evaluated one by one in the order where they have been
|
||||||
|
defined. The first one matching, if any, is selected to perform
|
||||||
|
the substitution.
|
||||||
|
|
||||||
|
For instance, if we had entered the following commands:
|
||||||
|
|
||||||
|
@smallexample
|
||||||
|
(@value{GDBP}) set substitute-path /usr/src/include /mnt/include
|
||||||
|
(@value{GDBP}) set substitute-path /usr/src /mnt/src
|
||||||
|
@end smallexample
|
||||||
|
|
||||||
|
@noindent
|
||||||
|
@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
|
||||||
|
@file{/mnt/include/defs.h} by using the first rule. However, it would
|
||||||
|
use the second rule to rewrite @file{/usr/src/lib/foo.c} into
|
||||||
|
@file{/mnt/src/lib/foo.c}.
|
||||||
|
|
||||||
|
|
||||||
|
@item unset substitute-path [path]
|
||||||
|
@kindex unset substitute-path
|
||||||
|
If a path is specified, search the current list of substitution rules
|
||||||
|
for a rule that would rewrite that path. Delete that rule if found.
|
||||||
|
A warning is emitted by the debugger if no rule could be found.
|
||||||
|
|
||||||
|
If no path is specified, then all substitution rules are deleted.
|
||||||
|
|
||||||
|
@item show substitute-path [path]
|
||||||
|
@kindex show substitute-path
|
||||||
|
If a path is specified, then print the source path substitution rule
|
||||||
|
which would rewrite that path, if any.
|
||||||
|
|
||||||
|
If no path is specified, then print all existing source path substitution
|
||||||
|
rules.
|
||||||
|
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
If your source path is cluttered with directories that are no longer of
|
If your source path is cluttered with directories that are no longer of
|
||||||
|
|
Loading…
Reference in New Issue