diff options
Diffstat (limited to 'doc/user/troubleshoot.xml')
| -rw-r--r-- | doc/user/troubleshoot.xml | 907 |
1 files changed, 260 insertions, 647 deletions
diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 51de8f2..183f9c4 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -1,6 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE sconsdoc [ + <!ENTITY % scons SYSTEM "../scons.mod"> + %scons; + + <!ENTITY % builders-mod SYSTEM "../generated/builders.mod"> + %builders-mod; + <!ENTITY % functions-mod SYSTEM "../generated/functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "../generated/tools.mod"> + %tools-mod; + <!ENTITY % variables-mod SYSTEM "../generated/variables.mod"> + %variables-mod; +]> + +<chapter id="chap-troubleshooting" + xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0/scons.xsd scons.xsd"> +<title>Troubleshooting</title> + <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -69,11 +90,16 @@ </para> - <programlisting> - # Intentionally misspell the output file name in the - # command used to create the file: - Command('file.out', 'file.in', 'cp $SOURCE file.oout') - </programlisting> + <scons_example name="troubleshoot_explain1"> + <file name="SConstruct" printme="1"> +# Intentionally misspell the output file name in the +# command used to create the file: +Command('file.out', 'file.in', 'cp $SOURCE file.oout') + </file> + <file name="file.in"> +file.in + </file> + </scons_example> <para> @@ -93,14 +119,11 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - cp file.in file.oout - % <userinput>scons -Q</userinput> - cp file.in file.oout - % <userinput>scons -Q</userinput> - cp file.in file.oout - </screen> + <scons_output example="troubleshoot_explain1" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -119,11 +142,9 @@ </para> - <screen> - % <userinput>scons -Q --debug=explain</userinput> - scons: building `file.out' because it doesn't exist - cp file.in file.oout - </screen> + <scons_output example="troubleshoot_explain1" os="posix" suffix="2"> + <scons_output_command>scons -Q --debug=explain</scons_output_command> + </scons_output> <para> @@ -139,6 +160,16 @@ </para> <para> + Note that you can also use --warn=target-not-built which checks + whether or not expected targets exist after a build rule is + executed. + </para> + + <scons_output example="troubleshoot_explain1" os="posix" suffix="3"> + <scons_output_command>scons -Q --warn=target-not-built</scons_output_command> + </scons_output> + + <para> The &debug-explain; option also comes in handy to help figure out what input file changed. @@ -151,22 +182,26 @@ </para> - + <scons_example name="troubleshoot_explain2"> + <file name="SConstruct"> +Program('prog', ['file1.c', 'file2.c', 'file3.c']) + </file> + <file name="file1.c"> +file1.c + </file> + <file name="file2.c"> +file2.c + </file> + <file name="file3.c"> +file3.c + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cc -o file1.o -c file1.c - cc -o file2.o -c file2.c - cc -o file3.o -c file3.c - cc -o prog file1.o file2.o file3.o - % <userinput>edit file2.c</userinput> - [CHANGE THE CONTENTS OF file2.c] - % <userinput>scons -Q --debug=explain</userinput> - scons: rebuilding `file2.o' because `file2.c' changed - cc -o file2.o -c file2.c - scons: rebuilding `prog' because `file2.o' changed - cc -o prog file1.o file2.o file3.o - </screen> + <scons_output example="troubleshoot_explain2" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF file2.c]">edit file2.c</scons_output_command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> + </scons_output> <para> @@ -185,26 +220,31 @@ </para> - + <scons_example name="troubleshoot_explain3"> + <file name="SConstruct"> +Program('prog', ['file1.c', 'file2.c', 'file3.c'], CPPPATH='.') + </file> + <file name="file1.c"> +#include <hello.h> +file1.c + </file> + <file name="file2.c"> +file2.c + </file> + <file name="file3.c"> +#include <hello.h> +file3.c + </file> + <file name="hello.h"> +#define string "world" + </file> + </scons_example> - <screen> - % <userinput>scons -Q</userinput> - cc -o file1.o -c -I. file1.c - cc -o file2.o -c -I. file2.c - cc -o file3.o -c -I. file3.c - cc -o prog file1.o file2.o file3.o - % <userinput>edit hello.h</userinput> - [CHANGE THE CONTENTS OF hello.h] - % <userinput>scons -Q --debug=explain</userinput> - scons: rebuilding `file1.o' because `hello.h' changed - cc -o file1.o -c -I. file1.c - scons: rebuilding `file3.o' because `hello.h' changed - cc -o file3.o -c -I. file3.c - scons: rebuilding `prog' because: - `file1.o' changed - `file3.o' changed - cc -o prog file1.o file2.o file3.o - </screen> + <scons_output example="troubleshoot_explain3" os="posix" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + <scons_output_command output=" [CHANGE THE CONTENTS OF hello.h]">edit hello.h</scons_output_command> + <scons_output_command>scons -Q --debug=explain</scons_output_command> + </scons_output> <para> @@ -246,10 +286,12 @@ </para> - <programlisting> - env = Environment() - print env.Dump() - </programlisting> + <scons_example name="troubleshoot_Dump"> + <file name="SConstruct" printme="1"> +env = Environment() +print env.Dump() + </file> + </scons_example> <para> @@ -258,79 +300,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, - 'CONFIGUREDIR': '#/.sconf_temp', - 'CONFIGURELOG': '#/config.log', - 'CPPSUFFIXES': [ '.c', - '.C', - '.cxx', - '.cpp', - '.c++', - '.cc', - '.h', - '.H', - '.hxx', - '.hpp', - '.hh', - '.F', - '.fpp', - '.FPP', - '.m', - '.mm', - '.S', - '.spp', - '.SPP', - '.sx'], - 'DSUFFIXES': ['.d'], - 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'ENV': { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}, - 'ESCAPE': <function escape at 0x700000>, - 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'HOST_ARCH': None, - 'HOST_OS': None, - 'IDLSUFFIXES': ['.idl', '.IDL'], - 'INSTALL': <function copyFunc at 0x700000>, - 'LIBPREFIX': 'lib', - 'LIBPREFIXES': ['$LIBPREFIX'], - 'LIBSUFFIX': '.a', - 'LIBSUFFIXES': ['$LIBSUFFIX', '$SHLIBSUFFIX'], - 'MAXLINELENGTH': 128072, - 'OBJPREFIX': '', - 'OBJSUFFIX': '.o', - 'PLATFORM': 'posix', - 'PROGPREFIX': '', - 'PROGSUFFIX': '', - 'PSPAWN': <function piped_env_spawn at 0x700000>, - 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'SCANNERS': [], - 'SHELL': 'sh', - 'SHLIBPREFIX': '$LIBPREFIX', - 'SHLIBSUFFIX': '.so', - 'SHOBJPREFIX': '$OBJPREFIX', - 'SHOBJSUFFIX': '$OBJSUFFIX', - 'SPAWN': <function spawnvpe_spawn at 0x700000>, - 'TARGET_ARCH': None, - 'TARGET_OS': None, - 'TEMPFILE': <class 'SCons.Platform.TempFileMunge'>, - 'TEMPFILEPREFIX': '@', - 'TOOLS': ['install', 'install'], - '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', - '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', - '__RPATH': '$_RPATH', - '_concat': <function _concat at 0x700000>, - '_defines': <function _defines at 0x700000>, - '_stripixes': <function _stripixes at 0x700000>} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump" os="posix" tools="gcc" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -339,112 +311,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder object at 0x700000>, 'PCH': <SCons.Builder.BuilderBase object at 0x700000>, 'RES': <SCons.Builder.BuilderBase object at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder object at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder object at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, - 'CC': 'cl', - 'CCCOM': <SCons.Action.FunctionAction object at 0x700000>, - 'CCFLAGS': ['/nologo'], - 'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'], - 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], - 'CFILESUFFIX': '.c', - 'CFLAGS': [], - 'CONFIGUREDIR': '#/.sconf_temp', - 'CONFIGURELOG': '#/config.log', - 'CPPDEFPREFIX': '/D', - 'CPPDEFSUFFIX': '', - 'CPPSUFFIXES': [ '.c', - '.C', - '.cxx', - '.cpp', - '.c++', - '.cc', - '.h', - '.H', - '.hxx', - '.hpp', - '.hh', - '.F', - '.fpp', - '.FPP', - '.m', - '.mm', - '.S', - '.spp', - '.SPP', - '.sx'], - 'CXX': '$CC', - 'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM")}', - 'CXXFILESUFFIX': '.cc', - 'CXXFLAGS': ['$(', '/TP', '$)'], - 'DSUFFIXES': ['.d'], - 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'ENV': { 'PATH': 'C:\\WINDOWS\\System32', - 'PATHEXT': '.COM;.EXE;.BAT;.CMD', - 'SystemRoot': 'C:\\WINDOWS'}, - 'ESCAPE': <function escape at 0x700000>, - 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'HOST_ARCH': '', - 'HOST_OS': 'win32', - 'IDLSUFFIXES': ['.idl', '.IDL'], - 'INCPREFIX': '/I', - 'INCSUFFIX': '', - 'INSTALL': <function copyFunc at 0x700000>, - 'LIBPREFIX': '', - 'LIBPREFIXES': ['$LIBPREFIX'], - 'LIBSUFFIX': '.lib', - 'LIBSUFFIXES': ['$LIBSUFFIX'], - 'MAXLINELENGTH': 2048, - 'MSVC_SETUP_RUN': True, - 'OBJPREFIX': '', - 'OBJSUFFIX': '.obj', - 'PCHCOM': '$CXX /Fo${TARGETS[1]} $CXXFLAGS $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS /c $SOURCES /Yc$PCHSTOP /Fp${TARGETS[0]} $CCPDBFLAGS $PCHPDBFLAGS', - 'PCHPDBFLAGS': ['${(PDB and "/Yd") or ""}'], - 'PLATFORM': 'win32', - 'PROGPREFIX': '', - 'PROGSUFFIX': '.exe', - 'PSPAWN': <function piped_spawn at 0x700000>, - 'RC': 'rc', - 'RCCOM': <SCons.Action.FunctionAction object at 0x700000>, - 'RCFLAGS': [], - 'RCSUFFIXES': ['.rc', '.rc2'], - 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, - 'SCANNERS': [], - 'SHCC': '$CC', - 'SHCCCOM': <SCons.Action.FunctionAction object at 0x700000>, - 'SHCCFLAGS': ['$CCFLAGS'], - 'SHCFLAGS': ['$CFLAGS'], - 'SHCXX': '$CXX', - 'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM")}', - 'SHCXXFLAGS': ['$CXXFLAGS'], - 'SHELL': None, - 'SHLIBPREFIX': '', - 'SHLIBSUFFIX': '.dll', - 'SHOBJPREFIX': '$OBJPREFIX', - 'SHOBJSUFFIX': '$OBJSUFFIX', - 'SPAWN': <function spawn at 0x700000>, - 'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1, - 'TARGET_ARCH': '', - 'TARGET_OS': 'win32', - 'TEMPFILE': <class 'SCons.Platform.TempFileMunge'>, - 'TEMPFILEPREFIX': '@', - 'TOOLS': ['msvc', 'install', 'install'], - '_CCCOMCOM': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $CCPCHFLAGS $CCPDBFLAGS', - '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', - '_CPPINCFLAGS': '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBDIRFLAGS': '$( ${_concat(LIBDIRPREFIX, LIBPATH, LIBDIRSUFFIX, __env__, RDirs, TARGET, SOURCE)} $)', - '_LIBFLAGS': '${_concat(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, __env__)}', - '_MSVC_OUTPUT_FLAG': <function msvc_output_flag at 0x700000>, - '_concat': <function _concat at 0x700000>, - '_defines': <function _defines at 0x700000>, - '_stripixes': <function _stripixes at 0x700000>} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump" os="win32" tools="msvc" suffix="2"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -477,10 +346,12 @@ </para> - <programlisting> - env = Environment() - print env.Dump('ENV') - </programlisting> + <scons_example name="troubleshoot_Dump_ENV"> + <file name="SConstruct" printme="1"> +env = Environment() +print env.Dump('ENV') + </file> + </scons_example> <para> @@ -488,15 +359,9 @@ </para> - <screen> - % <userinput>scons</userinput> - scons: Reading SConscript files ... - { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump_ENV" os="posix" suffix="1"> + <scons_output_command>scons</scons_output_command> + </scons_output> <para> @@ -504,17 +369,9 @@ </para> - <screen> - C:\><userinput>scons</userinput> - scons: Reading SConscript files ... - { 'PATH': 'C:\\WINDOWS\\System32', - 'PATHEXT': '.COM;.EXE;.BAT;.CMD', - 'SystemRoot': 'C:\\WINDOWS'} - scons: done reading SConscript files. - scons: Building targets ... - scons: `.' is up to date. - scons: done building targets. - </screen> + <scons_output example="troubleshoot_Dump_ENV" os="win32" suffix="2"> + <scons_output_command>scons</scons_output_command> + </scons_output> </section> @@ -542,10 +399,24 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.']) - env.Program('prog', ['f1.c', 'f2.c', 'f3.c']) - </programlisting> + <scons_example name="troubleshoot_tree1"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.']) +env.Program('prog', ['f1.c', 'f2.c', 'f3.c']) + </file> + <file name="f1.c"> +#include "inc.h" + </file> + <file name="f2.c"> +#include "inc.h" + </file> + <file name="f3.c"> +#include "inc.h" + </file> + <file name="inc.h"> +inc.h + </file> + </scons_example> <para> @@ -554,38 +425,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - +-. - +-SConstruct - +-f1.c - +-f1.o - | +-f1.c - | +-inc.h - +-f2.c - +-f2.o - | +-f2.c - | +-inc.h - +-f3.c - +-f3.o - | +-f3.c - | +-inc.h - +-inc.h - +-prog - +-f1.o - | +-f1.c - | +-inc.h - +-f2.o - | +-f2.c - | +-inc.h - +-f3.o - +-f3.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="1"> + <scons_output_command>scons -Q --tree=all</scons_output_command> + </scons_output> <para> @@ -609,13 +451,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all f2.o</userinput> - cc -o f2.o -c -I. f2.c - +-f2.o - +-f2.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="2"> + <scons_output_command>scons -Q --tree=all f2.o</scons_output_command> + </scons_output> <para> @@ -629,17 +467,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all f1.o f3.o</userinput> - cc -o f1.o -c -I. f1.c - +-f1.o - +-f1.c - +-inc.h - cc -o f3.o -c -I. f3.c - +-f3.o - +-f3.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="3"> + <scons_output_command>scons -Q --tree=all f1.o f3.o</scons_output_command> + </scons_output> <para> @@ -649,49 +479,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=status</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - E = exists - R = exists in repository only - b = implicit builder - B = explicit builder - S = side effect - P = precious - A = always build - C = current - N = no clean - H = no cache - - [E b ]+-. - [E C ] +-SConstruct - [E C ] +-f1.c - [E B C ] +-f1.o - [E C ] | +-f1.c - [E C ] | +-inc.h - [E C ] +-f2.c - [E B C ] +-f2.o - [E C ] | +-f2.c - [E C ] | +-inc.h - [E C ] +-f3.c - [E B C ] +-f3.o - [E C ] | +-f3.c - [E C ] | +-inc.h - [E C ] +-inc.h - [E B C ] +-prog - [E B C ] +-f1.o - [E C ] | +-f1.c - [E C ] | +-inc.h - [E B C ] +-f2.o - [E C ] | +-f2.c - [E C ] | +-inc.h - [E B C ] +-f3.o - [E C ] +-f3.c - [E C ] +-inc.h - </screen> + <scons_output example="troubleshoot_tree1" suffix="4"> + <scons_output_command>scons -Q --tree=status</scons_output_command> + </scons_output> <para> @@ -707,21 +497,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=derived</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - +-. - +-f1.o - +-f2.o - +-f3.o - +-prog - +-f1.o - +-f2.o - +-f3.o - </screen> + <scons_output example="troubleshoot_tree1" suffix="5"> + <scons_output_command>scons -Q --tree=derived</scons_output_command> + </scons_output> <para> @@ -730,32 +508,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=derived,status</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - cc -o prog f1.o f2.o f3.o - E = exists - R = exists in repository only - b = implicit builder - B = explicit builder - S = side effect - P = precious - A = always build - C = current - N = no clean - H = no cache - - [E b ]+-. - [E B C ] +-f1.o - [E B C ] +-f2.o - [E B C ] +-f3.o - [E B C ] +-prog - [E B C ] +-f1.o - [E B C ] +-f2.o - [E B C ] +-f3.o - </screen> + <scons_output example="troubleshoot_tree1" suffix="6"> + <scons_output_command>scons -Q --tree=derived,status</scons_output_command> + </scons_output> <para> @@ -776,14 +531,34 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.'], - LIBS = ['foo'], - LIBPATH = ['.']) - env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) - env.Program('prog1.c') - env.Program('prog2.c') - </programlisting> + <scons_example name="troubleshoot_tree2"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.'], + LIBS = ['foo'], + LIBPATH = ['.']) +env.Library('foo', ['f1.c', 'f2.c', 'f3.c']) +env.Program('prog1.c') +env.Program('prog2.c') + </file> + <file name="prog1.c"> +#include "inc.h" + </file> + <file name="prog2.c"> +#include "inc.h" + </file> + <file name="f1.c"> +#include "inc.h" + </file> + <file name="f2.c"> +#include "inc.h" + </file> + <file name="f3.c"> +#include "inc.h" + </file> + <file name="inc.h"> +inc.h + </file> + </scons_example> <para> @@ -792,79 +567,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=all</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - ar rc libfoo.a f1.o f2.o f3.o - ranlib libfoo.a - cc -o prog1.o -c -I. prog1.c - cc -o prog1 prog1.o -L. -lfoo - cc -o prog2.o -c -I. prog2.c - cc -o prog2 prog2.o -L. -lfoo - +-. - +-SConstruct - +-f1.c - +-f1.o - | +-f1.c - | +-inc.h - +-f2.c - +-f2.o - | +-f2.c - | +-inc.h - +-f3.c - +-f3.o - | +-f3.c - | +-inc.h - +-inc.h - +-libfoo.a - | +-f1.o - | | +-f1.c - | | +-inc.h - | +-f2.o - | | +-f2.c - | | +-inc.h - | +-f3.o - | +-f3.c - | +-inc.h - +-prog1 - | +-prog1.o - | | +-prog1.c - | | +-inc.h - | +-libfoo.a - | +-f1.o - | | +-f1.c - | | +-inc.h - | +-f2.o - | | +-f2.c - | | +-inc.h - | +-f3.o - | +-f3.c - | +-inc.h - +-prog1.c - +-prog1.o - | +-prog1.c - | +-inc.h - +-prog2 - | +-prog2.o - | | +-prog2.c - | | +-inc.h - | +-libfoo.a - | +-f1.o - | | +-f1.c - | | +-inc.h - | +-f2.o - | | +-f2.c - | | +-inc.h - | +-f3.o - | +-f3.c - | +-inc.h - +-prog2.c - +-prog2.o - +-prog2.c - +-inc.h - </screen> + <scons_output example="troubleshoot_tree2" suffix="1"> + <scons_output_command>scons -Q --tree=all</scons_output_command> + </scons_output> <para> @@ -884,51 +589,9 @@ </para> - <screen> - % <userinput>scons -Q --tree=prune</userinput> - cc -o f1.o -c -I. f1.c - cc -o f2.o -c -I. f2.c - cc -o f3.o -c -I. f3.c - ar rc libfoo.a f1.o f2.o f3.o - ranlib libfoo.a - cc -o prog1.o -c -I. prog1.c - cc -o prog1 prog1.o -L. -lfoo - cc -o prog2.o -c -I. prog2.c - cc -o prog2 prog2.o -L. -lfoo - +-. - +-SConstruct - +-f1.c - +-f1.o - | +-f1.c - | +-inc.h - +-f2.c - +-f2.o - | +-f2.c - | +-inc.h - +-f3.c - +-f3.o - | +-f3.c - | +-inc.h - +-inc.h - +-libfoo.a - | +-[f1.o] - | +-[f2.o] - | +-[f3.o] - +-prog1 - | +-prog1.o - | | +-prog1.c - | | +-inc.h - | +-[libfoo.a] - +-prog1.c - +-[prog1.o] - +-prog2 - | +-prog2.o - | | +-prog2.c - | | +-inc.h - | +-[libfoo.a] - +-prog2.c - +-[prog2.o] - </screen> + <scons_output example="troubleshoot_tree2" suffix="2"> + <scons_output_command>scons -Q --tree=prune</scons_output_command> + </scons_output> <para> @@ -954,7 +617,15 @@ </para> - + <scons_example name="troubleshoot_presub"> + <file name="SConstruct"> +env = Environment(CPPPATH = ['.']) +env.Program('prog', 'prog.c') + </file> + <file name="prog.c"> +prog.c + </file> + </scons_example> <!-- @@ -962,20 +633,20 @@ shows the Python functions from the sconsdoc.py execution wrapper used to generate this manual, not the underlying command-line strings. - <scons_output example="presub"> + <scons_output example="troubleshoot_presub" suffix="1"> <scons_output_command>scons -Q - -debug=presub</scons_output_command> </scons_output> --> <screen> - % <userinput>scons -Q --debug=presub</userinput> - Building prog.o with action: - $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES - cc -o prog.o -c -I. prog.c - Building prog with action: - $SMART_LINKCOM - cc -o prog prog.o +% <userinput>scons -Q --debug=presub</userinput> +Building prog.o with action: + $CC -o $TARGET -c $CFLAGS $CCFLAGS $_CCOMCOM $SOURCES +cc -o prog.o -c -I. prog.c +Building prog with action: + $SMART_LINKCOM +cc -o prog prog.o </screen> </section> @@ -994,10 +665,21 @@ </para> - <programlisting> - env = Environment(LIBPATH = ['libs1', 'libs2']) - env.Program('prog.c', LIBS=['foo', 'bar']) - </programlisting> + <scons_example name="troubleshoot_findlibs"> + <file name="SConstruct" printme="1"> +env = Environment(LIBPATH = ['libs1', 'libs2']) +env.Program('prog.c', LIBS=['foo', 'bar']) + </file> + <file name="prog.c"> +prog.c + </file> + <file name="libs1/libfoo.a"> +libs1/libfoo.a + </file> + <file name="libs2/libbar.a"> +libs2/libbar.a + </file> + </scons_example> <para> @@ -1009,20 +691,9 @@ </para> - <screen> - % <userinput>scons -Q --debug=findlibs</userinput> - findlibs: looking for 'libfoo.a' in 'libs1' ... - findlibs: ... FOUND 'libfoo.a' in 'libs1' - findlibs: looking for 'libfoo.so' in 'libs1' ... - findlibs: looking for 'libfoo.so' in 'libs2' ... - findlibs: looking for 'libbar.a' in 'libs1' ... - findlibs: looking for 'libbar.a' in 'libs2' ... - findlibs: ... FOUND 'libbar.a' in 'libs2' - findlibs: looking for 'libbar.so' in 'libs1' ... - findlibs: looking for 'libbar.so' in 'libs2' ... - cc -o prog.o -c prog.c - cc -o prog prog.o -Llibs1 -Llibs2 -lfoo -lbar - </screen> + <scons_output example="troubleshoot_findlibs" suffix="1"> + <scons_output_command>scons -Q --debug=findlibs</scons_output_command> + </scons_output> </section> @@ -1038,25 +709,25 @@ </para> - <scons_example name="includes"> + <scons_example name="troubleshoot_includes"> <file name="SConstruct" printme="1"> - env = Environment(CPPPATH = ['inc1', 'inc2']) - env.Program('prog.c') +env = Environment(CPPPATH = ['inc1', 'inc2']) +env.Program('prog.c') </file> <file name="prog.c"> - #include "file1.h" - #include "file2.h" - prog.c +#include "file1.h" +#include "file2.h" +prog.c </file> <file name="inc1/file1.h"> - inc1/file1.h +inc1/file1.h </file> <file name="inc2/file2.h"> - inc2/file2.h +inc2/file2.h </file> </scons_example> - <scons_output example="includes"> + <scons_output example="troubleshoot_includes" suffix="1"> <scons_output_command>scons -Q - - debug=includes prog</scons_output_command> </scons_output> @@ -1086,9 +757,11 @@ </para> - <programlisting> - Program('prog.c') - </programlisting> + <scons_example name="troubleshoot_stacktrace"> + <file name="SConstruct" printme="1"> +Program('prog.c') + </file> + </scons_example> <para> @@ -1098,10 +771,9 @@ </para> - <screen> - % <userinput>scons -Q</userinput> - scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. - </screen> + <scons_output example="troubleshoot_stacktrace" suffix="1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> <para> @@ -1116,19 +788,9 @@ </para> - <screen> - % <userinput>scons -Q --debug=stacktrace</userinput> - scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. - scons: internal stack trace: - File "bootstrap/src/engine/SCons/Job.py", line 199, in start - task.prepare() - File "bootstrap/src/engine/SCons/Script/Main.py", line 168, in prepare - return SCons.Taskmaster.OutOfDateTask.prepare(self) - File "bootstrap/src/engine/SCons/Taskmaster.py", line 189, in prepare - executor.prepare() - File "bootstrap/src/engine/SCons/Executor.py", line 392, in prepare - raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0])) - </screen> + <scons_output example="troubleshoot_stacktrace" suffix="2"> + <scons_output_command>scons -Q --debug=stacktrace</scons_output_command> + </scons_output> <para> @@ -1175,74 +837,23 @@ </para> - <programlisting> - env = Environment(CPPPATH = ['.']) - env.Program('prog.c') - </programlisting> + <scons_example name="troubleshoot_taskmastertrace"> + <file name="SConstruct" printme="1"> +env = Environment(CPPPATH = ['.']) +env.Program('prog.c') + </file> + <file name="prog.c"> +#include "inc.h" +prog.c + </file> + <file name="inc.h"> +#define STRING "one" + </file> + </scons_example> - <screen> - % <userinput>scons -Q --taskmastertrace=- prog</userinput> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <no_state 0 'prog'> and its children: - Taskmaster: <no_state 0 'prog.o'> - Taskmaster: adjusted ref count: <pending 1 'prog'>, child 'prog.o' - Taskmaster: Considering node <no_state 0 'prog.o'> and its children: - Taskmaster: <no_state 0 'prog.c'> - Taskmaster: <no_state 0 'inc.h'> - Taskmaster: adjusted ref count: <pending 1 'prog.o'>, child 'prog.c' - Taskmaster: adjusted ref count: <pending 2 'prog.o'>, child 'inc.h' - Taskmaster: Considering node <no_state 0 'prog.c'> and its children: - Taskmaster: Evaluating <pending 0 'prog.c'> - - Task.make_ready_current(): node <pending 0 'prog.c'> - Task.prepare(): node <up_to_date 0 'prog.c'> - Task.executed_with_callbacks(): node <up_to_date 0 'prog.c'> - Task.postprocess(): node <up_to_date 0 'prog.c'> - Task.postprocess(): removing <up_to_date 0 'prog.c'> - Task.postprocess(): adjusted parent ref count <pending 1 'prog.o'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <no_state 0 'inc.h'> and its children: - Taskmaster: Evaluating <pending 0 'inc.h'> - - Task.make_ready_current(): node <pending 0 'inc.h'> - Task.prepare(): node <up_to_date 0 'inc.h'> - Task.executed_with_callbacks(): node <up_to_date 0 'inc.h'> - Task.postprocess(): node <up_to_date 0 'inc.h'> - Task.postprocess(): removing <up_to_date 0 'inc.h'> - Task.postprocess(): adjusted parent ref count <pending 0 'prog.o'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <pending 0 'prog.o'> and its children: - Taskmaster: <up_to_date 0 'prog.c'> - Taskmaster: <up_to_date 0 'inc.h'> - Taskmaster: Evaluating <pending 0 'prog.o'> - - Task.make_ready_current(): node <pending 0 'prog.o'> - Task.prepare(): node <executing 0 'prog.o'> - Task.execute(): node <executing 0 'prog.o'> - cc -o prog.o -c -I. prog.c - Task.executed_with_callbacks(): node <executing 0 'prog.o'> - Task.postprocess(): node <executed 0 'prog.o'> - Task.postprocess(): removing <executed 0 'prog.o'> - Task.postprocess(): adjusted parent ref count <pending 0 'prog'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: Considering node <pending 0 'prog'> and its children: - Taskmaster: <executed 0 'prog.o'> - Taskmaster: Evaluating <pending 0 'prog'> - - Task.make_ready_current(): node <pending 0 'prog'> - Task.prepare(): node <executing 0 'prog'> - Task.execute(): node <executing 0 'prog'> - cc -o prog prog.o - Task.executed_with_callbacks(): node <executing 0 'prog'> - Task.postprocess(): node <executed 0 'prog'> - - Taskmaster: Looking for a node to evaluate - Taskmaster: No candidate anymore. - </screen> + <scons_output example="troubleshoot_taskmastertrace" os="posix" suffix="1"> + <scons_output_command>scons -Q --taskmastertrace=- prog</scons_output_command> + </scons_output> <para> @@ -1332,3 +943,5 @@ </section> --> + +</chapter> |