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
  36   </para>
  37
  38   <section>
  39   <title>Why is That Target Being Rebuilt?  the &debug-explain; Option</title>
  40
  41     <para>
  42
  43     Let's take a simple example of
  44     a misconfigured build
  45     that causes a target to be rebuilt
  46     every time &SCons; is run:
  47
  48     </para>
  49
  50     <programlisting>
  51       # Intentionally misspell the output file name in the
  52       # command used to create the file:
  53       Command('file.out', 'file.in', 'cp $SOURCE file.oout')
  54     </programlisting>
  55
  56     <para>
  57
  58     (Note to Windows users:  The POSIX &cp; command
  59     copies the first file named on the command line
  60     to the second file.
  61     In our example, it copies the &file_in; file
  62     to the &file_out; file.)
  63
  64     </para>
  65
  66     <para>
  67
  68     Now if we run &SCons; multiple on this example,
  69     we see that it re-runs the &cp;
  70     command every time:
  71
  72     </para>
  73
  74     <screen>
  75       % <userinput>scons -Q</userinput>
  76       cp file.in file.oout
  77       % <userinput>scons -Q</userinput>
  78       cp file.in file.oout
  79       % <userinput>scons -Q</userinput>
  80       cp file.in file.oout
  81     </screen>
  82
  83     <para>
  84
  85     In this example,
  86     the underlying cause is obvious:
  87     we've intentionally misspelled the output file name
  88     in the &cp; command,
  89     so the command doesn't actually
  90     build the &file_out; file that we've told &SCons; to expect.
  91     But if the problem weren't obvious,
  92     it would be helpful
  93     to specify the &debug-explain; option
  94     on the command line
  95     to have &SCons; tell us very specifically
  96     why it's decided to rebuild the target:
  97
  98     </para>
  99
 100     <screen>
 101       % <userinput>scons -Q --debug=explain</userinput>
 102       scons: building `file.out' because it doesn't exist
 103       cp file.in file.oout
 104     </screen>
 105
 106     <para>
 107
 108     If this had been a more complicated example
 109     involving a lot of build output,
 110     having &SCons; tell us that
 111     it's trying to rebuild the target file
 112     because it doesn't exist
 113     would be an important clue
 114     that something was wrong with
 115     the command that we invoked to build it.
 116
 117     </para>
 118
 119     <para>
 120
 121     The &debug-explain; option also comes in handy
 122     to help figure out what input file changed.
 123     Given a simple configuration that builds
 124     a program from three source files,
 125     changing one of the source files
 126     and rebuilding with the &debug-explain;
 127     option shows very specifically
 128     why &SCons; rebuilds the files that it does:
 129
 130     </para>
 131
 132
 133
 134     <screen>
 135       % <userinput>scons -Q</userinput>
 136       cc -o file1.o -c file1.c
 137       cc -o file2.o -c file2.c
 138       cc -o file3.o -c file3.c
 139       cc -o prog file1.o file2.o file3.o
 140       % <userinput>edit file2.c</userinput>
 141           [CHANGE THE CONTENTS OF file2.c]
 142       % <userinput>scons -Q --debug=explain</userinput>
 143       scons: rebuilding `file2.o' because `file2.c' changed
 144       cc -o file2.o -c file2.c
 145       scons: rebuilding `prog' because `file2.o' changed
 146       cc -o prog file1.o file2.o file3.o
 147     </screen>
 148
 149     <para>
 150
 151     This becomes even more helpful
 152     in identifying when a file is rebuilt
 153     due to a change in an implicit dependency,
 154     such as an incuded <filename>.h</filename> file.
 155     If the <filename>file1.c</filename>
 156     and <filename>file3.c</filename> files
 157     in our example
 158     both included a &hello_h; file,
 159     then changing that included file
 160     and re-running &SCons; with the &debug-explain; option
 161     will pinpoint that it's the change to the included file
 162     that starts the chain of rebuilds:
 163
 164     </para>
 165
 166
 167
 168     <screen>
 169       % <userinput>scons -Q</userinput>
 170       cc -o file1.o -c -I. file1.c
 171       cc -o file2.o -c -I. file2.c
 172       cc -o file3.o -c -I. file3.c
 173       cc -o prog file1.o file2.o file3.o
 174       % <userinput>edit hello.h</userinput>
 175           [CHANGE THE CONTENTS OF hello.h]
 176       % <userinput>scons -Q --debug=explain</userinput>
 177       scons: rebuilding `file1.o' because `hello.h' changed
 178       cc -o file1.o -c -I. file1.c
 179       scons: rebuilding `file3.o' because `hello.h' changed
 180       cc -o file3.o -c -I. file3.c
 181       scons: rebuilding `prog' because:
 182                  `file1.o' changed
 183                  `file3.o' changed
 184       cc -o prog file1.o file2.o file3.o
 185     </screen>
 186
 187   </section>
 188
 189   <section>
 190   <title>What's in That Construction Environment?  the &Dump; Method</title>
 191
 192     <para>
 193
 194     When you create a construction environment,
 195     &SCons; populates it
 196     with construction variables that are set up
 197     for various compilers, linkers and utilities
 198     that it finds on your system.
 199     Although this is usually helpful and what you want,
 200     it might be frustrating if &SCons;
 201     doesn't set certain variables that you
 202     expect to be sit.
 203     In situations like this,
 204     it's sometimes helpful to use the
 205     construction environment &Dump; method
 206     to print all or some of
 207     the construction variables.
 208     Note that the &Dump; method
 209     <emphasis>returns</emphasis>
 210     the representation of the variables
 211     in the environment
 212     for you to print (or otherwise manipulate):
 213
 214     </para>
 215
 216
 217
 218     <para>
 219
 220     On a POSIX system with gcc installed,
 221     this might generate:
 222
 223     </para>
 224
 225     <screen>
 226       % <userinput>scons</userinput>
 227       scons: Reading SConscript files ...
 228       { 'BUILDERS': {},
 229         'CONFIGUREDIR': '#/.sconf_temp',
 230         'CONFIGURELOG': '#/config.log',
 231         'CPPSUFFIXES': [ '.c',
 232                          '.C',
 233                          '.cxx',
 234                          '.cpp',
 235                          '.c++',
 236                          '.cc',
 237                          '.h',
 238                          '.H',
 239                          '.hxx',
 240                          '.hpp',
 241                          '.hh',
 242                          '.F',
 243                          '.fpp',
 244                          '.FPP',
 245                          '.m',
 246                          '.mm',
 247                          '.S',
 248                          '.spp',
 249                          '.SPP'],
 250         'DSUFFIXES': ['.d'],
 251         'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43bec&gt;,
 252         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c0c&gt;,
 253         'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'},
 254         'ESCAPE': &lt;function escape at 0xb7b66c34&gt;,
 255         'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c2c&gt;,
 256         'IDLSUFFIXES': ['.idl', '.IDL'],
 257         'INSTALL': &lt;function installFunc at 0xb7c41f0c&gt;,
 258         'INSTALLSTR': &lt;function installStr at 0xb7c41f44&gt;,
 259         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
 260         'LIBPREFIX': 'lib',
 261         'LIBPREFIXES': '$LIBPREFIX',
 262         'LIBSUFFIX': '.a',
 263         'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'],
 264         'MAXLINELENGTH': 128072,
 265         'OBJPREFIX': '',
 266         'OBJSUFFIX': '.o',
 267         'PLATFORM': 'posix',
 268         'PROGPREFIX': '',
 269         'PROGSUFFIX': '',
 270         'PSPAWN': &lt;function piped_env_spawn at 0xb7b66fb4&gt;,
 271         'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c43c4c&gt;,
 272         'SCANNERS': [],
 273         'SHELL': 'sh',
 274         'SHLIBPREFIX': '$LIBPREFIX',
 275         'SHLIBSUFFIX': '.so',
 276         'SHOBJPREFIX': '$OBJPREFIX',
 277         'SHOBJSUFFIX': '$OBJSUFFIX',
 278         'SPAWN': &lt;function spawnvpe_spawn at 0xb7b66a74&gt;,
 279         'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7bd37ac&gt;,
 280         'TEMPFILEPREFIX': '@',
 281         'TOOLS': [],
 282         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
 283         '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 284         '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 285         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
 286         '__RPATH': '$_RPATH',
 287         '_concat': &lt;function _concat at 0xb7c41fb4&gt;,
 288         '_defines': &lt;function _defines at 0xb7c47064&gt;,
 289         '_installStr': &lt;function installStr at 0xb7c41f44&gt;,
 290         '_stripixes': &lt;function _stripixes at 0xb7c4702c&gt;}
 291       scons: done reading SConscript files.
 292       scons: Building targets ...
 293       scons: `.' is up to date.
 294       scons: done building targets.
 295     </screen>
 296
 297     <para>
 298
 299     On a Windows system with Visual C++
 300     the output might look like:
 301
 302     </para>
 303
 304     <screen>
 305       C:\><userinput>scons</userinput>
 306       scons: Reading SConscript files ...
 307       { 'BUILDERS': {'Object': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6024c&gt;, 'SharedObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b603cc&gt;, 'StaticObject': &lt;SCons.Builder.CompositeBuilder instance at 0xb7b6024c&gt;, 'PCH': &lt;SCons.Builder.BuilderBase instance at 0xb7bd2eac&gt;, 'RES': &lt;SCons.Builder.BuilderBase instance at 0xb7b596ec&gt;},
 308         'CC': 'cl',
 309         'CCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b6086c&gt;,
 310         'CCCOMFLAGS': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo$TARGET $CCPCHFLAGS $CCPDBFLAGS',
 311         'CCFLAGS': ['/nologo'],
 312         'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'],
 313         'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'],
 314         'CFILESUFFIX': '.c',
 315         'CFLAGS': [],
 316         'CONFIGUREDIR': '#/.sconf_temp',
 317         'CONFIGURELOG': '#/config.log',
 318         'CPPDEFPREFIX': '/D',
 319         'CPPDEFSUFFIX': '',
 320         'CPPSUFFIXES': [ '.c',
 321                          '.C',
 322                          '.cxx',
 323                          '.cpp',
 324                          '.c++',
 325                          '.cc',
 326                          '.h',
 327                          '.H',
 328                          '.hxx',
 329                          '.hpp',
 330                          '.hh',
 331                          '.F',
 332                          '.fpp',
 333                          '.FPP',
 334                          '.m',
 335                          '.mm',
 336                          '.S',
 337                          '.spp',
 338                          '.SPP'],
 339         'CXX': '$CC',
 340         'CXXCOM': '$CXX $CXXFLAGS $CCCOMFLAGS',
 341         'CXXFILESUFFIX': '.cc',
 342         'CXXFLAGS': ['$CCFLAGS', '$(', '/TP', '$)'],
 343         'DSUFFIXES': ['.d'],
 344         'Dir': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58bec&gt;,
 345         'Dirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c0c&gt;,
 346         'ENV': { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
 347                  'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
 348                  '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',
 349                  'PATHEXT': '.COM;.EXE;.BAT;.CMD',
 350                  'SystemRoot': 'C:/WINDOWS'},
 351         'ESCAPE': &lt;function escape at 0xb7bc917c&gt;,
 352         'File': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c2c&gt;,
 353         'IDLSUFFIXES': ['.idl', '.IDL'],
 354         'INCPREFIX': '/I',
 355         'INCSUFFIX': '',
 356         'INSTALL': &lt;function installFunc at 0xb7c56f0c&gt;,
 357         'INSTALLSTR': &lt;function installStr at 0xb7c56f44&gt;,
 358         'LATEXSUFFIXES': ['.tex', '.ltx', '.latex'],
 359         'LIBPREFIX': '',
 360         'LIBPREFIXES': ['$LIBPREFIX'],
 361         'LIBSUFFIX': '.lib',
 362         'LIBSUFFIXES': ['$LIBSUFFIX'],
 363         'MAXLINELENGTH': 2048,
 364         'MSVS': {'VERSION': '6.0', 'VERSIONS': ['6.0']},
 365         'MSVS_VERSION': '6.0',
 366         'OBJPREFIX': '',
 367         'OBJSUFFIX': '.obj',
 368         'PCHCOM': '$CXX $CXXFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Fo${TARGETS[1]} /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS',
 369         'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'],
 370         'PLATFORM': 'win32',
 371         'PROGPREFIX': '',
 372         'PROGSUFFIX': '.exe',
 373         'PSPAWN': &lt;function piped_spawn at 0xb7bc90d4&gt;,
 374         'RC': 'rc',
 375         'RCCOM': '$RC $_CPPDEFFLAGS $_CPPINCFLAGS $RCFLAGS /fo$TARGET $SOURCES',
 376         'RCFLAGS': [],
 377         'RDirs': &lt;SCons.Defaults.Variable_Method_Caller instance at 0xb7c58c4c&gt;,
 378         'SCANNERS': [],
 379         'SHCC': '$CC',
 380         'SHCCCOM': &lt;SCons.Action.FunctionAction instance at 0xb7b608cc&gt;,
 381         'SHCCFLAGS': ['$CCFLAGS'],
 382         'SHCFLAGS': ['$CFLAGS'],
 383         'SHCXX': '$CXX',
 384         'SHCXXCOM': '$SHCXX $SHCXXFLAGS $CCCOMFLAGS',
 385         'SHCXXFLAGS': ['$CXXFLAGS'],
 386         'SHELL': None,
 387         'SHLIBPREFIX': '',
 388         'SHLIBSUFFIX': '.dll',
 389         'SHOBJPREFIX': '$OBJPREFIX',
 390         'SHOBJSUFFIX': '$OBJSUFFIX',
 391         'SPAWN': &lt;function spawn at 0xb7bc9144&gt;,
 392         'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1,
 393         'TEMPFILE': &lt;class SCons.Platform.TempFileMunge at 0xb7be87ac&gt;,
 394         'TEMPFILEPREFIX': '@',
 395         'TOOLS': ['msvc'],
 396         '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}',
 397         '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 398         '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)',
 399         '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}',
 400         '_concat': &lt;function _concat at 0xb7c56fb4&gt;,
 401         '_defines': &lt;function _defines at 0xb7c5c064&gt;,
 402         '_installStr': &lt;function installStr at 0xb7c56f44&gt;,
 403         '_stripixes': &lt;function _stripixes at 0xb7c5c02c&gt;}
 404       scons: done reading SConscript files.
 405       scons: Building targets ...
 406       scons: `.' is up to date.
 407       scons: done building targets.
 408     </screen>
 409
 410     <para>
 411
 412     The construction environments in these examples have
 413     actually been restricted to just gcc and Visual C++,
 414     respectively.
 415     In a real-life situation,
 416     the construction environments will
 417     likely contain a great many more variables.
 418
 419     </para>
 420
 421     <para>
 422
 423     To make it easier to see just what you're
 424     interested in,
 425     the &Dump; method allows you to
 426     specify a specific constrcution variable
 427     that you want to disply.
 428     For example,
 429     it's not unusual to want to verify
 430     the external environment used to execute build commands,
 431     to make sure that the PATH and other
 432     environment variables are set up the way they should be.
 433     You can do this as follows:
 434
 435     </para>
 436
 437
 438
 439     <para>
 440
 441     Which might display the following when executed on a POSIX system:
 442
 443     </para>
 444
 445     <screen>
 446       % <userinput>scons</userinput>
 447       scons: Reading SConscript files ...
 448       {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}
 449       scons: done reading SConscript files.
 450       scons: Building targets ...
 451       scons: `.' is up to date.
 452       scons: done building targets.
 453     </screen>
 454
 455     <para>
 456
 457     And the following when executed on a Windows system:
 458
 459     </para>
 460
 461     <screen>
 462       C:\><userinput>scons</userinput>
 463       scons: Reading SConscript files ...
 464       { 'INCLUDE': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\include',
 465         'LIB': 'C:\\Program Files\\Microsoft Visual Studio/VC98\\lib',
 466         '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',
 467         'PATHEXT': '.COM;.EXE;.BAT;.CMD',
 468         'SystemRoot': 'C:/WINDOWS'}
 469       scons: done reading SConscript files.
 470       scons: Building targets ...
 471       scons: `.' is up to date.
 472       scons: done building targets.
 473     </screen>
 474
 475   </section>