How the Debugger Finds Source Files

The debugger searches for a source file (dir_name/base_name) using the following algorithm:

1. If dir_name is mapped to another source directory (mapped_dir_name), look for mapped_dir_name/base_name.
2. If Step 1 fails to find a readable file:
   Case 1: If dir_name is absolute, look for dir_name/base_name.
   Case 2: If dir_name is relative, for each entry use_dir in use_list, look for use_dir/dir_name/base_name. Note that the use_list entries are tried in the order they appear in the use_list.
3. If Step 2 fails, for each entry use_dir in use_list, look for use_dir/base_name. Just as in Step 2, the use_list entries are tried in the order they appear in the use_list.
4. If Step 3 fails, the debugger cannot find any source file.

The debugger uses the first-found readable file as the source file.

The debugger has source directory mapping commands that:

• Inform you in which directories the debugger is looking for the source files.
• Allow you to designate directories in which the debugger will look for the source files.

The following example shows how to use source directory mapping. Suppose you compile x_solarSystem as follows:

% pwd

/home/user/examples

% ls -R

bin/ src/

./bin:

x_solarSystem*

./src:

solarSystemSrc/

./src/solarSystemSrc:

base_class_includes/    main/                   star.cxx

derived_class_includes/ orbit.cxx

heavenlyBody.cxx        planet.cxx

./src/solarSystemSrc/base_class_includes:

heavenlyBody.h  orbit.h

./src/solarSystemSrc/derived_class_includes:

planet.h  star.h

./src/solarSystemSrc/main:

solarSystem.cxx

% cd src

% cc -g -o ../bin/x_solarSystem \

  -IsolarSystemSrc/base_class_includes \

  -IsolarSystemSrc/derived_class_includes \

  main/solarSystem.cxx heavenlyBody.cxx orbit.cxx planet.cxx star.cxx

Then you move the directory solarSystemSrc elsewhere:

% mv solarSystemSrc movedSolarSystemSrc

Now debug x_solarSystem in /home/users/Examples/bin

DBX Mode

(idb) list $curline - 10:20

Source file not found or not readable, tried...

    ./bld/i686-Linux-development/debuggable/solarSystemSrc/main/solarSystem.cxx

    ../src/bld/i686-Linux-development/debuggable/solarSystemSrc/main/solarSystem.cxx

    /home/user/examples/bld/i686-Linux-development/debuggable/solarSystemSrc/main/solarSystem.cxx

    ./solarSystem.cxx

    ../src/solarSystem.cxx

    /home/user/examples/solarSystem.cxx

The debugger cannot find the file because it has been moved to another directory.

The following command displays a summary of the source directories in a.outexe. The ellipsis (...) here means that solarSystemSrc contains one or more source directories.

DBX Mode

(idb) show source directory

.

/home/user/examples/solarSystemSrc

 ...

Information: You can further expand a '...' using the command

    show source directory <directory>

or

    show all source directory <directory>

where <directory> is the directory on the line above the '...'.

The first command displays only the children of <directory>, whereas

the second command displays all the descendants of <directory>.

The following command directs the debugger to look for source files originally in solarSystemSrc in movedSolarSystemSrc instead. This time, the debugger finds the source file.

DBX Mode

(idb) map source directory /home/user/examples/solarSystemSrc /home/user/examples/movedSolarSystemSrc

(idb) list $curline - 10:20

    104

    105     // Insert the new entry appropriately

    106     //

    107     if (iAmBiggerThan < biggestCount) {

    108         biggestMoons[iAmBiggerThan] = moon;

    109     }

    110 }

    111

    112 int main()

    113 {

>   114     unsigned int j = 1;    // for scoping examples

    115     for (unsigned int i = 0; i < biggestCount; i++)

    116         biggestMoons[i] = NULL;

    117

    118     Star *sun = new Star("Sol", G, 2);

    119     buildOurSolarSystem(sun);

    120     sun->printBodyAndItsSatellites(j);

    121     printBiggestMoons();

    122

    123     return 0;

The following command gives a complete list of source directories. As you can see, solarSystemSrc is mapped to movedSolarSystemSrc. As a side effect of mapping solarSystemSrc to movedSolarSystemSrc, the subdirectories in solarSystemSrc are mapped to their counterparts under movedSolarSystemSrc.

DBX Mode

(idb) show all source directory

.

/home/user/examples/solarSystemSrc  *=>  /home/user/examples/movedSolarSystemSrc

 /home/user/examples/solarSystemSrc/base_class_includes  =>  /home/user/examples/movedSolarSystemSrc/base_class_includes

 /home/user/examples/solarSystemSrc/derived_class_includes  =>  /home/user/examples/movedSolarSystemSrc/derived_class_includes

 /home/user/examples/solarSystemSrc/main  =>  /home/user/examples/movedSolarSystemSrc/main

To summarize, the debugger provides the following four commands for checking and setting source directory mappings:

DBX Mode

source_directory_mapping_command

        : show source directory [ directory_name ]

        | show all source directory [ directory_name ]

        | map source directory from_directory_name to_directory_name

        | unmap source directory from_directory_name

Use the show source directory (dbx) command to display the directory mapping information of directory_name and its child directories (or immediate subdirectory). If directory_name is not specified, the mapping information of all the source directories whose parent is not a source directory is displayed.

The show all source directory (dbx) command is identical to the show source directory (dbx) command except that the mapping information of all the descendants of directory_name is displayed:

DBX Mode

(idb) show source directory

.

/home/user/examples/solarSystemSrc  *=>  /home/user/examples/movedSolarSystemSrc

 ...

(idb) show all source directory

.

/home/user/examples/solarSystemSrc  *=>  /home/user/examples/movedSolarSystemSrc

 /home/user/examples/solarSystemSrc/base_class_includes  =>  /home/user/examples/movedSolarSystemSrc/base_class_includes

 /home/user/examples/solarSystemSrc/derived_class_includes  =>  /home/user/examples/movedSolarSystemSrc/derived_class_includes

 /home/user/examples/solarSystemSrc/main  =>  /home/user/examples/movedSolarSystemSrc/main

When you further expand ellipsis points (...) where directory is the directory on the line above the ellipsis points:

• The show source directory (dbx) command displays only the children of directory_name.
• The show all source directory (dbx) command displays all the descendants of directory_name.

Use the map source directory (dbx) command to tell the debugger that the source files in the directory from_directory_name can now be found in to_directory_name.

The unmap source directory (dbx) command maps from_directory_name back to itself; in other words, if from_directory_name has been mapped to some other directory, this command will restore its default mapping. For example:

DBX Mode

(idb) show source directory

.

/home/user/examples/solarSystemSrc  *=>  /home/user/examples/movedSolarSystemSrc

 ...

(idb) show source directory /home/user/examples/solarSystemSrc

/home/user/examples/solarSystemSrc  *=>  /home/user/examples/movedSolarSystemSrc

 /home/user/examples/solarSystemSrc/base_class_includes  =>  /home/user/examples/movedSolarSystemSrc/base_class_includes

 /home/user/examples/solarSystemSrc/derived_class_includes  =>  /home/user/examples/movedSolarSystemSrc/derived_class_includes

 /home/user/examples/solarSystemSrc/main  =>  /home/user/examples/movedSolarSystemSrc/main

(idb) unmap source directory /home/user/examples/solarSystemSrc

(idb) show source directory /home/user/examples/solarSystemSrc

/home/user/examples/solarSystemSrc

 /home/user/examples/solarSystemSrc/base_class_includes

 /home/user/examples/solarSystemSrc/derived_class_includes

Note:

The symbol *=> means that you are setting the mapping explicitly using the map source directory (dbx) command, whereas => means that the mapping is derived from an existing explicit mapping.

By default, the use_list is: (1) the current directory and (2) the directory containing the executable file (dbx). Each process has its own use_list. You can also use the idb command -I option to specify search directories.

The following commands let you view and modify the use_list.

DBX Mode

source_search_list_command

        : use_command

        | unuse_command

GDB Mode

source_search_list_command

        : directory_command

        | show directories

Enter the use (dbx) without an argument or show directories (gdb) command to list the directories in which the debugger searches for source code files. Specify a directory argument to make source code files in that directory available to the debugger. You can also use the idb command -I option to specify search directories, which puts those directories in the use_list.

You can customize your debugger environment source code search paths by adding commands to your .dbxinit file that use the use command:

DBX Mode

use_command

        : use [directory_name ...]

If the directory_name is specified, it is either appended to or replaces the use_list, depending on whether the value of the $dbxuse debugger variable is zero (append) or non-zero (replace).

(idb) use

Directory search path for source files:

. ../src /home/user/examples

(idb)

(idb) use aa

Directory search path for source files:

. ../src /home/user/examples aa

(idb)

(idb) use bb cc

Directory search path for source files:

. ../src /home/user/examples aa bb cc

(idb)

(idb)

(idb) use bb

Directory search path for source files:

. ../src /home/user/examples aa bb cc

(idb) use aa bb cc

Directory search path for source files:

. ../src /home/user/examples aa bb cc

(idb) set $dbxuse = 1

(idb) use aa

Directory search path for source files:

. ../src /home/user/examples aa

(idb) use aa bb cc

GDB Mode

directory_command

        : directory [directory_name ...]

Use the directory command with no argument to reset the use_list to empty value.

If the directory_name is specified, it is prepended to use_list. Several directory names may be given to the directory command, separated by ':' or whitespace. If you specify a directory, which is already in the list, it is moved forward.

To get the full list of directories in the search list, use the show directories command.

DBX Mode

unuse_command

        : unuse [directory_name ...]

        | unuse *

The unuse command removes entries from the use_list:

Enter the unuse command without the directory_name to set the search list to the default (the home directory, the current directory, and the directory containing the executable file). Include the directory names to remove them from the search list. The asterisk (*) argument removes all directories from the search list.

(idb)

(idb) unuse aa

Directory search path for source files:

. ../src /home/user/examples bb cc

(idb)

(idb) unuse aa

aa not in the current source path

Directory search path for source files:

. ../src /home/user/examples bb cc

(idb)

(idb) unuse bb cc

Directory search path for source files:

. ../src /home/user/examples

(idb)

(idb) unuse *

Directory search path for source files:

(idb)

(idb) unuse

Directory search path for source files:

. ../src /home/user/examples