7.4 Specifying Source Directories

Executable programs sometimes do not record the directories of the source files from which they were compiled, just the names. Even when they do, the directories could be moved between the compilation and your debugging session. No value for GDBN has a list of directories to search for source files; this is called the source path. Each time No value for GDBN wants a source file, it tries all the directories in the list, in the order they are present in the list, until it finds a file with the desired name.

For example, suppose an executable references the file ‘/usr/src/foo-1.0/lib/foo.c’, and our source path is ‘/mnt/cross’. The file is first looked up literally; if this fails, ‘/mnt/cross/usr/src/foo-1.0/lib/foo.c’ is tried; if this fails, ‘/mnt/cross/foo.c’ is opened; if this fails, an error message is printed. No value for GDBN does not look up the parts of the source file name, such as ‘/mnt/cross/src/foo-1.0/lib/foo.c’. Likewise, the subdirectories of the source path are not searched: if the source path is ‘/mnt/cross’, and the binary refers to ‘foo.c’, No value for GDBN would not find it under ‘/mnt/cross/usr/src/foo-1.0/lib’.

Plain file names, relative file names with leading directories, file names containing dots, etc. are all treated as described above; for instance, if the source path is ‘/mnt/cross’, and the source file is recorded as ‘../lib/foo.c’, No value for GDBN would first try ‘../lib/foo.c’, then ‘/mnt/cross/../lib/foo.c’, and after that—‘/mnt/cross/foo.c’.

Note that the executable search path is not used to locate the source files.

Whenever you reset or rearrange the source path, No value for GDBN clears out any information it has cached about where source files are found and where each line is in the file.

When you start No value for GDBN, its source path includes only ‘cdir’ and ‘cwd’, in that order. To add other directories, use the directory command.

The search path is used to find both program source files and No value for GDBN script files (read using the ‘-command’ option and ‘source’ command).

In addition to the source path, No value for GDBN provides a set of commands that manage a list of source path substitution rules. A 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 set substitute-path, we name these two parts from and to respectively. No value for GDBN does a simple string replacement of from with 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 ‘foo-1.0’ tree has been moved from ‘/usr/src’ to ‘/mnt/cross’, then you can tell No value for GDBN to replace ‘/usr/src’ in all source path names with ‘/mnt/cross’. The first lookup will then be ‘/mnt/cross/foo-1.0/lib/foo.c’ in place of the original location of ‘/usr/src/foo-1.0/lib/foo.c’. To define a source path substitution rule, use the set substitute-path command (see set substitute-path).

To avoid unexpected substitution results, a rule is applied only if the from part of the directory name ends at a directory separator. For instance, a rule substituting ‘/usr/source’ into ‘/mnt/cross’ will be applied to ‘/usr/source/foo-1.0’ but not to ‘/usr/sourceware/foo-2.0’. And because the substitution is applied only at the beginning of the directory name, this rule will not be applied to ‘/root/usr/source/baz.c’ either.

In many cases, you can achieve the same result using the directory command. However, set substitute-path can be more efficient in the case where the sources are organized in a complex tree with multiple subdirectories. With the directory command, you need to add each subdirectory of your project. If you moved the entire tree while preserving its internal organization, then set substitute-path allows you to direct the debugger to all the sources with one single command.

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, 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 No value for GDBN at the new location.

directory dirname …

dir dirname …

Add directory dirname to the front of the source path. Several directory names may be given to this command, separated by ‘:’ (‘;’ on MS-DOS and MS-Windows, where ‘:’ usually appears as part of absolute file names) or whitespace. You may specify a directory that is already in the source path; this moves it forward, so No value for GDBN searches it sooner.

You can use the string ‘$cdir’ to refer to the compilation directory (if one is recorded), and ‘$cwd’ to refer to the current working directory. ‘$cwd’ is not the same as ‘.’—the former tracks the current working directory as it changes during your No value for GDBN session, while the latter is immediately expanded to the current directory at the time you add an entry to the source path.

directory

Reset the source path to its default value (‘$cdir:$cwd’ on Unix systems). This requires confirmation.

show directories

Print the source path: show which directories it contains.

set substitute-path from to

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 from was already defined, then the old rule is also deleted.

For example, if the file ‘/foo/bar/baz.c’ was moved to ‘/mnt/cross/baz.c’, then the command

(No value for GDBP) set substitute-path /usr/src /mnt/cross

will tell No value for GDBN to replace ‘/usr/src’ with ‘/mnt/cross’, which will allow No value for GDBN to find the 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:

(No value for GDBP) set substitute-path /usr/src/include /mnt/include (No value for GDBP) set substitute-path /usr/src /mnt/src

No value for GDBN would then rewrite ‘/usr/src/include/defs.h’ into ‘/mnt/include/defs.h’ by using the first rule. However, it would use the second rule to rewrite ‘/usr/src/lib/foo.c’ into ‘/mnt/src/lib/foo.c’.

unset substitute-path [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.

show substitute-path [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.

If your source path is cluttered with directories that are no longer of interest, No value for GDBN may sometimes cause confusion by finding the wrong versions of source. You can correct the situation as follows:

1. Use directory with no argument to reset the source path to its default value.
2. Use directory with suitable arguments to reinstall the directories you want in the source path. You can add all the directories in one command.