| <html lang="en"> |
| <head> |
| <title>Source Path - Debugging with GDB</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Debugging with GDB"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Source.html#Source" title="Source"> |
| <link rel="prev" href="Search.html#Search" title="Search"> |
| <link rel="next" href="Machine-Code.html#Machine-Code" title="Machine Code"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Source-Path"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Machine-Code.html#Machine-Code">Machine Code</a>, |
| Previous: <a rel="previous" accesskey="p" href="Search.html#Search">Search</a>, |
| Up: <a rel="up" accesskey="u" href="Source.html#Source">Source</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">9.5 Specifying Source Directories</h3> |
| |
| <p><a name="index-source-path-453"></a><a name="index-directories-for-source-files-454"></a>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. <span class="sc">gdb</span> has a list of directories to search for source files; |
| this is called the <dfn>source path</dfn>. Each time <span class="sc">gdb</span> 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. |
| |
| <p>For example, suppose an executable references the file |
| <samp><span class="file">/usr/src/foo-1.0/lib/foo.c</span></samp>, and our source path is |
| <samp><span class="file">/mnt/cross</span></samp>. The file is first looked up literally; if this |
| fails, <samp><span class="file">/mnt/cross/usr/src/foo-1.0/lib/foo.c</span></samp> is tried; if this |
| fails, <samp><span class="file">/mnt/cross/foo.c</span></samp> is opened; if this fails, an error |
| message is printed. <span class="sc">gdb</span> does not look up the parts of the |
| source file name, such as <samp><span class="file">/mnt/cross/src/foo-1.0/lib/foo.c</span></samp>. |
| Likewise, the subdirectories of the source path are not searched: if |
| the source path is <samp><span class="file">/mnt/cross</span></samp>, and the binary refers to |
| <samp><span class="file">foo.c</span></samp>, <span class="sc">gdb</span> would not find it under |
| <samp><span class="file">/mnt/cross/usr/src/foo-1.0/lib</span></samp>. |
| |
| <p>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 <samp><span class="file">/mnt/cross</span></samp>, and the source file |
| is recorded as <samp><span class="file">../lib/foo.c</span></samp>, <span class="sc">gdb</span> would first try |
| <samp><span class="file">../lib/foo.c</span></samp>, then <samp><span class="file">/mnt/cross/../lib/foo.c</span></samp>, and after |
| that—<samp><span class="file">/mnt/cross/foo.c</span></samp>. |
| |
| <p>Note that the executable search path is <em>not</em> used to locate the |
| source files. |
| |
| <p>Whenever you reset or rearrange the source path, <span class="sc">gdb</span> clears out |
| any information it has cached about where source files are found and where |
| each line is in the file. |
| |
| <p><a name="index-directory-455"></a><a name="index-dir-456"></a>When you start <span class="sc">gdb</span>, its source path includes only ‘<samp><span class="samp">cdir</span></samp>’ |
| and ‘<samp><span class="samp">cwd</span></samp>’, in that order. |
| To add other directories, use the <code>directory</code> command. |
| |
| <p>The search path is used to find both program source files and <span class="sc">gdb</span> |
| script files (read using the ‘<samp><span class="samp">-command</span></samp>’ option and ‘<samp><span class="samp">source</span></samp>’ command). |
| |
| <p>In addition to the source path, <span class="sc">gdb</span> provides a set of commands |
| that manage a list of source path substitution rules. A <dfn>substitution |
| rule</dfn> 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 <a href="set-substitute_002dpath.html#set-substitute_002dpath">set substitute-path</a>, we name these two parts <var>from</var> and |
| <var>to</var> respectively. <span class="sc">gdb</span> does a simple string replacement |
| of <var>from</var> with <var>to</var> 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. |
| |
| <p>Using the previous example, suppose the <samp><span class="file">foo-1.0</span></samp> tree has been |
| moved from <samp><span class="file">/usr/src</span></samp> to <samp><span class="file">/mnt/cross</span></samp>, then you can tell |
| <span class="sc">gdb</span> to replace <samp><span class="file">/usr/src</span></samp> in all source path names with |
| <samp><span class="file">/mnt/cross</span></samp>. The first lookup will then be |
| <samp><span class="file">/mnt/cross/foo-1.0/lib/foo.c</span></samp> in place of the original location |
| of <samp><span class="file">/usr/src/foo-1.0/lib/foo.c</span></samp>. To define a source path |
| substitution rule, use the <code>set substitute-path</code> command |
| (see <a href="set-substitute_002dpath.html#set-substitute_002dpath">set substitute-path</a>). |
| |
| <p>To avoid unexpected substitution results, a rule is applied only if the |
| <var>from</var> part of the directory name ends at a directory separator. |
| For instance, a rule substituting <samp><span class="file">/usr/source</span></samp> into |
| <samp><span class="file">/mnt/cross</span></samp> will be applied to <samp><span class="file">/usr/source/foo-1.0</span></samp> but |
| not to <samp><span class="file">/usr/sourceware/foo-2.0</span></samp>. And because the substitution |
| is applied only at the beginning of the directory name, this rule will |
| not be applied to <samp><span class="file">/root/usr/source/baz.c</span></samp> either. |
| |
| <p>In many cases, you can achieve the same result using the <code>directory</code> |
| command. However, <code>set substitute-path</code> can be more efficient in |
| the case where the sources are organized in a complex tree with multiple |
| subdirectories. With the <code>directory</code> 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</code> |
| allows you to direct the debugger to all the sources with one single |
| command. |
| |
| <p><code>set substitute-path</code> 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</code> 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 <span class="sc">gdb</span> at the new location. |
| |
| <p><a name="index-g_t_0040samp_007b_002d_002dwith_002drelocated_002dsources_007d-457"></a><a name="index-default-source-path-substitution-458"></a>You can configure a default source path substitution rule by |
| configuring <span class="sc">gdb</span> with the |
| ‘<samp><span class="samp">--with-relocated-sources=</span><var>dir</var></samp>’ option. The <var>dir</var> |
| should be the name of a directory under <span class="sc">gdb</span>'s configured |
| prefix (set with ‘<samp><span class="samp">--prefix</span></samp>’ or ‘<samp><span class="samp">--exec-prefix</span></samp>’), and |
| directory names in debug information under <var>dir</var> will be adjusted |
| automatically if the installed <span class="sc">gdb</span> is moved to a new |
| location. This is useful if <span class="sc">gdb</span>, libraries or executables |
| with debug information and corresponding source code are being moved |
| together. |
| |
| <dl> |
| <dt><code>directory </code><var>dirname</var><code> ...</code><br><dt><code>dir </code><var>dirname</var><code> ...</code><dd>Add directory <var>dirname</var> to the front of the source path. Several |
| directory names may be given to this command, separated by ‘<samp><span class="samp">:</span></samp>’ |
| (‘<samp><span class="samp">;</span></samp>’ on MS-DOS and MS-Windows, where ‘<samp><span class="samp">:</span></samp>’ 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 <span class="sc">gdb</span> searches it sooner. |
| |
| <p><a name="index-cdir-459"></a><a name="index-cwd-460"></a><a name="index-g_t_0024cdir_0040r_007b_002c-convenience-variable_007d-461"></a><a name="index-g_t_0024cwd_0040r_007b_002c-convenience-variable_007d-462"></a><a name="index-compilation-directory-463"></a><a name="index-current-directory-464"></a><a name="index-working-directory-465"></a><a name="index-directory_002c-current-466"></a><a name="index-directory_002c-compilation-467"></a>You can use the string ‘<samp><span class="samp">$cdir</span></samp>’ to refer to the compilation |
| directory (if one is recorded), and ‘<samp><span class="samp">$cwd</span></samp>’ to refer to the current |
| working directory. ‘<samp><span class="samp">$cwd</span></samp>’ is not the same as ‘<samp><span class="samp">.</span></samp>’—the former |
| tracks the current working directory as it changes during your <span class="sc">gdb</span> |
| session, while the latter is immediately expanded to the current |
| directory at the time you add an entry to the source path. |
| |
| <br><dt><code>directory</code><dd>Reset the source path to its default value (‘<samp><span class="samp">$cdir:$cwd</span></samp>’ on Unix systems). This requires confirmation. |
| |
| <!-- RET-repeat for @code{directory} is explicitly disabled, but since --> |
| <!-- repeating it would be a no-op we do not say that. (thanks to RMS) --> |
| <br><dt><code>show directories</code><dd><a name="index-show-directories-468"></a>Print the source path: show which directories it contains. |
| |
| <p><a name="set-substitute_002dpath"></a><br><dt><code>set substitute-path </code><var>from</var> <var>to</var><dd><a name="index-set-substitute_002dpath-469"></a>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</var> was already defined, then the old rule is also deleted. |
| |
| <p>For example, if the file <samp><span class="file">/foo/bar/baz.c</span></samp> was moved to |
| <samp><span class="file">/mnt/cross/baz.c</span></samp>, then the command |
| |
| <pre class="smallexample"> (gdb) set substitute-path /usr/src /mnt/cross |
| </pre> |
| <p class="noindent">will tell <span class="sc">gdb</span> to replace ‘<samp><span class="samp">/usr/src</span></samp>’ with |
| ‘<samp><span class="samp">/mnt/cross</span></samp>’, which will allow <span class="sc">gdb</span> to find the file |
| <samp><span class="file">baz.c</span></samp> even though it was moved. |
| |
| <p>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. |
| |
| <p>For instance, if we had entered the following commands: |
| |
| <pre class="smallexample"> (gdb) set substitute-path /usr/src/include /mnt/include |
| (gdb) set substitute-path /usr/src /mnt/src |
| </pre> |
| <p class="noindent"><span class="sc">gdb</span> would then rewrite <samp><span class="file">/usr/src/include/defs.h</span></samp> into |
| <samp><span class="file">/mnt/include/defs.h</span></samp> by using the first rule. However, it would |
| use the second rule to rewrite <samp><span class="file">/usr/src/lib/foo.c</span></samp> into |
| <samp><span class="file">/mnt/src/lib/foo.c</span></samp>. |
| |
| <br><dt><code>unset substitute-path [path]</code><dd><a name="index-unset-substitute_002dpath-470"></a>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. |
| |
| <p>If no path is specified, then all substitution rules are deleted. |
| |
| <br><dt><code>show substitute-path [path]</code><dd><a name="index-show-substitute_002dpath-471"></a>If a path is specified, then print the source path substitution rule |
| which would rewrite that path, if any. |
| |
| <p>If no path is specified, then print all existing source path substitution |
| rules. |
| |
| </dl> |
| |
| <p>If your source path is cluttered with directories that are no longer of |
| interest, <span class="sc">gdb</span> may sometimes cause confusion by finding the wrong |
| versions of source. You can correct the situation as follows: |
| |
| <ol type=1 start=1> |
| <li>Use <code>directory</code> with no argument to reset the source path to its default value. |
| |
| <li>Use <code>directory</code> with suitable arguments to reinstall the |
| directories you want in the source path. You can add all the |
| directories in one command. |
| </ol> |
| |
| </body></html> |
| |
