1<html lang="en"> 2<head> 3<title>Source Path - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Source.html#Source" title="Source"> 9<link rel="prev" href="Search.html#Search" title="Search"> 10<link rel="next" href="Machine-Code.html#Machine-Code" title="Machine Code"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Free Software'' and ``Free Software Needs 21Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 22and with the Back-Cover Texts as in (a) below. 23 24(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 25this GNU Manual. Buying copies from GNU Press supports the FSF in 26developing GNU and promoting software freedom.''--> 27<meta http-equiv="Content-Style-Type" content="text/css"> 28<style type="text/css"><!-- 29 pre.display { font-family:inherit } 30 pre.format { font-family:inherit } 31 pre.smalldisplay { font-family:inherit; font-size:smaller } 32 pre.smallformat { font-family:inherit; font-size:smaller } 33 pre.smallexample { font-size:smaller } 34 pre.smalllisp { font-size:smaller } 35 span.sc { font-variant:small-caps } 36 span.roman { font-family:serif; font-weight:normal; } 37 span.sansserif { font-family:sans-serif; font-weight:normal; } 38--></style> 39<link rel="stylesheet" type="text/css" href="../cs.css"> 40</head> 41<body> 42<div class="node"> 43<a name="Source-Path"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Machine-Code.html#Machine-Code">Machine Code</a>, 46Previous: <a rel="previous" accesskey="p" href="Search.html#Search">Search</a>, 47Up: <a rel="up" accesskey="u" href="Source.html#Source">Source</a> 48<hr> 49</div> 50 51<h3 class="section">9.5 Specifying Source Directories</h3> 52 53<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 54files from which they were compiled, just the names. Even when they do, 55the directories could be moved between the compilation and your debugging 56session. <span class="sc">gdb</span> has a list of directories to search for source files; 57this is called the <dfn>source path</dfn>. Each time <span class="sc">gdb</span> wants a source file, 58it tries all the directories in the list, in the order they are present 59in the list, until it finds a file with the desired name. 60 61 <p>For example, suppose an executable references the file 62<samp><span class="file">/usr/src/foo-1.0/lib/foo.c</span></samp>, and our source path is 63<samp><span class="file">/mnt/cross</span></samp>. The file is first looked up literally; if this 64fails, <samp><span class="file">/mnt/cross/usr/src/foo-1.0/lib/foo.c</span></samp> is tried; if this 65fails, <samp><span class="file">/mnt/cross/foo.c</span></samp> is opened; if this fails, an error 66message is printed. <span class="sc">gdb</span> does not look up the parts of the 67source file name, such as <samp><span class="file">/mnt/cross/src/foo-1.0/lib/foo.c</span></samp>. 68Likewise, the subdirectories of the source path are not searched: if 69the source path is <samp><span class="file">/mnt/cross</span></samp>, and the binary refers to 70<samp><span class="file">foo.c</span></samp>, <span class="sc">gdb</span> would not find it under 71<samp><span class="file">/mnt/cross/usr/src/foo-1.0/lib</span></samp>. 72 73 <p>Plain file names, relative file names with leading directories, file 74names containing dots, etc. are all treated as described above; for 75instance, if the source path is <samp><span class="file">/mnt/cross</span></samp>, and the source file 76is recorded as <samp><span class="file">../lib/foo.c</span></samp>, <span class="sc">gdb</span> would first try 77<samp><span class="file">../lib/foo.c</span></samp>, then <samp><span class="file">/mnt/cross/../lib/foo.c</span></samp>, and after 78that—<samp><span class="file">/mnt/cross/foo.c</span></samp>. 79 80 <p>Note that the executable search path is <em>not</em> used to locate the 81source files. 82 83 <p>Whenever you reset or rearrange the source path, <span class="sc">gdb</span> clears out 84any information it has cached about where source files are found and where 85each line is in the file. 86 87 <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>’ 88and ‘<samp><span class="samp">cwd</span></samp>’, in that order. 89To add other directories, use the <code>directory</code> command. 90 91 <p>The search path is used to find both program source files and <span class="sc">gdb</span> 92script files (read using the ‘<samp><span class="samp">-command</span></samp>’ option and ‘<samp><span class="samp">source</span></samp>’ command). 93 94 <p>In addition to the source path, <span class="sc">gdb</span> provides a set of commands 95that manage a list of source path substitution rules. A <dfn>substitution 96rule</dfn> specifies how to rewrite source directories stored in the program's 97debug information in case the sources were moved to a different 98directory between compilation and debugging. A rule is made of 99two strings, the first specifying what needs to be rewritten in 100the path, and the second specifying how it should be rewritten. 101In <a href="set-substitute_002dpath.html#set-substitute_002dpath">set substitute-path</a>, we name these two parts <var>from</var> and 102<var>to</var> respectively. <span class="sc">gdb</span> does a simple string replacement 103of <var>from</var> with <var>to</var> at the start of the directory part of the 104source file name, and uses that result instead of the original file 105name to look up the sources. 106 107 <p>Using the previous example, suppose the <samp><span class="file">foo-1.0</span></samp> tree has been 108moved from <samp><span class="file">/usr/src</span></samp> to <samp><span class="file">/mnt/cross</span></samp>, then you can tell 109<span class="sc">gdb</span> to replace <samp><span class="file">/usr/src</span></samp> in all source path names with 110<samp><span class="file">/mnt/cross</span></samp>. The first lookup will then be 111<samp><span class="file">/mnt/cross/foo-1.0/lib/foo.c</span></samp> in place of the original location 112of <samp><span class="file">/usr/src/foo-1.0/lib/foo.c</span></samp>. To define a source path 113substitution rule, use the <code>set substitute-path</code> command 114(see <a href="set-substitute_002dpath.html#set-substitute_002dpath">set substitute-path</a>). 115 116 <p>To avoid unexpected substitution results, a rule is applied only if the 117<var>from</var> part of the directory name ends at a directory separator. 118For instance, a rule substituting <samp><span class="file">/usr/source</span></samp> into 119<samp><span class="file">/mnt/cross</span></samp> will be applied to <samp><span class="file">/usr/source/foo-1.0</span></samp> but 120not to <samp><span class="file">/usr/sourceware/foo-2.0</span></samp>. And because the substitution 121is applied only at the beginning of the directory name, this rule will 122not be applied to <samp><span class="file">/root/usr/source/baz.c</span></samp> either. 123 124 <p>In many cases, you can achieve the same result using the <code>directory</code> 125command. However, <code>set substitute-path</code> can be more efficient in 126the case where the sources are organized in a complex tree with multiple 127subdirectories. With the <code>directory</code> command, you need to add each 128subdirectory of your project. If you moved the entire tree while 129preserving its internal organization, then <code>set substitute-path</code> 130allows you to direct the debugger to all the sources with one single 131command. 132 133 <p><code>set substitute-path</code> is also more than just a shortcut command. 134The source path is only used if the file at the original location no 135longer exists. On the other hand, <code>set substitute-path</code> modifies 136the debugger behavior to look at the rewritten location instead. So, if 137for any reason a source file that is not relevant to your executable is 138located at the original location, a substitution rule is the only 139method available to point <span class="sc">gdb</span> at the new location. 140 141 <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 142configuring <span class="sc">gdb</span> with the 143‘<samp><span class="samp">--with-relocated-sources=</span><var>dir</var></samp>’ option. The <var>dir</var> 144should be the name of a directory under <span class="sc">gdb</span>'s configured 145prefix (set with ‘<samp><span class="samp">--prefix</span></samp>’ or ‘<samp><span class="samp">--exec-prefix</span></samp>’), and 146directory names in debug information under <var>dir</var> will be adjusted 147automatically if the installed <span class="sc">gdb</span> is moved to a new 148location. This is useful if <span class="sc">gdb</span>, libraries or executables 149with debug information and corresponding source code are being moved 150together. 151 152 <dl> 153<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 154directory names may be given to this command, separated by ‘<samp><span class="samp">:</span></samp>’ 155(‘<samp><span class="samp">;</span></samp>’ on MS-DOS and MS-Windows, where ‘<samp><span class="samp">:</span></samp>’ usually appears as 156part of absolute file names) or 157whitespace. You may specify a directory that is already in the source 158path; this moves it forward, so <span class="sc">gdb</span> searches it sooner. 159 160 <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 161directory (if one is recorded), and ‘<samp><span class="samp">$cwd</span></samp>’ to refer to the current 162working directory. ‘<samp><span class="samp">$cwd</span></samp>’ is not the same as ‘<samp><span class="samp">.</span></samp>’—the former 163tracks the current working directory as it changes during your <span class="sc">gdb</span> 164session, while the latter is immediately expanded to the current 165directory at the time you add an entry to the source path. 166 167 <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. 168 169 <!-- RET-repeat for @code{directory} is explicitly disabled, but since --> 170 <!-- repeating it would be a no-op we do not say that. (thanks to RMS) --> 171 <br><dt><code>show directories</code><dd><a name="index-show-directories-468"></a>Print the source path: show which directories it contains. 172 173 <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 174current list of existing substitution rules. If a rule with the same 175<var>from</var> was already defined, then the old rule is also deleted. 176 177 <p>For example, if the file <samp><span class="file">/foo/bar/baz.c</span></samp> was moved to 178<samp><span class="file">/mnt/cross/baz.c</span></samp>, then the command 179 180 <pre class="smallexample"> (gdb) set substitute-path /usr/src /mnt/cross 181</pre> 182 <p class="noindent">will tell <span class="sc">gdb</span> to replace ‘<samp><span class="samp">/usr/src</span></samp>’ with 183‘<samp><span class="samp">/mnt/cross</span></samp>’, which will allow <span class="sc">gdb</span> to find the file 184<samp><span class="file">baz.c</span></samp> even though it was moved. 185 186 <p>In the case when more than one substitution rule have been defined, 187the rules are evaluated one by one in the order where they have been 188defined. The first one matching, if any, is selected to perform 189the substitution. 190 191 <p>For instance, if we had entered the following commands: 192 193 <pre class="smallexample"> (gdb) set substitute-path /usr/src/include /mnt/include 194 (gdb) set substitute-path /usr/src /mnt/src 195</pre> 196 <p class="noindent"><span class="sc">gdb</span> would then rewrite <samp><span class="file">/usr/src/include/defs.h</span></samp> into 197<samp><span class="file">/mnt/include/defs.h</span></samp> by using the first rule. However, it would 198use the second rule to rewrite <samp><span class="file">/usr/src/lib/foo.c</span></samp> into 199<samp><span class="file">/mnt/src/lib/foo.c</span></samp>. 200 201 <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 202for a rule that would rewrite that path. Delete that rule if found. 203A warning is emitted by the debugger if no rule could be found. 204 205 <p>If no path is specified, then all substitution rules are deleted. 206 207 <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 208which would rewrite that path, if any. 209 210 <p>If no path is specified, then print all existing source path substitution 211rules. 212 213 </dl> 214 215 <p>If your source path is cluttered with directories that are no longer of 216interest, <span class="sc">gdb</span> may sometimes cause confusion by finding the wrong 217versions of source. You can correct the situation as follows: 218 219 <ol type=1 start=1> 220<li>Use <code>directory</code> with no argument to reset the source path to its default value. 221 222 <li>Use <code>directory</code> with suitable arguments to reinstall the 223directories you want in the source path. You can add all the 224directories in one command. 225 </ol> 226 227 </body></html> 228 229