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