1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Source Path</title> 18 19<meta name="description" content="Debugging with GDB: Source Path"> 20<meta name="keywords" content="Debugging with GDB: Source Path"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Source.html#Source" rel="up" title="Source"> 29<link href="Machine-Code.html#Machine-Code" rel="next" title="Machine Code"> 30<link href="Search.html#Search" rel="previous" title="Search"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Source-Path"></a> 65<div class="header"> 66<p> 67Next: <a href="Machine-Code.html#Machine-Code" accesskey="n" rel="next">Machine Code</a>, Previous: <a href="Search.html#Search" accesskey="p" rel="previous">Search</a>, Up: <a href="Source.html#Source" accesskey="u" rel="up">Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Specifying-Source-Directories"></a> 71<h3 class="section">9.5 Specifying Source Directories</h3> 72 73<a name="index-source-path"></a> 74<a name="index-directories-for-source-files"></a> 75<p>Executable programs sometimes do not record the directories of the source 76files from which they were compiled, just the names. Even when they do, 77the directories could be moved between the compilation and your debugging 78session. <small>GDB</small> has a list of directories to search for source files; 79this is called the <em>source path</em>. Each time <small>GDB</small> wants a source file, 80it tries all the directories in the list, in the order they are present 81in the list, until it finds a file with the desired name. 82</p> 83<p>For example, suppose an executable references the file 84<samp>/usr/src/foo-1.0/lib/foo.c</samp>, does not record a compilation 85directory, and the <em>source path</em> is <samp>/mnt/cross</samp>. 86<small>GDB</small> would look for the source file in the following 87locations: 88</p> 89<ol> 90<li> <samp>/usr/src/foo-1.0/lib/foo.c</samp> 91</li><li> <samp>/mnt/cross/usr/src/foo-1.0/lib/foo.c</samp> 92</li><li> <samp>/mnt/cross/foo.c</samp> 93 94</li></ol> 95 96<p>If the source file is not present at any of the above locations then 97an error is printed. <small>GDB</small> does not look up the parts of the 98source file name, such as <samp>/mnt/cross/src/foo-1.0/lib/foo.c</samp>. 99Likewise, the subdirectories of the source path are not searched: if 100the source path is <samp>/mnt/cross</samp>, and the binary refers to 101<samp>foo.c</samp>, <small>GDB</small> would not find it under 102<samp>/mnt/cross/usr/src/foo-1.0/lib</samp>. 103</p> 104<p>Plain file names, relative file names with leading directories, file 105names containing dots, etc. are all treated as described above, 106except that non-absolute file names are not looked up literally. If 107the <em>source path</em> is <samp>/mnt/cross</samp>, the source file is 108recorded as <samp>../lib/foo.c</samp>, and no compilation directory is 109recorded, then <small>GDB</small> will search in the following locations: 110</p> 111<ol> 112<li> <samp>/mnt/cross/../lib/foo.c</samp> 113</li><li> <samp>/mnt/cross/foo.c</samp> 114 115</li></ol> 116 117<a name="index-cdir"></a> 118<a name="index-cwd"></a> 119<a name="index-_0024cdir_002c-convenience-variable"></a> 120<a name="index-_0024cwd_002c-convenience-variable"></a> 121<a name="index-compilation-directory"></a> 122<a name="index-current-directory"></a> 123<a name="index-working-directory"></a> 124<a name="index-directory_002c-current"></a> 125<a name="index-directory_002c-compilation"></a> 126<p>The <em>source path</em> will always include two special entries 127‘<samp>$cdir</samp>’ and ‘<samp>$cwd</samp>’, these refer to the compilation directory 128(if one is recorded) and the current working directory respectively. 129</p> 130<p>‘<samp>$cdir</samp>’ causes <small>GDB</small> to search within the compilation 131directory, if one is recorded in the debug information. If no 132compilation directory is recorded in the debug information then 133‘<samp>$cdir</samp>’ is ignored. 134</p> 135<p>‘<samp>$cwd</samp>’ is not the same as ‘<samp>.</samp>’—the former tracks the 136current working directory as it changes during your <small>GDB</small> 137session, while the latter is immediately expanded to the current 138directory at the time you add an entry to the source path. 139</p> 140<p>If a compilation directory is recorded in the debug information, and 141<small>GDB</small> has not found the source file after the first search 142using <em>source path</em>, then <small>GDB</small> will combine the 143compilation directory and the filename, and then search for the source 144file again using the <em>source path</em>. 145</p> 146<p>For example, if the executable records the source file as 147<samp>/usr/src/foo-1.0/lib/foo.c</samp>, the compilation directory is 148recorded as <samp>/project/build</samp>, and the <em>source path</em> is 149<samp>/mnt/cross:$cdir:$cwd</samp> while the current working directory of 150the <small>GDB</small> session is <samp>/home/user</samp>, then <small>GDB</small> will 151search for the source file in the following locations: 152</p> 153<ol> 154<li> <samp>/usr/src/foo-1.0/lib/foo.c</samp> 155</li><li> <samp>/mnt/cross/usr/src/foo-1.0/lib/foo.c</samp> 156</li><li> <samp>/project/build/usr/src/foo-1.0/lib/foo.c</samp> 157</li><li> <samp>/home/user/usr/src/foo-1.0/lib/foo.c</samp> 158</li><li> <samp>/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c</samp> 159</li><li> <samp>/project/build/project/build/usr/src/foo-1.0/lib/foo.c</samp> 160</li><li> <samp>/home/user/project/build/usr/src/foo-1.0/lib/foo.c</samp> 161</li><li> <samp>/mnt/cross/foo.c</samp> 162</li><li> <samp>/project/build/foo.c</samp> 163</li><li> <samp>/home/user/foo.c</samp> 164 165</li></ol> 166 167<p>If the file name in the previous example had been recorded in the 168executable as a relative path rather than an absolute path, then the 169first look up would not have occurred, but all of the remaining steps 170would be similar. 171</p> 172<p>When searching for source files on MS-DOS and MS-Windows, where 173absolute paths start with a drive letter (e.g. 174<samp>C:/project/foo.c</samp>), <small>GDB</small> will remove the drive letter 175from the file name before appending it to a search directory from 176<em>source path</em>; for instance if the executable references the 177source file <samp>C:/project/foo.c</samp> and <em>source path</em> is set to 178<samp>D:/mnt/cross</samp>, then <small>GDB</small> will search in the following 179locations for the source file: 180</p> 181<ol> 182<li> <samp>C:/project/foo.c</samp> 183</li><li> <samp>D:/mnt/cross/project/foo.c</samp> 184</li><li> <samp>D:/mnt/cross/foo.c</samp> 185 186</li></ol> 187 188<p>Note that the executable search path is <em>not</em> used to locate the 189source files. 190</p> 191<p>Whenever you reset or rearrange the source path, <small>GDB</small> clears out 192any information it has cached about where source files are found and where 193each line is in the file. 194</p> 195<a name="index-directory"></a> 196<a name="index-dir"></a> 197<p>When you start <small>GDB</small>, its source path includes only ‘<samp>$cdir</samp>’ 198and ‘<samp>$cwd</samp>’, in that order. 199To add other directories, use the <code>directory</code> command. 200</p> 201<p>The search path is used to find both program source files and <small>GDB</small> 202script files (read using the ‘<samp>-command</samp>’ option and ‘<samp>source</samp>’ command). 203</p> 204<p>In addition to the source path, <small>GDB</small> provides a set of commands 205that manage a list of source path substitution rules. A <em>substitution 206rule</em> specifies how to rewrite source directories stored in the program’s 207debug information in case the sources were moved to a different 208directory between compilation and debugging. A rule is made of 209two strings, the first specifying what needs to be rewritten in 210the path, and the second specifying how it should be rewritten. 211In <a href="#set-substitute_002dpath">set substitute-path</a>, we name these two parts <var>from</var> and 212<var>to</var> respectively. <small>GDB</small> does a simple string replacement 213of <var>from</var> with <var>to</var> at the start of the directory part of the 214source file name, and uses that result instead of the original file 215name to look up the sources. 216</p> 217<p>Using the previous example, suppose the <samp>foo-1.0</samp> tree has been 218moved from <samp>/usr/src</samp> to <samp>/mnt/cross</samp>, then you can tell 219<small>GDB</small> to replace <samp>/usr/src</samp> in all source path names with 220<samp>/mnt/cross</samp>. The first lookup will then be 221<samp>/mnt/cross/foo-1.0/lib/foo.c</samp> in place of the original location 222of <samp>/usr/src/foo-1.0/lib/foo.c</samp>. To define a source path 223substitution rule, use the <code>set substitute-path</code> command 224(see <a href="#set-substitute_002dpath">set substitute-path</a>). 225</p> 226<p>To avoid unexpected substitution results, a rule is applied only if the 227<var>from</var> part of the directory name ends at a directory separator. 228For instance, a rule substituting <samp>/usr/source</samp> into 229<samp>/mnt/cross</samp> will be applied to <samp>/usr/source/foo-1.0</samp> but 230not to <samp>/usr/sourceware/foo-2.0</samp>. And because the substitution 231is applied only at the beginning of the directory name, this rule will 232not be applied to <samp>/root/usr/source/baz.c</samp> either. 233</p> 234<p>In many cases, you can achieve the same result using the <code>directory</code> 235command. However, <code>set substitute-path</code> can be more efficient in 236the case where the sources are organized in a complex tree with multiple 237subdirectories. With the <code>directory</code> command, you need to add each 238subdirectory of your project. If you moved the entire tree while 239preserving its internal organization, then <code>set substitute-path</code> 240allows you to direct the debugger to all the sources with one single 241command. 242</p> 243<p><code>set substitute-path</code> is also more than just a shortcut command. 244The source path is only used if the file at the original location no 245longer exists. On the other hand, <code>set substitute-path</code> modifies 246the debugger behavior to look at the rewritten location instead. So, if 247for any reason a source file that is not relevant to your executable is 248located at the original location, a substitution rule is the only 249method available to point <small>GDB</small> at the new location. 250</p> 251<a name="index-_002d_002dwith_002drelocated_002dsources"></a> 252<a name="index-default-source-path-substitution"></a> 253<p>You can configure a default source path substitution rule by 254configuring <small>GDB</small> with the 255‘<samp>--with-relocated-sources=<var>dir</var></samp>’ option. The <var>dir</var> 256should be the name of a directory under <small>GDB</small>’s configured 257prefix (set with ‘<samp>--prefix</samp>’ or ‘<samp>--exec-prefix</samp>’), and 258directory names in debug information under <var>dir</var> will be adjusted 259automatically if the installed <small>GDB</small> is moved to a new 260location. This is useful if <small>GDB</small>, libraries or executables 261with debug information and corresponding source code are being moved 262together. 263</p> 264<dl compact="compact"> 265<dt><code>directory <var>dirname</var> …</code></dt> 266<dt><code>dir <var>dirname</var> …</code></dt> 267<dd><p>Add directory <var>dirname</var> to the front of the source path. Several 268directory names may be given to this command, separated by ‘<samp>:</samp>’ 269(‘<samp>;</samp>’ on MS-DOS and MS-Windows, where ‘<samp>:</samp>’ usually appears as 270part of absolute file names) or 271whitespace. You may specify a directory that is already in the source 272path; this moves it forward, so <small>GDB</small> searches it sooner. 273</p> 274<p>The special strings ‘<samp>$cdir</samp>’ (to refer to the compilation 275directory, if one is recorded), and ‘<samp>$cwd</samp>’ (to refer to the 276current working directory) can also be included in the list of 277directories <var>dirname</var>. Though these will already be in the source 278path they will be moved forward in the list so <small>GDB</small> searches 279them sooner. 280</p> 281</dd> 282<dt><code>directory</code></dt> 283<dd><p>Reset the source path to its default value (‘<samp>$cdir:$cwd</samp>’ on Unix systems). This requires confirmation. 284</p> 285 286</dd> 287<dt><code>set directories <var>path-list</var></code></dt> 288<dd><a name="index-set-directories"></a> 289<p>Set the source path to <var>path-list</var>. 290‘<samp>$cdir:$cwd</samp>’ are added if missing. 291</p> 292</dd> 293<dt><code>show directories</code></dt> 294<dd><a name="index-show-directories"></a> 295<p>Print the source path: show which directories it contains. 296</p> 297<a name="set-substitute_002dpath"></a></dd> 298<dt><code>set substitute-path <var>from</var> <var>to</var></code></dt> 299<dd><a name="index-set-substitute_002dpath"></a> 300<p>Define a source path substitution rule, and add it at the end of the 301current list of existing substitution rules. If a rule with the same 302<var>from</var> was already defined, then the old rule is also deleted. 303</p> 304<p>For example, if the file <samp>/foo/bar/baz.c</samp> was moved to 305<samp>/mnt/cross/baz.c</samp>, then the command 306</p> 307<div class="smallexample"> 308<pre class="smallexample">(gdb) set substitute-path /foo/bar /mnt/cross 309</pre></div> 310 311<p>will tell <small>GDB</small> to replace ‘<samp>/foo/bar</samp>’ with 312‘<samp>/mnt/cross</samp>’, which will allow <small>GDB</small> to find the file 313<samp>baz.c</samp> even though it was moved. 314</p> 315<p>In the case when more than one substitution rule have been defined, 316the rules are evaluated one by one in the order where they have been 317defined. The first one matching, if any, is selected to perform 318the substitution. 319</p> 320<p>For instance, if we had entered the following commands: 321</p> 322<div class="smallexample"> 323<pre class="smallexample">(gdb) set substitute-path /usr/src/include /mnt/include 324(gdb) set substitute-path /usr/src /mnt/src 325</pre></div> 326 327<p><small>GDB</small> would then rewrite <samp>/usr/src/include/defs.h</samp> into 328<samp>/mnt/include/defs.h</samp> by using the first rule. However, it would 329use the second rule to rewrite <samp>/usr/src/lib/foo.c</samp> into 330<samp>/mnt/src/lib/foo.c</samp>. 331</p> 332 333</dd> 334<dt><code>unset substitute-path [path]</code></dt> 335<dd><a name="index-unset-substitute_002dpath"></a> 336<p>If a path is specified, search the current list of substitution rules 337for a rule that would rewrite that path. Delete that rule if found. 338A warning is emitted by the debugger if no rule could be found. 339</p> 340<p>If no path is specified, then all substitution rules are deleted. 341</p> 342</dd> 343<dt><code>show substitute-path [path]</code></dt> 344<dd><a name="index-show-substitute_002dpath"></a> 345<p>If a path is specified, then print the source path substitution rule 346which would rewrite that path, if any. 347</p> 348<p>If no path is specified, then print all existing source path substitution 349rules. 350</p> 351</dd> 352</dl> 353 354<p>If your source path is cluttered with directories that are no longer of 355interest, <small>GDB</small> may sometimes cause confusion by finding the wrong 356versions of source. You can correct the situation as follows: 357</p> 358<ol> 359<li> Use <code>directory</code> with no argument to reset the source path to its default value. 360 361</li><li> Use <code>directory</code> with suitable arguments to reinstall the 362directories you want in the source path. You can add all the 363directories in one command. 364</li></ol> 365 366<hr> 367<div class="header"> 368<p> 369Next: <a href="Machine-Code.html#Machine-Code" accesskey="n" rel="next">Machine Code</a>, Previous: <a href="Search.html#Search" accesskey="p" rel="previous">Search</a>, Up: <a href="Source.html#Source" accesskey="u" rel="up">Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 370</div> 371 372 373 374</body> 375</html> 376