doc/user/troubleshoot.sgml

   1 <!--
   2
   3   __COPYRIGHT__
   4
   5   Permission is hereby granted, free of charge, to any person obtaining
   6   a copy of this software and associated documentation files (the
   7   "Software"), to deal in the Software without restriction, including
   8   without limitation the rights to use, copy, modify, merge, publish,
   9   distribute, sublicense, and/or sell copies of the Software, and to
  10   permit persons to whom the Software is furnished to do so, subject to
  11   the following conditions:
  12
  13   The above copyright notice and this permission notice shall be included
  14   in all copies or substantial portions of the Software.
  15
  16   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  17   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  18   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20   LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 -->
  25
  26   <para>
  27
  28   The experience of configuring any
  29   software build tool to build a large code base
  30   usually, at some point,
  31   involves trying to figure out why
  32   the tool is behaving a certain way,
  33   and how to get it to behave the way you want.
  34   &SCons; is no different.
  35   This appendix contains a number of
  36   different ways in which you can
  37   get some additional insight into &SCons;' behavior.
  38
  39   </para>
  40
  41   <para>
  42
  43   Note that we're always interested in trying to
  44   improve how you can troubleshoot configuration problems.
  45   If you run into a problem that has
  46   you scratching your head,
  47   and which there just doesn't seem to be a good way to debug,
  48   odds are pretty good that someone else will run into
  49   the same problem, too.
  50   If so, please let the SCons development team know
  51   (preferably by filing a bug report
  52   or feature request at our project pages at tigris.org)
  53   so that we can use your feedback
  54   to try to come up with a better way to help you,
  55   and others, get the necessary insight into &SCons; behavior
  56   to help identify and fix configuration issues.
  57
  58   </para>
  59
  60   <section>
  61   <title>Why is That Target Being Rebuilt?  the &debug-explain; Option</title>
  62
  63     <para>
  64
  65     Let's look at a simple example of
  66     a misconfigured build
  67     that causes a target to be rebuilt
  68     every time &SCons; is run:
  69
  70     </para>
  71
  72     <programlisting>
  73       # Intentionally misspell the output file name in the
  74       # command used to create the file:
  75       Command('file.out', 'file.in', 'cp $SOURCE file.oout')
  76     </programlisting>
  77
  78     <para>
  79
  80     (Note to Windows users:  The POSIX &cp; command
  81     copies the first file named on the command line
  82     to the second file.
  83     In our example, it copies the &file_in; file
  84     to the &file_out; file.)
  85
  86     </para>
  87
  88     <para>
  89
  90     Now if we run &SCons; multiple times on this example,
  91     we see that it re-runs the &cp;
  92     command every time:
  93
  94     </para>
  95
  96     <screen>
  97       % <userinput>scons -Q</userinput>
  98       cp file.in file.oout
  99       % <userinput>scons -Q</userinput>
 100       cp file.in file.oout
 101       % <userinput>scons -Q</userinput>
 102       cp file.in file.oout
 103     </screen>
 104
 105     <para>
 106
 107     In this example,
 108     the underlying cause is obvious:
 109     we've intentionally misspelled the output file name
 110     in the &cp; command,
 111     so the command doesn't actually
 112     build the &file_out; file that we've told &SCons; to expect.
 113     But if the problem weren't obvious,
 114     it would be helpful
 115     to specify the &debug-explain; option
 116     on the command line
 117     to have &SCons; tell us very specifically
 118     why it's decided to rebuild the target:
 119
 120     </para>
 121
 122     <screen>
 123       % <userinput>scons -Q --debug=explain</userinput>
 124       scons: building `file.out' because it doesn't exist
 125       cp file.in file.oout
 126     </screen>
 127
 128     <para>
 129
 130     If this had been a more complicated example
 131     involving a lot of build output,
 132     having &SCons; tell us that
 133     it's trying to rebuild the target file
 134     because it doesn't exist
 135     would be an important clue
 136     that something was wrong with
 137     the command that we invoked to build it.
 138
 139     </para>
 140
 141     <para>
 142
 143     The &debug-explain; option also comes in handy
 144     to help figure out what input file changed.
 145     Given a simple configuration that builds
 146     a program from three source files,
 147     changing one of the source files
 148     and rebuilding with the &debug-explain;
 149     option shows very specifically
 150     why &SCons; rebuilds the files that it does:
 151
 152     </para>
 153
 154
 155
 156     <screen>
 157       % <userinput>scons -Q</userinput>
 158       cc -o file1.o -c file1.c
 159       cc -o file2.o -c file2.c
 160       cc -o file3.o -c file3.c
 161       cc -o prog file1.o file2.o file3.o
 162       % <userinput>edit file2.c</userinput>
 163           [CHANGE THE CONTENTS OF file2.c]
 164       % <userinput>scons -Q --debug=explain</userinput>
 165       scons: rebuilding `file2.o' because `file2.c' changed
 166       cc -o file2.o -c file2.c
 167       scons: rebuilding `prog' because `file2.o' changed
 168       cc -o prog file1.o file2.o file3.o
 169     </screen>
 170
 171     <para>
 172
 173     This becomes even more helpful
 174     in identifying when a file is rebuilt
 175     due to a change in an implicit dependency,
 176     such as an incuded <filename>.h</filename> file.
 177     If the <filename>file1.c</filename>
 178     and <filename>file3.c</filename> files
 179     in our example
 180     both included a &hello_h; file,
 181     then changing that included file
 182     and re-running &SCons; with the &debug-explain; option
 183     will pinpoint that it's the change to the included file
 184     that starts the chain of rebuilds:
 185
 186     </para>
 187
 188
 189
 190     <screen>
 191       % <userinput>scons -Q</userinput>
 192       cc -o file1.o -c -I. file1.c
 193       cc -o file2.o -c -I. file2.c
 194       cc -o file3.o -c -I. file3.c
 195       cc -o prog file1.o file2.o file3.o
 196       % <userinput>edit hello.h</userinput>
 197           [CHANGE THE CONTENTS OF hello.h]
 198       % <userinput>scons -Q --debug=explain</userinput>
 199       scons: rebuilding `file1.o' because `hello.h' changed
 200       cc -o file1.o -c -I. file1.c
 201       scons: rebuilding `file3.o' because `hello.h' changed
 202       cc -o file3.o -c -I. file3.c
 203       scons: rebuilding `prog' because:
 204                  `file1.o' changed
 205                  `file3.o' changed
 206       cc -o prog file1.o file2.o file3.o
 207     </screen>
 208
 209     <para>
 210
 211     (Note that the &debug-explain; option will only tell you
 212     why &SCons; decided to rebuild necessary targets.
 213     It does not tell you what files it examined
 214     when deciding <emphasis>not</emphasis>
 215     to rebuild a target file,
 216     which is often a more valuable question to answer.)
 217
 218     </para>
 219
 220   </section>
 221
 222   <section>
 223   <title>What's in That Construction Environment?  the &Dump; Method</title>
 224
 225     <para>
 226
 227     When you create a construction environment,
 228     &SCons; populates it
 229     with construction variables that are set up
 230     for various compilers, linkers and utilities
 231     that it finds on your system.
 232     Although this is usually helpful and what you want,
 233     it might be frustrating if &SCons;
 234     doesn't set certain variables that you
 235     expect to be sit.
 236     In situations like this,
 237     it's sometimes helpful to use the
 238     construction environment &Dump; method
 239     to print all or some of
 240     the construction variables.
 241     Note that the &Dump; method
 242     <emphasis>returns</emphasis>
 243     the representation of the variables
 244     in the environment
 245     for you to print (or otherwise manipulate):
 246
 247     </para>
 248
 249     <programlisting>
 250          env = Environment()
 251          print env.Dump()
 252     </programlisting>
 253
 254     <para>
 255
 256     On a POSIX system with gcc installed,
 257     this might generate:
 258
 259     </para>
 260
 261     <screen>
 262       % <userinput>scons</userinput>
 263       scons: Reading SConscript files ...
 264       { 'BUILDERS': {},
 265         'CONFIGUREDIR': '#/.sconf_temp',
 266         'CONFIGURELOG': '#/config.log',
 267         'CPPSUFFIXES': [ '.c',
 268                          '.C',
 269                          '.cxx',
 270                          '.cpp',
 271                          '.c++',
 272                          '.cc',
 273                          '.h',
 274                          '.H',
 275                          '.hxx',
 276                          '.hpp',
 277                          '.hh',
 278                          '.F',
 279                          '.fpp',
 280                          '.FPP',
 281                          '.m',
 282                          '.mm',
 283                          '.S',
 284                          '.spp',
 285                          '.SPP'],
 286         'DSUFFIXES': ['.d'],
 287         'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fdac&gt;,
 288         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fdcc&gt;,
 289         'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
 290         'ESCAPE': &lt;function escape at 0xb7ba1f0c&gt;,
 291         'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fdec&gt;,
 292         'IDLSUFFIXES': ['.idl', '.IDL'],
 293         'INSTALL': &lt;function installFunc at 0xb7c4317c&gt;,
 294         'INSTALLSTR': &lt;function installStr at 0xb7c431b4&gt;,
 295         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
 296         'LIBPREFIX': 'lib',
 297         'LIBPREFIXES': '$LIBPREFIX',
 298         'LIBSUFFIX': '.a',
 299         'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'],
 300         'MAXLINELENGTH': 128072,
 301         'OBJPREFIX': '',
 302         'OBJSUFFIX': '.o',
 303         'PLATFORM': 'posix',
 304         'PROGPREFIX': '',
 305         'PROGSUFFIX': '',
 306         'PSPAWN': &lt;function piped_env_spawn at 0xb7bb12cc&gt;,
 307         'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c3fe0c&gt;,
 308         'SCANNERS': [],
 309         'SHELL': 'sh',
 310         'SHLIBPREFIX': '$LIBPREFIX',
 311         'SHLIBSUFFIX': '.so',
 312         'SHOBJPREFIX': '$OBJPREFIX',
 313         'SHOBJSUFFIX': '$OBJSUFFIX',
 314         'SPAWN': &lt;function spawnvpe_spawn at 0xb7ba1d4c&gt;,
 315         'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7bce89c&gt;,
 316         'TEMPFILEPREFIX': '@',
 317         'TOOLS': [],
 318         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
 319         '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 320         '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 321         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
 322         '__RPATH': '$_RPATH',
 323         '_concat': &lt;function _concat at 0xb7c43224&gt;,
 324         '_defines': &lt;function _defines at 0xb7c432cc&gt;,
 325         '_installStr': &lt;function installStr at 0xb7c431b4&gt;,
 326         '_stripixes': &lt;function _stripixes at 0xb7c43294&gt;}
 327       scons: done reading SConscript files.
 328       scons: Building targets ...
 329       scons: `.' is up to date.
 330       scons: done building targets.
 331     </screen>
 332
 333     <para>
 334
 335     On a Windows system with Visual C++
 336     the output might look like:
 337
 338     </para>
 339
 340     <screen>
 341       C:\><userinput>scons</userinput>
 342       scons: Reading SConscript files ...
 343       { 'BUILDERS': {'Object': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6354c&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b636cc&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6354c&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0xb7bd6e8c&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0xb7b5b9ec&gt;},
 344         'CC': 'cl',
 345         'CCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b63b6c&gt;,
 346         'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS',
 347         'CCFLAGS': ['/nologo'],
 348         'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'],
 349         'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'],
 350         'CFILESUFFIX': '.c',
 351         'CFLAGS': [],
 352         'CONFIGUREDIR': '#/.sconf_temp',
 353         'CONFIGURELOG': '#/config.log',
 354         'CPPDEFPREFIX': '/D',
 355         'CPPDEFSUFFIX': '',
 356         'CPPSUFFIXES': [ '.c',
 357                          '.C',
 358                          '.cxx',
 359                          '.cpp',
 360                          '.c++',
 361                          '.cc',
 362                          '.h',
 363                          '.H',
 364                          '.hxx',
 365                          '.hpp',
 366                          '.hh',
 367                          '.F',
 368                          '.fpp',
 369                          '.FPP',
 370                          '.m',
 371                          '.mm',
 372                          '.S',
 373                          '.spp',
 374                          '.SPP'],
 375         'CXX': '$CC',
 376         'CXXCOM': '$CXX $CXXFLAGS $CCCOMFLAGS',
 377         'CXXFILESUFFIX': '.cc',
 378         'CXXFLAGS': ['$CCFLAGS', '$(', '/TP', '$)'],
 379         'DSUFFIXES': ['.d'],
 380         'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5adac&gt;,
 381         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5adcc&gt;,
 382         'ENV': { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
 383                  'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
 384                  'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin',
 385                  'PATHEXT': '.COM;.EXE;.BAT;.CMD',
 386                  'SystemRoot': 'C:/WINDOWS'},
 387         'ESCAPE': &lt;function escape at 0xb7bcf454&gt;,
 388         'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5adec&gt;,
 389         'IDLSUFFIXES': ['.idl', '.IDL'],
 390         'INCPREFIX': '/I',
 391         'INCSUFFIX': '',
 392         'INSTALL': &lt;function installFunc at 0xb7c5e17c&gt;,
 393         'INSTALLSTR': &lt;function installStr at 0xb7c5e1b4&gt;,
 394         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
 395         'LIBPREFIX': '',
 396         'LIBPREFIXES': ['$LIBPREFIX'],
 397         'LIBSUFFIX': '.lib',
 398         'LIBSUFFIXES': ['$LIBSUFFIX'],
 399         'MAXLINELENGTH': 2048,
 400         'MSVS': {'VERSION': '6.0', 'VERSIONS': ['6.0']},
 401         'MSVS_VERSION': '6.0',
 402         'OBJPREFIX': '',
 403         'OBJSUFFIX': '.obj',
 404         'PCHCOM': '$CXX $CXXFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo${TARGETS[1]} /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS',
 405         'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'],
 406         'PLATFORM': 'win32',
 407         'PROGPREFIX': '',
 408         'PROGSUFFIX': '.exe',
 409         'PSPAWN': &lt;function piped_spawn at 0xb7bcf3ac&gt;,
 410         'RC': 'rc',
 411         'RCCOM': '$RC $_CPPDEFFLAGS $_CPPINCFLAGS $RCFLAGS /fo$TARGET $SOURCES',
 412         'RCFLAGS': [],
 413         'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c5ae0c&gt;,
 414         'SCANNERS': [],
 415         'SHCC': '$CC',
 416         'SHCCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b63bcc&gt;,
 417         'SHCCFLAGS': ['$CCFLAGS'],
 418         'SHCFLAGS': ['$CFLAGS'],
 419         'SHCXX': '$CXX',
 420         'SHCXXCOM': '$SHCXX $SHCXXFLAGS $CCCOMFLAGS',
 421         'SHCXXFLAGS': ['$CXXFLAGS'],
 422         'SHELL': None,
 423         'SHLIBPREFIX': '',
 424         'SHLIBSUFFIX': '.dll',
 425         'SHOBJPREFIX': '$OBJPREFIX',
 426         'SHOBJSUFFIX': '$OBJSUFFIX',
 427         'SPAWN': &lt;function spawn at 0xb7bcf41c&gt;,
 428         'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1,
 429         'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7be989c&gt;,
 430         'TEMPFILEPREFIX': '@',
 431         'TOOLS': ['msvc'],
 432         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
 433         '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 434         '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 435         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
 436         '_concat': &lt;function _concat at 0xb7c5e224&gt;,
 437         '_defines': &lt;function _defines at 0xb7c5e2cc&gt;,
 438         '_installStr': &lt;function installStr at 0xb7c5e1b4&gt;,
 439         '_stripixes': &lt;function _stripixes at 0xb7c5e294&gt;}
 440       scons: done reading SConscript files.
 441       scons: Building targets ...
 442       scons: `.' is up to date.
 443       scons: done building targets.
 444     </screen>
 445
 446     <para>
 447
 448     The construction environments in these examples have
 449     actually been restricted to just gcc and Visual C++,
 450     respectively.
 451     In a real-life situation,
 452     the construction environments will
 453     likely contain a great many more variables.
 454
 455     </para>
 456
 457     <para>
 458
 459     To make it easier to see just what you're
 460     interested in,
 461     the &Dump; method allows you to
 462     specify a specific constrcution variable
 463     that you want to disply.
 464     For example,
 465     it's not unusual to want to verify
 466     the external environment used to execute build commands,
 467     to make sure that the PATH and other
 468     environment variables are set up the way they should be.
 469     You can do this as follows:
 470
 471     </para>
 472
 473     <programlisting>
 474          env = Environment()
 475          print env.Dump('ENV')
 476     </programlisting>
 477
 478     <para>
 479
 480     Which might display the following when executed on a POSIX system:
 481
 482     </para>
 483
 484     <screen>
 485       % <userinput>scons</userinput>
 486       scons: Reading SConscript files ...
 487       {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}
 488       scons: done reading SConscript files.
 489       scons: Building targets ...
 490       scons: `.' is up to date.
 491       scons: done building targets.
 492     </screen>
 493
 494     <para>
 495
 496     And the following when executed on a Windows system:
 497
 498     </para>
 499
 500     <screen>
 501       C:\><userinput>scons</userinput>
 502       scons: Reading SConscript files ...
 503       { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
 504         'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
 505         'PATH': 'C:\\Program Files\\Microsoft Visual Studio\\Common\\tools\\WIN95;C:\\Program Files\\Microsoft Visual Studio\\Common\\MSDev98\\bin;C:\\Program Files\\Microsoft Visual Studio\\Common\\tools;C:\\Program Files\\Microsoft Visual Studio/VC98\\bin',
 506         'PATHEXT': '.COM;.EXE;.BAT;.CMD',
 507         'SystemRoot': 'C:/WINDOWS'}
 508       scons: done reading SConscript files.
 509       scons: Building targets ...
 510       scons: `.' is up to date.
 511       scons: done building targets.
 512     </screen>
 513
 514   </section>
 515
 516   <section>
 517
 518   <title>What Dependencies Does &SCons; Know About?  the &tree; Option</title>
 519
 520     <para>
 521
 522     Sometimes the best way to try to figure out what
 523     &SCons; is doing is simply to take a look at the
 524     dependency graph that it constructs
 525     based on your &SConscript; files.
 526     The <literal>--tree</literal> option
 527     will display all or part of the
 528     &SCons; dependency graph in an
 529     "ASCII art" graphical format
 530     that shows the dependency hierarchy.
 531
 532     </para>
 533
 534     <para>
 535
 536     For example, given the following input &SConstruct; file:
 537
 538     </para>
 539
 540     <programlisting>
 541          env = Environment(CPPPATH = ['.'])
 542          env.Program('prog', ['f1.c', 'f2.c', 'f3.c'])
 543     </programlisting>
 544
 545     <para>
 546
 547     Running &SCons; with the <literal>--tree=all</literal>
 548     option yields:
 549
 550     </para>
 551
 552     <screen>
 553       % <userinput>scons -Q --tree=all</userinput>
 554       cc -o f1.o -c -I. f1.c
 555       cc -o f2.o -c -I. f2.c
 556       cc -o f3.o -c -I. f3.c
 557       cc -o prog f1.o f2.o f3.o
 558       +-.
 559         +--
 560         +-SConstruct
 561         +-f1.c
 562         +-f1.o
 563         | +-f1.c
 564         | +-inc.h
 565         +-f2.c
 566         +-f2.o
 567         | +-f2.c
 568         | +-inc.h
 569         +-f3.c
 570         +-f3.o
 571         | +-f3.c
 572         | +-inc.h
 573         +-inc.h
 574         +-prog
 575           +-f1.o
 576           | +-f1.c
 577           | +-inc.h
 578           +-f2.o
 579           | +-f2.c
 580           | +-inc.h
 581           +-f3.o
 582             +-f3.c
 583             +-inc.h
 584     </screen>
 585
 586     <para>
 587
 588     The tree will also be printed when the
 589     <literal>-n</literal> (no execute) option is used,
 590     which allows you to examine the dependency graph
 591     for a configuration without actually
 592     rebuilding anything in the tree.
 593
 594     </para>
 595
 596     <para>
 597
 598     The <literal>--tree</literal> option only prints
 599     the dependency graph for the specified targets
 600     (or the default target(s) if none are specified on the command line).
 601     So if you specify a target like <filename>f2.o</filename>
 602     on the command line,
 603     the <literal>--tree</literal> option will only
 604     print the dependency graph for that file:
 605
 606     </para>
 607
 608     <screen>
 609       % <userinput>scons -Q --tree=all f2.o</userinput>
 610       cc -o f2.o -c -I. f2.c
 611       +-f2.o
 612         +-f2.c
 613         +-inc.h
 614     </screen>
 615
 616     <para>
 617
 618     This is, of course, useful for
 619     restricting the output from a very large
 620     build configuration to just a
 621     portion in which you're interested.
 622     Multiple targets are fine,
 623     in which case a tree will be printed
 624     for each specified target:
 625
 626     </para>
 627
 628     <screen>
 629       % <userinput>scons -Q --tree=all f1.o f3.o</userinput>
 630       cc -o f1.o -c -I. f1.c
 631       +-f1.o
 632         +-f1.c
 633         +-inc.h
 634       cc -o f3.o -c -I. f3.c
 635       +-f3.o
 636         +-f3.c
 637         +-inc.h
 638     </screen>
 639
 640     <para>
 641
 642     The <literal>status</literal> argument may be used
 643     to tell &SCons; to print status information about
 644     each file in the dependency graph:
 645
 646     </para>
 647
 648     <screen>
 649       % <userinput>scons -Q --tree=status</userinput>
 650       cc -o f1.o -c -I. f1.c
 651       cc -o f2.o -c -I. f2.c
 652       cc -o f3.o -c -I. f3.c
 653       cc -o prog f1.o f2.o f3.o
 654        E         = exists
 655         R        = exists in repository only
 656          b       = implicit builder
 657          B       = explicit builder
 658           S      = side effect
 659            P     = precious
 660             A    = always build
 661              C   = current
 662               N  = no clean
 663                H = no cache
 664
 665       [E b      ]+-.
 666       [         ]  +--
 667       [E        ]  +-SConstruct
 668       [E        ]  +-f1.c
 669       [E B   C  ]  +-f1.o
 670       [E        ]  | +-f1.c
 671       [E        ]  | +-inc.h
 672       [E        ]  +-f2.c
 673       [E B   C  ]  +-f2.o
 674       [E        ]  | +-f2.c
 675       [E        ]  | +-inc.h
 676       [E        ]  +-f3.c
 677       [E B   C  ]  +-f3.o
 678       [E        ]  | +-f3.c
 679       [E        ]  | +-inc.h
 680       [E        ]  +-inc.h
 681       [E B   C  ]  +-prog
 682       [E B   C  ]    +-f1.o
 683       [E        ]    | +-f1.c
 684       [E        ]    | +-inc.h
 685       [E B   C  ]    +-f2.o
 686       [E        ]    | +-f2.c
 687       [E        ]    | +-inc.h
 688       [E B   C  ]    +-f3.o
 689       [E        ]      +-f3.c
 690       [E        ]      +-inc.h
 691     </screen>
 692
 693     <para>
 694
 695     Note that <literal>--tree=all,status</literal> is equivalent;
 696     the <literal>all</literal>
 697     is assumed if only <literal>status</literal> is present.
 698     As an alternative to <literal>all</literal>,
 699     you can specify <literal>--tree=derived</literal>
 700     to have &SCons; only print derived targets
 701     in the tree output,
 702     skipping source files
 703     (like <filename>.c</filename> and <filename>.h</filename> files):
 704
 705     </para>
 706
 707     <screen>
 708       % <userinput>scons -Q --tree=derived</userinput>
 709       cc -o f1.o -c -I. f1.c
 710       cc -o f2.o -c -I. f2.c
 711       cc -o f3.o -c -I. f3.c
 712       cc -o prog f1.o f2.o f3.o
 713       +-.
 714     </screen>
 715
 716     <para>
 717
 718     You can use the <literal>status</literal>
 719     modifier with <literal>derived</literal> as well:
 720
 721     </para>
 722
 723     <screen>
 724       % <userinput>scons -Q --tree=derived,status</userinput>
 725       cc -o f1.o -c -I. f1.c
 726       cc -o f2.o -c -I. f2.c
 727       cc -o f3.o -c -I. f3.c
 728       cc -o prog f1.o f2.o f3.o
 729        E         = exists
 730         R        = exists in repository only
 731          b       = implicit builder
 732          B       = explicit builder
 733           S      = side effect
 734            P     = precious
 735             A    = always build
 736              C   = current
 737               N  = no clean
 738                H = no cache
 739
 740       [E b      ]+-.
 741       [E B   C  ]  +-f1.o
 742       [E B   C  ]  +-f2.o
 743       [E B   C  ]  +-f3.o
 744       [E B   C  ]  +-prog
 745       [E B   C  ]    +-f1.o
 746       [E B   C  ]    +-f2.o
 747       [E B   C  ]    +-f3.o
 748     </screen>
 749
 750     <para>
 751
 752     Note that the order of the <literal>--tree=</literal>
 753     arguments doesn't matter;
 754     <literal>--tree=status,derived</literal> is
 755     completely equivalent.
 756
 757     </para>
 758
 759     <para>
 760
 761     The default behavior of the <literal>--tree</literal> option
 762     is to repeat all of the dependencies each time the library dependency
 763     (or any other dependency file) is encountered in the tree.
 764     If certain target files share other target files,
 765     such as two programs that use the same library:
 766
 767     </para>
 768
 769     <programlisting>
 770          env = Environment(CPPPATH = ['.'],
 771                            LIBS = ['foo'],
 772                            LIBPATH = ['.'])
 773          env.Library('foo', ['f1.c', 'f2.c', 'f3.c'])
 774          env.Program('prog1.c')
 775          env.Program('prog2.c')
 776     </programlisting>
 777
 778     <para>
 779
 780     Then there can be a <emphasis>lot</emphasis> of repetition in the
 781     <literal>--tree=</literal> output:
 782
 783     </para>
 784
 785     <screen>
 786       % <userinput>scons -Q --tree=all</userinput>
 787       cc -o f1.o -c -I. f1.c
 788       cc -o f2.o -c -I. f2.c
 789       cc -o f3.o -c -I. f3.c
 790       ar rc libfoo.a f1.o f2.o f3.o
 791       ranlib libfoo.a
 792       cc -o prog1.o -c -I. prog1.c
 793       cc -o prog1 prog1.o -L. -lfoo
 794       cc -o prog2.o -c -I. prog2.c
 795       cc -o prog2 prog2.o -L. -lfoo
 796       +-.
 797         +--
 798         +-SConstruct
 799         +-f1.c
 800         +-f1.o
 801         | +-f1.c
 802         | +-inc.h
 803         +-f2.c
 804         +-f2.o
 805         | +-f2.c
 806         | +-inc.h
 807         +-f3.c
 808         +-f3.o
 809         | +-f3.c
 810         | +-inc.h
 811         +-inc.h
 812         +-libfoo.a
 813         | +-f1.o
 814         | | +-f1.c
 815         | | +-inc.h
 816         | +-f2.o
 817         | | +-f2.c
 818         | | +-inc.h
 819         | +-f3.o
 820         |   +-f3.c
 821         |   +-inc.h
 822         +-prog1
 823         | +-prog1.o
 824         | | +-prog1.c
 825         | | +-inc.h
 826         | +-libfoo.a
 827         |   +-f1.o
 828         |   | +-f1.c
 829         |   | +-inc.h
 830         |   +-f2.o
 831         |   | +-f2.c
 832         |   | +-inc.h
 833         |   +-f3.o
 834         |     +-f3.c
 835         |     +-inc.h
 836         +-prog1.c
 837         +-prog1.o
 838         | +-prog1.c
 839         | +-inc.h
 840         +-prog2
 841         | +-prog2.o
 842         | | +-prog2.c
 843         | | +-inc.h
 844         | +-libfoo.a
 845         |   +-f1.o
 846         |   | +-f1.c
 847         |   | +-inc.h
 848         |   +-f2.o
 849         |   | +-f2.c
 850         |   | +-inc.h
 851         |   +-f3.o
 852         |     +-f3.c
 853         |     +-inc.h
 854         +-prog2.c
 855         +-prog2.o
 856           +-prog2.c
 857           +-inc.h
 858     </screen>
 859
 860     <para>
 861
 862     In a large configuration with many internal libraries
 863     and include files,
 864     this can very quickly lead to huge output trees.
 865     To help make this more manageable,
 866     a <literal>prune</literal> modifier may
 867     be added to the option list,
 868     in which case &SCons;
 869     will print the name of a target that has
 870     already been visited during the tree-printing
 871     in <literal>[square brackets]</literal>
 872     as an indication that the dependencies
 873     of the target file may be found
 874     by looking farther up the tree:
 875
 876     </para>
 877
 878     <screen>
 879       % <userinput>scons -Q --tree=prune</userinput>
 880       cc -o f1.o -c -I. f1.c
 881       cc -o f2.o -c -I. f2.c
 882       cc -o f3.o -c -I. f3.c
 883       ar rc libfoo.a f1.o f2.o f3.o
 884       ranlib libfoo.a
 885       cc -o prog1.o -c -I. prog1.c
 886       cc -o prog1 prog1.o -L. -lfoo
 887       cc -o prog2.o -c -I. prog2.c
 888       cc -o prog2 prog2.o -L. -lfoo
 889       +-.
 890         +--
 891         +-SConstruct
 892         +-f1.c
 893         +-f1.o
 894         | +-[f1.c]
 895         | +-inc.h
 896         +-f2.c
 897         +-f2.o
 898         | +-[f2.c]
 899         | +-[inc.h]
 900         +-f3.c
 901         +-f3.o
 902         | +-[f3.c]
 903         | +-[inc.h]
 904         +-[inc.h]
 905         +-libfoo.a
 906         | +-[f1.o]
 907         | +-[f2.o]
 908         | +-[f3.o]
 909         +-prog1
 910         | +-prog1.o
 911         | | +-prog1.c
 912         | | +-[inc.h]
 913         | +-[libfoo.a]
 914         +-[prog1.c]
 915         +-[prog1.o]
 916         +-prog2
 917         | +-prog2.o
 918         | | +-prog2.c
 919         | | +-[inc.h]
 920         | +-[libfoo.a]
 921         +-[prog2.c]
 922         +-[prog2.o]
 923     </screen>
 924
 925     <para>
 926
 927     Like the <literal>status</literal> keyword,
 928     the <literal>prune</literal> argument by itself
 929     is equivalent to <literal>--tree=all,prune</literal>.
 930
 931     </para>
 932
 933   </section>
 934
 935   <section>
 936
 937   <title>How is &SCons; Constructing the Command Lines It Executes?  the &debug-presub; Option</title>
 938
 939     <para>
 940
 941     Sometimes it's useful to look at the
 942     pre-substitution string
 943     that &SCons; uses to generate
 944     the command lines it executes.
 945     This can be done with the &debug-presub; option:
 946
 947     </para>
 948
 949
 950
 951     <!--
 952
 953     Have to capture output here, otherwise the - -debug=presub output
 954     shows the Python functions from the sconsdoc.py execution wrapper
 955     used to generate this manual, not the underlying command-line strings.
 956
 957     <scons_output example="presub">
 958       <scons_output_command>scons -Q - -debug=presub</scons_output_command>
 959     </scons_output>
 960
 961     -->
 962
 963     <screen>
 964       % <userinput>scons -Q --debug=presub</userinput>
 965       Building prog.o with action:
 966         $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES
 967       cc -o prog.o -c -I. prog.c
 968       Building prog with action:
 969         $SMART_LINKCOM
 970       cc -o prog prog.o
 971     </screen>
 972
 973   </section>
 974
 975   <section>
 976
 977   <title>Where is &SCons; Searching for Libraries?  the &debug-findlibs; Option</title>
 978
 979     <para>
 980
 981     To get some insight into what library names
 982     &SCons; is searching for,
 983     and in which directories it is searching,
 984     Use the <literal>--debug=findlibs</literal> option.
 985     Given the following input &SConstruct; file:
 986
 987     </para>
 988
 989     <programlisting>
 990         env = Environment(LIBPATH = ['libs1', 'libs2'])
 991         env.Program('prog.c', LIBS=['foo', 'bar'])
 992     </programlisting>
 993
 994     <para>
 995
 996     And the libraries <filename>libfoo.a</filename>
 997     and <filename>libbar.a</filename>
 998     in <filename>libs1</filename> and <filename>libs2</filename>,
 999     respectively,
1000     use of the <literal>--debug=findlibs</literal> option yields:
1001
1002     </para>
1003
1004     <screen>
1005       % <userinput>scons -Q --debug=findlibs</userinput>
1006         findlibs: looking for 'libfoo.a' in 'libs1' ...
1007         findlibs: ... FOUND 'libfoo.a' in 'libs1'
1008         findlibs: looking for 'libfoo.so' in 'libs1' ...
1009         findlibs: looking for 'libfoo.so' in 'libs2' ...
1010         findlibs: looking for 'libbar.a' in 'libs1' ...
1011         findlibs: looking for 'libbar.a' in 'libs2' ...
1012         findlibs: ... FOUND 'libbar.a' in 'libs2'
1013         findlibs: looking for 'libbar.so' in 'libs1' ...
1014         findlibs: looking for 'libbar.so' in 'libs2' ...
1015       cc -o prog.o -c prog.c
1016       cc -o prog prog.o -Llibs1 -Llibs2 -lfoo -lbar
1017     </screen>
1018
1019   </section>
1020
1021   <!--
1022
1023   <section>
1024
1025   <title>What Implicit Dependencies Did the &SCons; Scanner find?  the &debug-includes; Option</title>
1026
1027     <para>
1028
1029     XXX explain the - - debug=includes option
1030
1031     </para>
1032
1033     <scons_example name="includes">
1034       <file name="SConstruct" printme="1">
1035         env = Environment(CPPPATH = ['inc1', 'inc2'])
1036         env.Program('prog.c')
1037       </file>
1038       <file name="prog.c">
1039       #include "file1.h"
1040       #include "file2.h"
1041       prog.c
1042       </file>
1043       <file name="inc1/file1.h">
1044       inc1/file1.h
1045       </file>
1046       <file name="inc2/file2.h">
1047       inc2/file2.h
1048       </file>
1049     </scons_example>
1050
1051     <scons_output example="includes">
1052       <scons_output_command>scons -Q - - debug=includes prog</scons_output_command>
1053     </scons_output>
1054
1055   </section>
1056
1057   -->
1058
1059   <section>
1060
1061   <title>Where is &SCons; Blowing Up?  the &debug-stacktrace; Option</title>
1062
1063     <para>
1064
1065     In general, &SCons; tries to keep its error
1066     messages short and informative.
1067     That means we usually try to avoid showing
1068     the stack traces that are familiar
1069     to experienced Python programmers,
1070     since they usually contain much more
1071     information than is useful to most people.
1072
1073     </para>
1074
1075     <para>
1076
1077     For example, the following &SConstruct; file:
1078
1079     </para>
1080
1081     <programlisting>
1082          Program('prog.c')
1083     </programlisting>
1084
1085     <para>
1086
1087     Generates the following error if the
1088     <filename>prog.c</filename> file
1089     does not exist:
1090
1091     </para>
1092
1093     <screen>
1094       % <userinput>scons -Q</userinput>
1095       scons: *** Source `prog.c' not found, needed by target `prog.o'.  Stop.
1096     </screen>
1097
1098     <para>
1099
1100     In this case,
1101     the error is pretty obvious.
1102     But if it weren't,
1103     and you wanted to try to get more information
1104     about the error,
1105     the &debug-stacktrace; option
1106     would show you exactly where in the &SCons; source code
1107     the problem occurs:
1108
1109     </para>
1110
1111     <screen>
1112       % <userinput>scons -Q --debug=stacktrace</userinput>
1113       scons: *** Source `prog.c' not found, needed by target `prog.o'.  Stop.
1114       scons: internal stack trace:
1115         File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Job.py", line 111, in start
1116           task.prepare()
1117         File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Taskmaster.py", line 166, in prepare
1118           t.prepare()
1119         File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Node/FS.py", line 2137, in prepare
1120           SCons.Node.Node.prepare(self)
1121         File "/home/knight/SCons/scons.0.96.C763/bootstrap/src/engine/SCons/Node/__init__.py", line 806, in prepare
1122           raise SCons.Errors.StopError, desc
1123     </screen>
1124
1125     <para>
1126
1127     Of course, if you do need to dive into the &SCons; source code,
1128     we'd like to know if, or how,
1129     the error messages or troubleshooting options
1130     could have been improved to avoid that.
1131     Not everyone has the necessary time or
1132     Python skill to dive into the source code,
1133     and we'd like to improve &SCons;
1134     for those people as well...
1135
1136     </para>
1137
1138   </section>
1139
1140   <section>
1141
1142   <title>How is &SCons; Making Its Decisions?  the &taskmastertrace; Option</title>
1143
1144     <para>
1145
1146     The internal &SCons; subsystem that handles walking
1147     the dependency graph
1148     and controls the decision-making about what to rebuild
1149     is the <literal>Taskmaster</literal>.
1150     &SCons; supports a <literal>--taskmastertrace</literal>
1151     option that tells the Taskmaster to print
1152     information about the children (dependencies)
1153     of the various Nodes on its walk down the graph,
1154     which specific dependent Nodes are being evaluated,
1155     and in what order.
1156
1157     </para>
1158
1159     <para>
1160
1161     The <literal>--taskmastertrace</literal> option
1162     takes as an argument the name of a file in
1163     which to put the trace output,
1164     with <filename>-</filename> (a single hyphen)
1165     indicating that the trace messages
1166     should be printed to the standard output:
1167
1168     </para>
1169
1170     <programlisting>
1171       env = Environment(CPPPATH = ['.'])
1172       env.Program('prog.c')
1173     </programlisting>
1174
1175     <screen>
1176       % <userinput>scons -Q --taskmastertrace=- prog</userinput>
1177       Taskmaster: 'prog': children:
1178           ['prog.o']
1179           waiting on unstarted children:
1180           ['prog.o']
1181       Taskmaster: 'prog.o': children:
1182           ['inc.h', 'prog.c']
1183           evaluating prog.o
1184       cc -o prog.o -c -I. prog.c
1185       Taskmaster: 'prog': children:
1186           ['prog.o']
1187           evaluating prog
1188       cc -o prog prog.o
1189       Taskmaster: 'prog': already handled (executed)
1190     </screen>
1191
1192     <para>
1193
1194     The <literal>--taskmastertrace</literal> option
1195     doesn't provide information about the actual
1196     calculations involved in deciding if a file is up-to-date,
1197     but it does show all of the dependencies
1198     it knows about for each Node,
1199     and the order in which those dependencies are evaluated.
1200     This can be useful as an alternate way to determine
1201     whether or not your &SCons; configuration,
1202     or the implicit dependency scan,
1203     has actually identified all the correct dependencies
1204     you want it to.
1205
1206     </para>
1207
1208   </section>
1209
1210   <!--
1211
1212   <section>
1213
1214   <title>Where Are My Build Bottlenecks?  the &profile; Option</title>
1215
1216     <para>
1217
1218     XXX explain the - - profile= option
1219
1220     </para>
1221
1222   </section>
1223
1224   -->
1225
1226   <!--
1227
1228   <section>
1229   <title>Troubleshooting Shared Caching:  the &cache-debug; Option</title>
1230
1231     <para>
1232
1233     XXX describe the - - cache-debug option
1234     XXX maybe point to the caching.in chapter?
1235
1236     </para>
1237
1238   </section>
1239
1240   -->