diff options
Diffstat (limited to 'doc')
112 files changed, 911 insertions, 4376 deletions
diff --git a/doc/SConscript b/doc/SConscript index e0b3f71..54b620e 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the @@ -43,7 +43,7 @@ dist_doc_tar_gz = '$DISTDIR/scons-doc-${VERSION}.tar.gz' # if lynx is available to do the dump. # fig2dev = whereis('fig2dev') -epydoc = whereis('epydoc') +epydoc_cli = whereis('epydoc') groff = whereis('groff') lynx = whereis('lynx') man2html = whereis('man2html') @@ -121,7 +121,7 @@ scons_doc_files = list(map(chop, open(manifest_xml_in).readlines())) scons_doc_files = [File('#src/engine/'+x).rstr() for x in scons_doc_files] if not jw: - print "jw not found, skipping building User Guide." + print "doc: jw not found, skipping building User Guide." else: # # Always create a version.xml file containing the version information @@ -151,6 +151,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. builders_gen = os.path.join(build, 'user', 'builders.gen') builders_mod = os.path.join(build, 'user', 'builders.mod') + functions_gen = os.path.join(build, 'user', 'functions.gen') + functions_mod = os.path.join(build, 'user', 'functions.mod') tools_gen = os.path.join(build, 'user', 'tools.gen') tools_mod = os.path.join(build, 'user', 'tools.mod') variables_gen = os.path.join(build, 'user', 'variables.gen') @@ -163,11 +165,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. # vs. the other. The *.gen and *.mod targets will still be dependent # on the list of the files themselves. doc_output_files = [builders_gen, builders_mod, + functions_gen, functions_mod, tools_gen, tools_mod, variables_gen, variables_mod] b = env.Command(doc_output_files, scons_doc_files, - "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $( $SOURCES $)") + "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -f ${TARGETS[2]},${TARGETS[3]} -t ${TARGETS[4]},${TARGETS[5]} -v ${TARGETS[6]},${TARGETS[7]} $( $SOURCES $)") env.Depends(b, "$SCONS_PROC_PY") env.Local(b) @@ -403,11 +406,11 @@ for m in man_page_list: x = orig_env.SCons_revision(os.path.join(build, 'man', m), os.path.join('man', m)) -man_i_files = ['builders.man', 'tools.man', 'variables.man'] +man_i_files = ['builders.man', 'functions.man', 'tools.man', 'variables.man'] man_intermediate_files = [os.path.join(build, 'man', x) for x in man_i_files] -cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -t ${TARGETS[1]} -v ${TARGETS[2]} $( $SOURCES $)" +cmd = "$PYTHON $SCONS_PROC_PY --man -b ${TARGETS[0]} -f ${TARGETS[1]} -t ${TARGETS[2]} -v ${TARGETS[3]} $( $SOURCES $)" man_intermediate_files = env.Command(man_intermediate_files, scons_doc_files, cmd) @@ -458,8 +461,79 @@ for man_1 in man_page_list: tar_deps.append(html) tar_list.append(html) -if not epydoc: - print "epydoc not found, skipping building API documentation." +if not epydoc_cli: + try: + import epydoc + except ImportError: + epydoc = None + else: + # adding Epydoc builder using imported module + def epydoc_builder_action(target, source, env): + """ + Take a list of `source` files and build docs for them in + `target` dir. + + `target` and `source` are lists. + + Uses OUTDIR and EPYDOCFLAGS environment variables. + + http://www.scons.org/doc/2.0.1/HTML/scons-user/x3594.html + """ + + # the epydoc build process is the following: + # 1. build documentation index + # 2. feed doc index to writer for docs + + from epydoc.docbuilder import build_doc_index + from epydoc.docwriter.html import HTMLWriter + from epydoc.docwriter.latex import LatexWriter + + # first arg is a list where can be names of python package dirs, + # python files, object names or objects itself + docindex = build_doc_index([str(src) for src in source]) + if docindex == None: + return -1 + + if env['EPYDOCFLAGS'] == '--html': + html_writer = HTMLWriter(docindex, + docformat='restructuredText', + prj_name='SCons', + prj_url='http://www.scons.org/') + try: + html_writer.write(env['OUTDIR']) + except OSError: # If directory cannot be created or any file cannot + # be created or written to. + return -2 + + """ + # PDF support requires external Linux utilites, so it's not crossplatform. + # Leaving for now. + # http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/src/epydoc/cli.py + + elif env['EPYDOCFLAGS'] == '--pdf': + pdf_writer = LatexWriter(docindex, + docformat='restructuredText', + prj_name='SCons', + prj_url='http://www.scons.org/') + """ + return 0 + + epydoc_commands = [ + Delete('$OUTDIR'), + epydoc_builder_action, + Touch('$TARGET'), + ] + +else: # epydoc_cli is found + epydoc_commands = [ + Delete('$OUTDIR'), + '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES', + Touch('$TARGET'), + ] + + +if not epydoc_cli and not epydoc: + print "doc: epydoc not found, skipping building API documentation." else: # XXX Should be in common with reading the same thing in # the SConstruct file. @@ -475,40 +549,37 @@ else: e = os.path.join(build, '..', 'scons', 'engine') sources = [os.path.join(e, x) for x in sources] - epydoc_commands = [ - Delete('$OUTDIR'), - '$EPYDOC $EPYDOCFLAGS --debug --output $OUTDIR --docformat=restructuredText --name SCons --url http://www.scons.org/ $SOURCES', - Touch('$TARGET'), - ] - htmldir = os.path.join(build, 'HTML', 'scons-api') env.Command('${OUTDIR}/index.html', sources, epydoc_commands, - EPYDOC=epydoc, EPYDOCFLAGS='--html', OUTDIR=htmldir) + EPYDOC=epydoc_cli, EPYDOCFLAGS='--html', OUTDIR=htmldir) tar_deps.append(htmldir) tar_list.append(htmldir) - # PDF and PostScript and TeX are built from the - # same invocation. - api_dir = os.path.join(build, 'scons-api') - api_pdf = os.path.join(api_dir, 'api.pdf') - api_ps = os.path.join(api_dir, 'api.ps') - api_tex = os.path.join(api_dir, 'api.tex') - api_targets = [api_pdf, api_ps, api_tex] - env.Command(api_targets, sources, epydoc_commands, - EPYDOC=epydoc, EPYDOCFLAGS='--pdf', OUTDIR=api_dir) - Local(api_targets) - - pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf') - env.InstallAs(pdf_install, api_pdf) - tar_deps.append(pdf_install) - tar_list.append(pdf_install) - Local(pdf_install) - - ps_install = os.path.join(build, 'PS', 'scons-api.ps') - env.InstallAs(ps_install, api_ps) - tar_deps.append(ps_install) - tar_list.append(ps_install) - Local(ps_install) + if not epydoc_cli: + print "doc: command line epydoc is not found, skipping PDF/PS/Tex output" + else: + # PDF and PostScript and TeX are built from the + # same invocation. + api_dir = os.path.join(build, 'scons-api') + api_pdf = os.path.join(api_dir, 'api.pdf') + api_ps = os.path.join(api_dir, 'api.ps') + api_tex = os.path.join(api_dir, 'api.tex') + api_targets = [api_pdf, api_ps, api_tex] + env.Command(api_targets, sources, epydoc_commands, + EPYDOC=epydoc_cli, EPYDOCFLAGS='--pdf', OUTDIR=api_dir) + Local(api_targets) + + pdf_install = os.path.join(build, 'PDF', 'scons-api.pdf') + env.InstallAs(pdf_install, api_pdf) + tar_deps.append(pdf_install) + tar_list.append(pdf_install) + Local(pdf_install) + + ps_install = os.path.join(build, 'PS', 'scons-api.ps') + env.InstallAs(ps_install, api_ps) + tar_deps.append(ps_install) + tar_list.append(ps_install) + Local(ps_install) # # Now actually create the tar file of the documentation, diff --git a/doc/design/scons.mod b/doc/design/scons.mod index 012bc3e..33538fb 100644 --- a/doc/design/scons.mod +++ b/doc/design/scons.mod @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation An SCons-specific DTD module, for use with SCons DocBook documentation, that contains names, phrases, acronyms, etc. used diff --git a/doc/developer/architecture.xml b/doc/developer/architecture.xml index e7c2f56..c122148 100644 --- a/doc/developer/architecture.xml +++ b/doc/developer/architecture.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/branches.xml b/doc/developer/branches.xml index 8f88c3c..b88bccf 100644 --- a/doc/developer/branches.xml +++ b/doc/developer/branches.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/copyright.xml b/doc/developer/copyright.xml index d718e5e..f89ef84 100644 --- a/doc/developer/copyright.xml +++ b/doc/developer/copyright.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/cycle.xml b/doc/developer/cycle.xml index bb34db5..cca4422 100644 --- a/doc/developer/cycle.xml +++ b/doc/developer/cycle.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/main.xml b/doc/developer/main.xml index c72ad38..25c56bf 100644 --- a/doc/developer/main.xml +++ b/doc/developer/main.xml @@ -2,7 +2,7 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/packaging.xml b/doc/developer/packaging.xml index 2ecae8c..50d8e7b 100644 --- a/doc/developer/packaging.xml +++ b/doc/developer/packaging.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/preface.xml b/doc/developer/preface.xml index da2964c..b61d7b8 100644 --- a/doc/developer/preface.xml +++ b/doc/developer/preface.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/sourcetree.xml b/doc/developer/sourcetree.xml index 3c89189..305a134 100644 --- a/doc/developer/sourcetree.xml +++ b/doc/developer/sourcetree.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/developer/testing.xml b/doc/developer/testing.xml index ea01780..1287e19 100644 --- a/doc/developer/testing.xml +++ b/doc/developer/testing.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/man/scons-time.1 b/doc/man/scons-time.1 index dda1c13..69db49a 100644 --- a/doc/man/scons-time.1 +++ b/doc/man/scons-time.1 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -19,7 +19,7 @@ .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" -.\" doc/man/scons-time.1 5134 2010/08/16 23:02:40 bdeegan +.\" doc/man/scons-time.1 5357 2011/09/09 21:31:03 bdeegan .\" .\" ES - Example Start - indents and turns off line fill .de ES @@ -98,7 +98,7 @@ [\fB--which=\fIWHICH\fR] [\fIARGUMENTS\fR] .. -.TH SCONS-TIME 1 "August 2010" +.TH SCONS-TIME 1 "September 2011" .SH NAME scons-time \- generate and display SCons timing information '\"========================================================================== diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 5d2b795..bd0d965 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -19,9 +19,9 @@ .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" -.\" doc/man/scons.1 5134 2010/08/16 23:02:40 bdeegan +.\" doc/man/scons.1 5357 2011/09/09 21:31:03 bdeegan .\" -.TH SCONS 1 "August 2010" +.TH SCONS 1 "September 2011" .\" ES - Example Start - indents and turns off line fill .rm ES .de ES @@ -100,17 +100,17 @@ file, .B scons looks for a directory named .I site_scons -in the directory containing the +in various system directories (see below) and the directory containing the .I SConstruct -file; if it exists, +file; for each of those dirs which exists, .I site_scons -is added to sys.path, +is prepended to sys.path, the file .IR site_scons/site_init.py , is evaluated if it exists, and the directory .I site_scons/site_tools -is added to the default toolpath if it exist. +is prepended to the default toolpath if it exists. See the .I --no-site-dir and @@ -601,6 +601,12 @@ have been compiled with optimization files). .TP +--debug=duplicate +Print a line for each unlink/relink (or copy) of a variant file from +its source file. Includes debugging info for unlinking stale variant +files, as well as unlinking old targets before building them. + +.TP --debug=dtree A synonym for the newer .B --tree=derived @@ -664,6 +670,18 @@ Re-run SCons under the control of the Python debugger. .TP +--debug=prepare +Print a line each time any target (internal or external) +is prepared for building. +.B scons +prints this for each target it considers, even if that +target is up to date (see also --debug=explain). +This can help debug problems with targets that aren't being +built; it shows whether +.B scons +is at least considering them or not. + +.TP --debug=presub Print the raw command line used to build each target before the construction environment variables are substituted. @@ -1095,13 +1113,13 @@ any out-of-date target files, but do not execute the commands. .RI --no-site-dir Prevents the automatic addition of the standard .I site_scons -dir to +dirs to .IR sys.path . Also prevents loading the .I site_scons/site_init.py -module if it exists, and prevents adding +modules if they exist, and prevents adding their .I site_scons/site_tools -to the toolpath. +dirs to the toolpath. .\" .TP .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file @@ -1182,7 +1200,7 @@ Ignored for compatibility with GNU .RI --site-dir= dir Uses the named dir as the site dir rather than the default .I site_scons -dir. This dir will get prepended to +dirs. This dir will get prepended to .IR sys.path , the module .IR dir /site_init.py @@ -1190,6 +1208,48 @@ will get loaded if it exists, and .IR dir /site_tools will get added to the default toolpath. +The default set of +.I site_scons +dirs used when +.I --site-dir +is not specified depends on the system platform, as follows. Note +that the directories are examined in the order given, from most +generic to most specific, so the last-executed site_init.py file is +the most specific one (which gives it the chance to override +everything else), and the dirs are prepended to the paths, again so +the last dir examined comes first in the resulting path. + +.IP "Windows:" +.nf + %ALLUSERSPROFILE/Application Data/scons/site_scons + %USERPROFILE%/Local Settings/Application Data/scons/site_scons + %APPDATA%/scons/site_scons + %HOME%/.scons/site_scons + ./site_scons +.fi +.IP "Mac OS X:" +.nf + /Library/Application Support/SCons/site_scons + /opt/local/share/scons/site_scons (for MacPorts) + /sw/share/scons/site_scons (for Fink) + $HOME/Library/Application Support/SCons/site_scons + $HOME/.scons/site_scons + ./site_scons +.fi +.IP "Solaris:" +.nf + /opt/sfw/scons/site_scons + /usr/share/scons/site_scons + $HOME/.scons/site_scons + ./site_scons +.fi +.IP "Linux, HPUX, and other Posix-like systems:" +.nf + /usr/share/scons/site_scons + $HOME/.scons/site_scons + ./site_scons +.fi + .TP .RI --stack-size= KILOBYTES Set the size stack used to run threads to @@ -2269,7 +2329,7 @@ Builders by adding them to the .B SourceFileScanner object. -See the section "Scanner Objects," +See the section "Scanner Objects" below, for more information about defining your own Scanner objects and using the @@ -2351,4049 +2411,34 @@ and global functions supported by include: '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" -.TP -.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" -Creates an Action object for -the specified -.IR action . -See the section "Action Objects," -below, for a complete explanation of the arguments and behavior. - -Note that the -.BR env.Action () -form of the invocation will expand -construction variables in any argument strings, -including the -.I action -argument, at the time it is called -using the construction variables in the -.I env -construction environment through which -.BR env.Action () -was called. -The -.BR Action () -form delays all variable expansion -until the Action object is actually used. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddMethod( object, function ", [" name ]) -.TP -.RI env.AddMethod( function ", [" name ]) -When called with the -.BR AddMethod () -form, -adds the specified -.I function -to the specified -.I object -as the specified method -.IR name . -When called with the -.BR env.AddMethod () -form, -adds the specified -.I function -to the construction environment -.I env -as the specified method -.IR name . -In both cases, if -.I name -is omitted or -.BR None , -the name of the -specified -.I function -itself is used for the method name. - -Examples: - -.ES -# Note that the first argument to the function to -# be attached as a method must be the object through -# which the method will be called; the Python -# convention is to call it 'self'. -def my_method(self, arg): - print "my_method() got", arg - -# Use the global AddMethod() function to add a method -# to the Environment class. This -AddMethod(Environment, my_method) -env = Environment() -env.my_method('arg') - -# Add the function as a method, using the function -# name for the method call. -env = Environment() -env.AddMethod(my_method, 'other_method_name') -env.other_method_name('another arg') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddOption( arguments ) -This function adds a new command-line option to be recognized. -The specified -.I arguments -are the same as supported by the standard Python -.BR optparse.add_option () -method (with a few additional capabilities noted below); -see the documentation for -.B optparse -for a thorough discussion of its option-processing capabities. - -In addition to the arguments and values supported by the -.B optparse.add_option () -method, -the SCons -.BR AddOption () -function allows you to set the -.B nargs -keyword value to -.B '?' -(a string with just the question mark) -to indicate that the specified long option(s) take(s) an -.I optional -argument. -When -.B "nargs = '?'" -is passed to the -.BR AddOption () -function, the -.B const -keyword argument -may be used to supply the "default" -value that should be used when the -option is specified on the command line -without an explicit argument. - -If no -.B default= -keyword argument is supplied when calling -.BR AddOption (), -the option will have a default value of -.BR None . - -Once a new command-line option has been added with -.BR AddOption (), -the option value may be accessed using -.BR GetOption () -or -.BR env.GetOption (). -\" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet. -\" Uncomment this when that works. See tigris issue 2105. -\" The value may also be set, using -\" .BR SetOption () -\" or -\" .BR env.SetOption (), -\" if conditions in a -\" .B SConscript -\" require overriding any default value. -\" Note, however, that a -\" value specified on the command line will -\" .I always -\" override a value set by any SConscript file. - -Any specified -.B help= -strings for the new option(s) -will be displayed by the -.B -H -or -.B -h -options -(the latter only if no other help text is -specified in the SConscript files). -The help text for the local options specified by -.BR AddOption () -will appear below the SCons options themselves, -under a separate -.B "Local Options" -heading. -The options will appear in the help text -in the order in which the -.BR AddOption () -calls occur. - -Example: - -.ES -AddOption('--prefix', - dest='prefix', - nargs=1, type='string', - action='store', - metavar='DIR', - help='installation prefix') -env = Environment(PREFIX = GetOption('prefix')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddPostAction( target ", " action ) -.TP -.RI env.AddPostAction( target ", " action ) -Arranges for the specified -.I action -to be performed -after the specified -.I target -has been built. -The specified action(s) may be -an Action object, or anything that -can be converted into an Action object -(see below). - -When multiple targets are supplied, -the action may be called multiple times, -once after each action that generates -one or more targets in the list. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AddPreAction( target ", " action ) -.TP -.RI env.AddPreAction( target ", " action ) -Arranges for the specified -.I action -to be performed -before the specified -.I target -is built. -The specified action(s) may be -an Action object, or anything that -can be converted into an Action object -(see below). - -When multiple targets are specified, -the action(s) may be called multiple times, -once before each action that generates -one or more targets in the list. - -Note that if any of the targets are built in multiple steps, -the action will be invoked just -before the "final" action that specifically -generates the specified target(s). -For example, when building an executable program -from a specified source -.B .c -file via an intermediate object file: - -.ES -foo = Program('foo.c') -AddPreAction(foo, 'pre_action') -.EE - -The specified -.B pre_action -would be executed before -.B scons -calls the link command that actually -generates the executable program binary -.BR foo , -not before compiling the -.B foo.c -file into an object file. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Alias( alias ", [" targets ", [" action ]]) -.TP -.RI env.Alias( alias ", [" targets ", [" action ]]) -Creates one or more phony targets that -expand to one or more other targets. -An optional -.I action -(command) -or list of actions -can be specified that will be executed -whenever the any of the alias targets are out-of-date. -Returns the Node object representing the alias, -which exists outside of any file system. -This Node object, or the alias name, -may be used as a dependency of any other target, -including another alias. -.B Alias -can be called multiple times for the same -alias to add additional targets to the alias, -or additional actions to the list for this alias. - -Examples: - -.ES -Alias('install') -Alias('install', '/usr/bin') -Alias(['install', 'install-lib'], '/usr/local/lib') - -env.Alias('install', ['/usr/local/bin', '/usr/local/lib']) -env.Alias('install', ['/usr/local/man']) - -env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AllowSubstExceptions([ exception ", ...])" -Specifies the exceptions that will be allowed -when expanding construction variables. -By default, -any construction variable expansions that generate a -.B NameError -or -.BR IndexError -exception will expand to a -.B '' -(a null string) and not cause scons to fail. -All exceptions not in the specified list -will generate an error message -and terminate processing. - -If -.B AllowSubstExceptions -is called multiple times, -each call completely overwrites the previous list -of allowed exceptions. - -Example: - -.ES -# Requires that all construction variable names exist. -# (You may wish to do this if you want to enforce strictly -# that all construction variables must be defined before use.) -AllowSubstExceptions() - -# Also allow a string containing a zero-division expansion -# like '${1 / 0}' to evalute to ''. -AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI AlwaysBuild( target ", ...)" -.TP -.RI env.AlwaysBuild( target ", ...)" -Marks each given -.I target -so that it is always assumed to be out of date, -and will always be rebuilt if needed. -Note, however, that -.BR AlwaysBuild () -does not add its target(s) to the default target list, -so the targets will only be built -if they are specified on the command line, -or are a dependent of a target specified on the command line--but -they will -.I always -be built if so specified. -Multiple targets can be passed in to a single call to -.BR AlwaysBuild (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Append( key = val ", [...])" -Appends the specified keyword arguments -to the end of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the values of the construction variable -and the keyword argument are the same type, -then the two values will be simply added together. -Otherwise, the construction variable -and the value of the keyword argument -are both coerced to lists, -and the lists are added together. -(See also the Prepend method, below.) - -Example: - -.ES -env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) -This appends new path elements to the given path in the -specified external environment -.RB ( ENV -by default). -This will only add -any particular path once (leaving the last one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using -.B os.path.normpath -and -.BR os.path.normcase ). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. - -If -.I delete_existing -is 0, then adding a path that already exists -will not move it to the end; it will stay where it is in the list. - -Example: - -.ES -print 'before:',env['ENV']['INCLUDE'] -include_path = '/foo/bar:/foo' -env.AppendENVPath('INCLUDE', include_path) -print 'after:',env['ENV']['INCLUDE'] - -yields: -before: /foo:/biz -after: /biz:/foo/bar:/foo -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.AppendUnique( key = val ", [...], delete_existing=0)" -Appends the specified keyword arguments -to the end of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the construction variable being appended to is a list, -then any value(s) that already exist in the -construction variable will -.I not -be added again to the list. -However, if delete_existing is 1, -existing matching values are removed first, so -existing values in the arg list move to the end of the list. - -Example: - -.ES -env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -env.BitKeeper() -A factory function that -returns a Builder object -to be used to fetch source files -using BitKeeper. -The returned Builder -is intended to be passed to the -.B SourceCode -function. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Example: - -.ES -env.SourceCode('.', env.BitKeeper()) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) -.TP -.RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ]) -Deprecated synonyms for -.BR VariantDir () -and -.BR env.VariantDir (). -The -.I build_dir -argument becomes the -.I variant_dir -argument of -.BR VariantDir () -or -.BR env.VariantDir (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Builder( action ", [" arguments ]) -.TP -.RI env.Builder( action ", [" arguments ]) -Creates a Builder object for -the specified -.IR action . -See the section "Builder Objects," -below, for a complete explanation of the arguments and behavior. - -Note that the -.BR env.Builder () -form of the invocation will expand -construction variables in any arguments strings, -including the -.I action -argument, -at the time it is called -using the construction variables in the -.B env -construction environment through which -.BR env.Builder () -was called. -The -.BR Builder () -form delays all variable expansion -until after the Builder object is actually called. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI CacheDir( cache_dir ) -.TP -.RI env.CacheDir( cache_dir ) -Specifies that -.B scons -will maintain a cache of derived files in -.I cache_dir . -The derived files in the cache will be shared -among all the builds using the same -.BR CacheDir () -call. -Specifying a -.I cache_dir -of -.B None -disables derived file caching. - -Calling -.BR env.CacheDir () -will only affect targets built -through the specified construction environment. -Calling -.BR CacheDir () -sets a global default -that will be used by all targets built -through construction environments -that do -.I not -have an -.BR env.CacheDir () -specified. - -When a -.BR CacheDir () -is being used and -.B scons -finds a derived file that needs to be rebuilt, -it will first look in the cache to see if a -derived file has already been built -from identical input files and an identical build action -(as incorporated into the MD5 build signature). -If so, -.B scons -will retrieve the file from the cache. -If the derived file is not present in the cache, -.B scons -will rebuild it and -then place a copy of the built file in the cache -(identified by its MD5 build signature), -so that it may be retrieved by other -builds that need to build the same derived file -from identical inputs. - -Use of a specified -.BR CacheDir() -may be disabled for any invocation -by using the -.B --cache-disable -option. - -If the -.B --cache-force -option is used, -.B scons -will place a copy of -.I all -derived files in the cache, -even if they already existed -and were not built by this invocation. -This is useful to populate a cache -the first time -.BR CacheDir () -is added to a build, -or after using the -.B --cache-disable -option. - -When using -.BR CacheDir (), -.B scons -will report, -"Retrieved `file' from cache," -unless the -.B --cache-show -option is being used. -When the -.B --cache-show -option is used, -.B scons -will print the action that -.I would -have been used to build the file, -without any indication that -the file was actually retrieved from the cache. -This is useful to generate build logs -that are equivalent regardless of whether -a given derived file has been built in-place -or retrieved from the cache. - -The -.BR NoCache () -method can be used to disable caching of specific files. This can be -useful if inputs and/or outputs of some tool are impossible to -predict or prohibitively large. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Clean( targets ", " files_or_dirs ) -.TP -.RI env.Clean( targets ", " files_or_dirs ) -This specifies a list of files or directories which should be removed -whenever the targets are specified with the -.B -c -command line option. -The specified targets may be a list -or an individual target. -Multiple calls to -.BR Clean () -are legal, -and create new targets or add files and directories to the -clean list for the specified targets. - -Multiple files or directories should be specified -either as separate arguments to the -.BR Clean () -method, or as a list. -.BR Clean () -will also accept the return value of any of the construction environment -Builder methods. -Examples: - -The related -.BR NoClean () -function overrides calling -.BR Clean () -for the same target, -and any targets passed to both functions will -.I not -be removed by the -.B -c -option. - -Examples: - -.ES -Clean('foo', ['bar', 'baz']) -Clean('dist', env.Program('hello', 'hello.c')) -Clean(['foo', 'bar'], 'something_else_to_clean') -.EE - -In this example, -installing the project creates a subdirectory for the documentation. -This statement causes the subdirectory to be removed -if the project is deinstalled. -.ES -Clean(docdir, os.path.join(docdir, projectname)) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Command( target ", " source ", " action ", [" key = val ", ...])" -.TP -.RI env.Command( target ", " source ", " action ", [" key = val ", ...])" -Executes a specific action -(or list of actions) -to build a target file or files. -This is more convenient -than defining a separate Builder object -for a single special-case build. - -As a special case, the -.B source_scanner -keyword argument can -be used to specify -a Scanner object -that will be used to scan the sources. -(The global -.B DirScanner -object can be used -if any of the sources will be directories -that must be scanned on-disk for -changes to files that aren't -already specified in other Builder of function calls.) - -Any other keyword arguments specified override any -same-named existing construction variables. - -An action can be an external command, -specified as a string, -or a callable Python object; -see "Action Objects," below, -for more complete information. -Also note that a string specifying an external command -may be preceded by an -.B @ -(at-sign) -to suppress printing the command in question, -or by a -.B \- -(hyphen) -to ignore the exit status of the external command. - -Examples: - -.ES -env.Command('foo.out', 'foo.in', - "$FOO_BUILD < $SOURCES > $TARGET") - -env.Command('bar.out', 'bar.in', - ["rm -f $TARGET", - "$BAR_BUILD < $SOURCES > $TARGET"], - ENV = {'PATH' : '/usr/local/bin/'}) - -def rename(env, target, source): - import os - os.rename('.tmp', str(target[0])) - -env.Command('baz.out', 'baz.in', - ["$BAZ_BUILD < $SOURCES > .tmp", - rename ]) -.EE - -.IP -Note that the -.BR Command () -function will usually assume, by default, -that the specified targets and/or sources are Files, -if no other part of the configuration -identifies what type of entry it is. -If necessary, you can explicitly specify -that targets or source nodes should -be treated as directoriese -by using the -.BR Dir () -or -.BR env.Dir () -functions. - -Examples: - -.ES -env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET') - -env['DISTDIR'] = 'destination/directory' -env.Command(env.Dir('$DISTDIR')), None, make_distdir) -.EE - -.IP -(Also note that SCons will usually -automatically create any directory necessary to hold a target file, -so you normally don't need to create directories by hand.) - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ]) -.TP -.RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ]) -Creates a Configure object for integrated -functionality similar to GNU autoconf. -See the section "Configure Contexts," -below, for a complete explanation of the arguments and behavior. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Clone([ key = val ", ...])" -Return a separate copy of a construction environment. -If there are any keyword arguments specified, -they are added to the returned copy, -overwriting any existing values -for the keywords. - -Example: - -.ES -env2 = env.Clone() -env3 = env.Clone(CCFLAGS = '-g') -.EE -.IP -Additionally, a list of tools and a toolpath may be specified, as in -the Environment constructor: - -.ES -def MyTool(env): env['FOO'] = 'bar' -env4 = env.Clone(tools = ['msvc', MyTool]) -.EE - -The -.I parse_flags -keyword argument is also recognized: - -.ES -# create an environment for compiling programs that use wxWidgets -wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Copy([ key = val ", ...])" -A now-deprecated synonym for -.BR env.Clone() . - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.CVS( repository ", " module ) -A factory function that -returns a Builder object -to be used to fetch source files -from the specified -CVS -.IR repository . -The returned Builder -is intended to be passed to the -.B SourceCode -function. - -The optional specified -.I module -will be added to the beginning -of all repository path names; -this can be used, in essence, -to strip initial directory names -from the repository path names, -so that you only have to -replicate part of the repository -directory hierarchy in your -local build directory. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Examples: - -.ES -# Will fetch foo/bar/src.c -# from /usr/local/CVSROOT/foo/bar/src.c. -env.SourceCode('.', env.CVS('/usr/local/CVSROOT')) - -# Will fetch bar/src.c -# from /usr/local/CVSROOT/foo/bar/src.c. -env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo')) - -# Will fetch src.c -# from /usr/local/CVSROOT/foo/bar/src.c. -env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Decider( function ) -.TP -.RI env.Decider( function ) -Specifies that all up-to-date decisions for -targets built through this construction environment -will be handled by the specified -.IR function . -The -.I function -can be one of the following strings -that specify the type of decision function -to be performed: - -.RS 10 -.HP 6 -.B timestamp-newer -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is newer than the target file's timestamp. -This is the behavior of the classic Make utility, -and -.B make -can be used a synonym for -.BR timestamp-newer . - -.HP 6 -.B timestamp-match -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is different than the -timestamp recorded the last time the target was built. -This provides behavior very similar to the classic Make utility -(in particular, files are not opened up so that their -contents can be checksummed) -except that the target will also be rebuilt if a -dependency file has been restored to a version with an -.I earlier -timestamp, such as can happen when restoring files from backup archives. - -.HP 6 -.B MD5 -Specifies that a target shall be considered out of date and rebuilt -if the dependency's content has changed sine the last time -the target was built, -as determined be performing an MD5 checksum -on the dependency's contents -and comparing it to the checksum recorded the -last time the target was built. -.B content -can be used as a synonym for -.BR MD5 . - -.HP 6 -.B MD5-timestamp -Specifies that a target shall be considered out of date and rebuilt -if the dependency's content has changed sine the last time -the target was built, -except that dependencies with a timestamp that matches -the last time the target was rebuilt will be -assumed to be up-to-date and -.I not -rebuilt. -This provides behavior very similar -to the -.B MD5 -behavior of always checksumming file contents, -with an optimization of not checking -the contents of files whose timestamps haven't changed. -The drawback is that SCons will -.I not -detect if a file's content has changed -but its timestamp is the same, -as might happen in an automated script -that runs a build, -updates a file, -and runs the build again, -all within a single second. -.RE - -.IP -Examples: - -.ES -# Use exact timestamp matches by default. -Decider('timestamp-match') - -# Use MD5 content signatures for any targets built -# with the attached construction environment. -env.Decider('content') -.EE - -.IP -In addition to the above already-available functions, -the -.I function -argument may be an actual Python function -that takes the following three arguments: - -.RS 10 -.IP dependency -The Node (file) which -should cause the -.I target -to be rebuilt -if it has "changed" since the last tme -.I target was built. - -.IP target -The Node (file) being built. -In the normal case, -this is what should get rebuilt -if the -.I dependency -has "changed." - -.IP prev_ni -Stored information about the state of the -.I dependency -the last time the -.I target -was built. -This can be consulted to match various -file characteristics -such as the timestamp, -size, or content signature. -.RE - -.IP -The -.I function -should return a -.B True -(non-zero) -value if the -.I dependency -has "changed" since the last time -the -.I target -was built -(indicating that the target -.I should -be rebuilt), -and -.B False -(zero) -otherwise -(indicating that the target should -.I not -be rebuilt). -Note that the decision can be made -using whatever criteria are appopriate. -Ignoring some or all of the function arguments -is perfectly normal. - -Example: - -.ES -def my_decider(dependency, target, prev_ni): - return not os.path.exists(str(target)) - -env.Decider(my_decider) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Default( targets ) -.TP -.RI env.Default( targets ) -This specifies a list of default targets, -which will be built by -.B scons -if no explicit targets are given on the command line. -Multiple calls to -.BR Default () -are legal, -and add to the list of default targets. - -Multiple targets should be specified as -separate arguments to the -.BR Default () -method, or as a list. -.BR Default () -will also accept the Node returned by any -of a construction environment's -builder methods. - -Examples: - -.ES -Default('foo', 'bar', 'baz') -env.Default(['a', 'b', 'c']) -hello = env.Program('hello', 'hello.c') -env.Default(hello) -.EE -.IP -An argument to -.BR Default () -of -.B None -will clear all default targets. -Later calls to -.BR Default () -will add to the (now empty) default-target list -like normal. - -The current list of targets added using the -.BR Default () -function or method is available in the -.B DEFAULT_TARGETS -list; -see below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI DefaultEnvironment([ args ]) -Creates and returns a default construction environment object. -This construction environment is used internally by SCons -in order to execute many of the global functions in this list, -and to fetch source files transparently -from source code management systems. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Depends( target ", " dependency ) -.TP -.RI env.Depends( target ", " dependency ) -Specifies an explicit dependency; -the -.I target -will be rebuilt -whenever the -.I dependency -has changed. -Both the specified -.I target -and -.I dependency -can be a string -(usually the path name of a file or directory) -or Node objects, -or a list of strings or Node objects -(such as returned by a Builder call). -This should only be necessary -for cases where the dependency -is not caught by a Scanner -for the file. - -Example: - -.ES -env.Depends('foo', 'other-input-file-for-foo') - -mylib = env.Library('mylib.c') -installed_lib = env.Install('lib', mylib) -bar = env.Program('bar.c') - -# Arrange for the library to be copied into the installation -# directory before trying to build the "bar" program. -# (Note that this is for example only. A "real" library -# dependency would normally be configured through the $LIBS -# and $LIBPATH variables, not using an env.Depends() call.) - -env.Depends(bar, installed_lib) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Dictionary([ vars ]) -Returns a dictionary object -containing copies of all of the -construction variables in the environment. -If there are any variable names specified, -only the specified construction -variables are returned in the dictionary. - -Example: - -.ES -dict = env.Dictionary() -cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Dir( name ", [" directory ]) -.TP -.RI env.Dir( name ", [" directory ]) -This returns a Directory Node, -an object that represents the specified directory -.IR name . -.I name -can be a relative or absolute path. -.I directory -is an optional directory that will be used as the parent directory. -If no -.I directory -is specified, the current script's directory is used as the parent. - -If -.I name -is a list, SCons returns a list of Dir nodes. -Construction variables are expanded in -.IR name . - -Directory Nodes can be used anywhere you -would supply a string as a directory name -to a Builder method or function. -Directory Nodes have attributes and methods -that are useful in many situations; -see "File and Directory Nodes," below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Dump([ key ]) -Returns a pretty printable representation of the environment. -.IR key , -if not -.IR None , -should be a string containing the name of the variable of interest. - -This SConstruct: -.ES -env=Environment() -print env.Dump('CCCOM') -.EE -.IP -will print: -.ES -\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' -.EE - -.ES -env=Environment() -print env.Dump() -.EE -.IP -will print: -.ES -{ 'AR': 'ar', - 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET', - 'ARFLAGS': ['r'], - 'AS': 'as', - 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES', - 'ASFLAGS': [], - ... -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI EnsurePythonVersion( major ", " minor ) -.TP -.RI env.EnsurePythonVersion( major ", " minor ) -Ensure that the Python version is at least -.IR major . minor . -This function will -print out an error message and exit SCons with a non-zero exit code if the -actual Python version is not late enough. - -Example: - -.ES -EnsurePythonVersion(2,2) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI EnsureSConsVersion( major ", " minor ", [" revision ]) -.TP -.RI env.EnsureSConsVersion( major ", " minor ", [" revision ]) -Ensure that the SCons version is at least -.IR major.minor , -or -.IR major.minor.revision . -if -.I revision -is specified. -This function will -print out an error message and exit SCons with a non-zero exit code if the -actual SCons version is not late enough. - -Examples: - -.ES -EnsureSConsVersion(0,14) - -EnsureSConsVersion(0,96,90) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Environment([ key = value ", ...])" -.TP -.RI env.Environment([ key = value ", ...])" -Return a new construction environment -initialized with the specified -.IR key = value -pairs. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Execute( action ", [" strfunction ", " varlist ]) -.TP -.RI env.Execute( action ", [" strfunction ", " varlist ]) -Executes an Action object. -The specified -.IR action -may be an Action object -(see the section "Action Objects," -below, for a complete explanation of the arguments and behavior), -or it may be a command-line string, -list of commands, -or executable Python function, -each of which will be converted -into an Action object -and then executed. -The exit value of the command -or return value of the Python function -will be returned. - -Note that -.B scons -will print an error message if the executed -.I action -fails--that is, -exits with or returns a non-zero value. -.B scons -will -.I not , -however, -automatically terminate the build -if the specified -.I action -fails. -If you want the build to stop in response to a failed -.BR Execute () -call, -you must explicitly check for a non-zero return value: - -.ES -Execute(Copy('file.out', 'file.in')) - -if Execute("mkdir sub/dir/ectory"): - # The mkdir failed, don't try to build. - Exit(1) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Exit([ value ]) -.TP -.RI env.Exit([ value ]) -This tells -.B scons -to exit immediately -with the specified -.IR value . -A default exit value of -.B 0 -(zero) -is used if no value is specified. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Export( vars ) -.TP -.RI env.Export( vars ) -This tells -.B scons -to export a list of variables from the current -SConscript file to all other SConscript files. -The exported variables are kept in a global collection, -so subsequent calls to -.BR Export () -will over-write previous exports that have the same name. -Multiple variable names can be passed to -.BR Export () -as separate arguments or as a list. -Keyword arguments can be used to provide names and their values. -A dictionary can be used to map variables to a different name when exported. -Both local variables and global variables can be exported. - -Examples: - -.ES -env = Environment() -# Make env available for all SConscript files to Import(). -Export("env") - -package = 'my_name' -# Make env and package available for all SConscript files:. -Export("env", "package") - -# Make env and package available for all SConscript files: -Export(["env", "package"]) - -# Make env available using the name debug: -Export(debug = env) - -# Make env available using the name debug: -Export({"debug":env}) -.EE - -.IP -Note that the -.BR SConscript () -function supports an -.I exports -argument that makes it easier to to export a variable or -set of variables to a single SConscript file. -See the description of the -.BR SConscript () -function, below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI File( name ", [" directory ]) -.TP -.RI env.File( name ", [" directory ]) -This returns a -File Node, -an object that represents the specified file -.IR name . -.I name -can be a relative or absolute path. -.I directory -is an optional directory that will be used as the parent directory. - -If -.I name -is a list, SCons returns a list of File nodes. -Construction variables are expanded in -.IR name . - -File Nodes can be used anywhere you -would supply a string as a file name -to a Builder method or function. -File Nodes have attributes and methods -that are useful in many situations; -see "File and Directory Nodes," below. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindFile( file ", " dirs ) -.TP -.RI env.FindFile( file ", " dirs ) -Search for -.I file -in the path specified by -.IR dirs . -.I dirs -may be a list of directory names or a single directory name. -In addition to searching for files that exist in the filesystem, -this function also searches for derived files -that have not yet been built. - -Example: - -.ES -foo = env.FindFile('foo', ['dir1', 'dir2']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindInstalledFiles( ) -.TP -.RI env.FindInstalledFiles( ) -Returns the list of targets set up by the -.B Install() -or -.B InstallAs() -builders. - -This function serves as a convenient method to select the contents of -a binary package. - -Example: - -.ES -Install( '/bin', [ 'executable_a', 'executable_b' ] ) - -# will return the file node list -# [ '/bin/executable_a', '/bin/executable_b' ] -FindInstalledFiles() - -Install( '/lib', [ 'some_library' ] ) - -# will return the file node list -# [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ] -FindInstalledFiles() -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindSourceFiles( node = '"."' ) -.TP -.RI env.FindSourceFiles( node = '"."' ) - -Returns the list of nodes which serve as the source of the built files. -It does so by inspecting the dependency tree starting at the optional -argument -.B node -which defaults to the '"."'-node. It will then return all leaves of -.B node. -These are all children which have no further children. - -This function is a convenient method to select the contents of a Source -Package. - -Example: - -.ES -Program( 'src/main_a.c' ) -Program( 'src/main_b.c' ) -Program( 'main_c.c' ) - -# returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c'] -FindSourceFiles() - -# returns ['src/main_b.c', 'src/main_a.c' ] -FindSourceFiles( 'src' ) -.EE - -.IP -As you can see build support files (SConstruct in the above example) -will also be returned by this function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI FindPathDirs( variable ) -Returns a function -(actually a callable Python object) -intended to be used as the -.B path_function -of a Scanner object. -The returned object will look up the specified -.I variable -in a construction environment -and treat the construction variable's value as a list of -directory paths that should be searched -(like -.BR CPPPATH , -.BR LIBPATH , -etc.). - -Note that use of -.BR FindPathDirs () -is generally preferable to -writing your own -.B path_function -for the following reasons: -1) The returned list will contain all appropriate directories -found in source trees -(when -.BR VariantDir () -is used) -or in code repositories -(when -.BR Repository () -or the -.B \-Y -option are used). -2) scons will identify expansions of -.I variable -that evaluate to the same list of directories as, -in fact, the same list, -and avoid re-scanning the directories for files, -when possible. - -Example: - -.ES -def my_scan(node, env, path, arg): - # Code to scan file contents goes here... - return include_files - -scanner = Scanner(name = 'myscanner', - function = my_scan, - path_function = FindPathDirs('MYPATH')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Flatten( sequence ) -.TP -.RI env.Flatten( sequence ) -Takes a sequence (that is, a Python list or tuple) -that may contain nested sequences -and returns a flattened list containing -all of the individual elements in any sequence. -This can be helpful for collecting -the lists returned by calls to Builders; -other Builders will automatically -flatten lists specified as input, -but direct Python manipulation of -these lists does not. - -Examples: - -.ES -foo = Object('foo.c') -bar = Object('bar.c') - -# Because `foo' and `bar' are lists returned by the Object() Builder, -# `objects' will be a list containing nested lists: -objects = ['f1.o', foo, 'f2.o', bar, 'f3.o'] - -# Passing such a list to another Builder is all right because -# the Builder will flatten the list automatically: -Program(source = objects) - -# If you need to manipulate the list directly using Python, you need to -# call Flatten() yourself, or otherwise handle nested lists: -for object in Flatten(objects): - print str(object) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetBuildFailures() -Returns a list of exceptions for the -actions that failed while -attempting to build targets. -Each element in the returned list is a -.B BuildError -object -with the following attributes -that record various aspects -of the build failure: - -.B .node -The node that was being built -when the build failure occurred. - -.B .status -The numeric exit status -returned by the command or Python function -that failed when trying to build the -specified Node. - -.B .errstr -The SCons error string -describing the build failure. -(This is often a generic -message like "Error 2" -to indicate that an executed -command exited with a status of 2.) - -.B .filename -The name of the file or -directory that actually caused the failure. -This may be different from the -.B .node -attribute. -For example, -if an attempt to build a target named -.B sub/dir/target -fails because the -.B sub/dir -directory could not be created, -then the -.B .node -attribute will be -.B sub/dir/target -but the -.B .filename -attribute will be -.BR sub/dir . - -.B .executor -The SCons Executor object -for the target Node -being built. -This can be used to retrieve -the construction environment used -for the failed action. - -.B .action -The actual SCons Action object that failed. -This will be one specific action -out of the possible list of -actions that would have been -executed to build the target. - -.B .command -The actual expanded command that was executed and failed, -after expansion of -.BR $TARGET , -.BR $SOURCE , -and other construction variables. - -Note that the -.BR GetBuildFailures () -function -will always return an empty list -until any build failure has occurred, -which means that -.BR GetBuildFailures () -will always return an empty list -while the -.B SConscript -files are being read. -Its primary intended use is -for functions that will be -executed before SCons exits -by passing them to the -standard Python -.BR atexit.register () -function. -Example: - -.ES -import atexit - -def print_build_failures(): - from SCons.Script import GetBuildFailures - for bf in GetBuildFailures(): - print "%s failed: %s" % (bf.node, bf.errstr) - -atexit.register(print_build_failures) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetBuildPath( file ", [" ... ]) -.TP -.RI env.GetBuildPath( file ", [" ... ]) -Returns the -.B scons -path name (or names) for the specified -.I file -(or files). -The specified -.I file -or files -may be -.B scons -Nodes or strings representing path names. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetLaunchDir() -.TP -.RI env.GetLaunchDir() -Returns the absolute path name of the directory from which -.B scons -was initially invoked. -This can be useful when using the -.BR \-u , -.BR \-U -or -.BR \-D -options, which internally -change to the directory in which the -.B SConstruct -file is found. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI GetOption( name ) -.TP -.RI env.GetOption( name ) -This function provides a way to query the value of -SCons options set on scons command line -(or set using the -.IR SetOption () -function). -The options supported are: - -.RS 10 -.TP 6 -.B cache_debug -which corresponds to --cache-debug; -.TP 6 -.B cache_disable -which corresponds to --cache-disable; -.TP 6 -.B cache_force -which corresponds to --cache-force; -.TP 6 -.B cache_show -which corresponds to --cache-show; -.TP 6 -.B clean -which corresponds to -c, --clean and --remove; -.TP 6 -.B config -which corresponds to --config; -.TP 6 -.B directory -which corresponds to -C and --directory; -.TP 6 -.B diskcheck -which corresponds to --diskcheck -.TP 6 -.B duplicate -which corresponds to --duplicate; -.TP 6 -.B file -which corresponds to -f, --file, --makefile and --sconstruct; -.TP 6 -.B help -which corresponds to -h and --help; -.TP 6 -.B ignore_errors -which corresponds to --ignore-errors; -.TP 6 -.B implicit_cache -which corresponds to --implicit-cache; -.TP 6 -.B implicit_deps_changed -which corresponds to --implicit-deps-changed; -.TP 6 -.B implicit_deps_unchanged -which corresponds to --implicit-deps-unchanged; -.TP 6 -.B interactive -which corresponds to --interact and --interactive; -.TP 6 -.B keep_going -which corresponds to -k and --keep-going; -.TP 6 -.B max_drift -which corresponds to --max-drift; -.TP 6 -.B no_exec -which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; -.TP 6 -.B no_site_dir -which corresponds to --no-site-dir; -.TP 6 -.B num_jobs -which corresponds to -j and --jobs; -.TP 6 -.B profile_file -which corresponds to --profile; -.TP 6 -.B question -which corresponds to -q and --question; -.TP 6 -.B random -which corresponds to --random; -.TP 6 -.B repository -which corresponds to -Y, --repository and --srcdir; -.TP 6 -.B silent -which corresponds to -s, --silent and --quiet; -.TP 6 -.B site_dir -which corresponds to --site-dir; -.TP 6 -.B stack_size -which corresponds to --stack-size; -.TP 6 -.B taskmastertrace_file -which corresponds to --taskmastertrace; and -.TP 6 -.B warn -which corresponds to --warn and --warning. -.RE - -.IP -See the documentation for the -corresponding command line object for information about each specific -option. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Glob( pattern ", [" ondisk ", " source ", " strings ]) -.TP -.RI env.Glob( pattern ", [" ondisk ", " source ", " strings ]) -Returns Nodes (or strings) that match the specified -.IR pattern , -relative to the directory of the current -.B SConscript -file. -The -.BR env.Glob () -form performs string substition on -.I pattern -and returns whatever matches -the resulting expanded pattern. - -The specified -.I pattern -uses Unix shell style metacharacters for matching: - -.ES - * matches everything - ? matches any single character - [seq] matches any character in seq - [!seq] matches any char not in seq -.EE - -.IP -If the first character of a filename is a dot, -it must be matched explicitly. -Character matches do -.I not -span directory separators. - -The -.BR Glob () -knows about -repositories -(see the -.BR Repository () -function) -and source directories -(see the -.BR VariantDir () -function) -and -returns a Node (or string, if so configured) -in the local (SConscript) directory -if matching Node is found -anywhere in a corresponding -repository or source directory. - -The -.B ondisk -argument may be set to -.B False -(or any other non-true value) -to disable the search for matches on disk, -thereby only returning matches among -already-configured File or Dir Nodes. -The default behavior is to -return corresponding Nodes -for any on-disk matches found. - -The -.B source -argument may be set to -.B True -(or any equivalent value) -to specify that, -when the local directory is a -.BR VariantDir (), -the returned Nodes should be from the -corresponding source directory, -not the local directory. - -The -.B strings -argument may be set to -.B True -(or any equivalent value) -to have the -.BR Glob () -function return strings, not Nodes, -that represent the matched files or directories. -The returned strings will be relative to -the local (SConscript) directory. -(Note that This may make it easier to perform -arbitrary manipulation of file names, -but if the returned strings are -passed to a different -.B SConscript -file, -any Node translation will be relative -to the other -.B SConscript -directory, -not the original -.B SConscript -directory.) - -Examples: - -.ES -Program('foo', Glob('*.c')) -Zip('/tmp/everything', Glob('.??*') + Glob('*')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\".TP -'\".RI GlobalBuilders( flag ) -'\"When -'\".B flag -'\"is non-zero, -'\"adds the names of the default builders -'\"(Program, Library, etc.) -'\"to the global name space -'\"so they can be called without an explicit construction environment. -'\"(This is the default.) -'\"When -'\".B -'\"flag is zero, -'\"the names of the default builders are removed -'\"from the global name space -'\"so that an explicit construction environment is required -'\"to call all builders. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Help( text ) -.TP -.RI env.Help( text ) -This specifies help text to be printed if the -.B -h -argument is given to -.BR scons . -If -.BR Help -is called multiple times, the text is appended together in the order -that -.BR Help -is called. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Ignore( target ", " dependency ) -.TP -.RI env.Ignore( target ", " dependency ) -The specified dependency file(s) -will be ignored when deciding if -the target file(s) need to be rebuilt. - -You can also use -.BR Ignore() -to remove a target from the default build. -In order to do this you must specify the directory the target will -be built in as the target, and the file you want to skip building -as the dependency. - -Note that this will only remove the dependencies listed from -the files built by default. It will still be built if that -dependency is needed by another object being built. -See the third and forth examples below. - -Examples: - -.ES -env.Ignore('foo', 'foo.c') -env.Ignore('bar', ['bar1.h', 'bar2.h']) -env.Ignore('.','foobar.obj') -env.Ignore('bar','bar/foobar.obj') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Import( vars ) -.TP -.RI env.Import( vars ) -This tells -.B scons -to import a list of variables into the current SConscript file. This -will import variables that were exported with -.BR Export () -or in the -.I exports -argument to -.BR SConscript (). -Variables exported by -.BR SConscript () -have precedence. -Multiple variable names can be passed to -.BR Import () -as separate arguments or as a list. The variable "*" can be used -to import all variables. - -Examples: - -.ES -Import("env") -Import("env", "variable") -Import(["env", "variable"]) -Import("*") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Literal( string ) -.TP -.RI env.Literal( string ) -The specified -.I string -will be preserved as-is -and not have construction variables expanded. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Local( targets ) -.TP -.RI env.Local( targets ) -The specified -.I targets -will have copies made in the local tree, -even if an already up-to-date copy -exists in a repository. -Returns a list of the target Node or Nodes. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -\" .TP -\" .RI env.MergeShellPaths( arg ", [" prepend ]) -\" Merges the elements of the specified -\" .IR arg , -\" which must be a dictionary, to the construction -\" environment's copy of the shell environment -\" in env['ENV']. -\" (This is the environment which is passed -\" to subshells spawned by SCons.) -\" Note that -\" .I arg -\" must be a single value, -\" so multiple strings must -\" be passed in as a list, -\" not as separate arguments to -\" .BR env.MergeShellPaths (). - -\" New values are prepended to the environment variable by default, -\" unless prepend=0 is specified. -\" Duplicate values are always eliminated, -\" since this function calls -\" .B AppendENVPath -\" or -\" .B PrependENVPath -\" depending on the -\" .I prepend -\" argument. See those functions for more details. - -\" Examples: - -\" .ES -\" # Prepend a path to the shell PATH. -\" env.MergeShellPaths({'PATH':'/usr/local/bin'} ) -\" # Append two dirs to the shell INCLUDE. -\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) - -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.MergeFlags( arg ", [" unique ]) -Merges the specified -.I arg -values to the construction environment's construction variables. -If the -.I arg -argument is not a dictionary, -it is converted to one by calling -.B env.ParseFlags() -on the argument -before the values are merged. -Note that -.I arg -must be a single value, -so multiple strings must -be passed in as a list, -not as separate arguments to -.BR env.MergeFlags (). - -By default, -duplicate values are eliminated; -you can, however, specify -.B unique=0 -to allow duplicate -values to be added. -When eliminating duplicate values, -any construction variables that end with -the string -.B PATH -keep the left-most unique value. -All other construction variables keep -the right-most unique value. - -Examples: - -.ES -# Add an optimization flag to $CCFLAGS. -env.MergeFlags('-O3') - -# Combine the flags returned from running pkg-config with an optimization -# flag and merge the result into the construction variables. -env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) - -# Combine an optimization flag with the flags returned from running pkg-config -# twice and merge the result into the construction variables. -env.MergeFlags(['-O3', - '!pkg-config gtk+-2.0 --cflags --libs', - '!pkg-config libpng12 --cflags --libs']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI NoCache( target ", ...)" -.TP -.RI env.NoCache( target ", ...)" -Specifies a list of files which should -.I not -be cached whenever the -.BR CacheDir () -method has been activated. -The specified targets may be a list -or an individual target. - -Multiple files should be specified -either as separate arguments to the -.BR NoCache () -method, or as a list. -.BR NoCache () -will also accept the return value of any of the construction environment -Builder methods. - -Calling -.BR NoCache () -on directories and other non-File Node types has no effect because -only File Nodes are cached. - -Examples: - -.ES -NoCache('foo.elf') -NoCache(env.Program('hello', 'hello.c')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI NoClean( target ", ...)" -.TP -.RI env.NoClean( target ", ...)" -Specifies a list of files or directories which should -.I not -be removed whenever the targets (or their dependencies) -are specified with the -.B -c -command line option. -The specified targets may be a list -or an individual target. -Multiple calls to -.BR NoClean () -are legal, -and prevent each specified target -from being removed by calls to the -.B -c -option. - -Multiple files or directories should be specified -either as separate arguments to the -.BR NoClean () -method, or as a list. -.BR NoClean () -will also accept the return value of any of the construction environment -Builder methods. - -Calling -.BR NoClean () -for a target overrides calling -.BR Clean () -for the same target, -and any targets passed to both functions will -.I not -be removed by the -.B -c -option. - -Examples: - -.ES -NoClean('foo.elf') -NoClean(env.Program('hello', 'hello.c')) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.ParseConfig( command ", [" function ", " unique ]) -Calls the specified -.I function -to modify the environment as specified by the output of -.I command . -The default -.I function -is -.BR env.MergeFlags (), -which expects the output of a typical -.I *-config command -(for example, -.BR gtk-config ) -and adds the options -to the appropriate construction variables. -By default, -duplicate values are not -added to any construction variables; -you can specify -.B unique=0 -to allow duplicate -values to be added. - -Interpreted options -and the construction variables they affect -are as specified for the -.BR env.ParseFlags () -method (which this method calls). -See that method's description, below, -for a table of options and construction variables. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI ParseDepends( filename ", [" must_exist ", " only_one ]) -.TP -.RI env.ParseDepends( filename ", [" must_exist ", " only_one ]) -Parses the contents of the specified -.I filename -as a list of dependencies in the style of -.BR Make -or -.BR mkdep , -and explicitly establishes all of the listed dependencies. - -By default, -it is not an error -if the specified -.I filename -does not exist. -The optional -.I must_exist -argument may be set to a non-zero -value to have -scons -throw an exception and -generate an error if the file does not exist, -or is otherwise inaccessible. - -The optional -.I only_one -argument may be set to a non-zero -value to have -scons -thrown an exception and -generate an error -if the file contains dependency -information for more than one target. -This can provide a small sanity check -for files intended to be generated -by, for example, the -.B gcc -M -flag, -which should typically only -write dependency information for -one output file into a corresponding -.B .d -file. - -The -.I filename -and all of the files listed therein -will be interpreted relative to -the directory of the -.I SConscript -file which calls the -.B ParseDepends -function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.ParseFlags( flags ", ...)" -Parses one or more strings containing -typical command-line flags for GCC tool chains -and returns a dictionary with the flag values -separated into the appropriate SCons construction variables. -This is intended as a companion to the -.BR env.MergeFlags () -method, but allows for the values in the returned dictionary -to be modified, if necessary, -before merging them into the construction environment. -(Note that -.BR env.MergeFlags () -will call this method if its argument is not a dictionary, -so it is usually not necessary to call -.BR env.ParseFlags () -directly unless you want to manipulate the values.) - -If the first character in any string is -an exclamation mark (!), -the rest of the string is executed as a command, -and the output from the command is -parsed as GCC tool chain command-line flags -and added to the resulting dictionary. - -Flag values are translated accordig to the prefix found, -and added to the following construction variables: - -.ES --arch CCFLAGS, LINKFLAGS --D CPPDEFINES --framework FRAMEWORKS --frameworkdir= FRAMEWORKPATH --include CCFLAGS --isysroot CCFLAGS, LINKFLAGS --I CPPPATH --l LIBS --L LIBPATH --mno-cygwin CCFLAGS, LINKFLAGS --mwindows LINKFLAGS --pthread CCFLAGS, LINKFLAGS --std= CFLAGS --Wa, ASFLAGS, CCFLAGS --Wl,-rpath= RPATH --Wl,-R, RPATH --Wl,-R RPATH --Wl, LINKFLAGS --Wp, CPPFLAGS -- CCFLAGS -+ CCFLAGS, LINKFLAGS -.EE - -.IP -Any other strings not associated with options -are assumed to be the names of libraries -and added to the -.B LIBS -construction variable. - -Examples (all of which produce the same result): - -.ES -dict = env.ParseFlags('-O2 -Dfoo -Dbar=1') -dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1') -dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1']) -dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -env.Perforce() -A factory function that -returns a Builder object -to be used to fetch source files -from the Perforce source code management system. -The returned Builder -is intended to be passed to the -.B SourceCode -function. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Example: - -.ES -env.SourceCode('.', env.Perforce()) -.EE -.IP -Perforce uses a number of external -environment variables for its operation. -Consequently, this function adds the -following variables from the user's external environment -to the construction environment's -ENV dictionary: -P4CHARSET, -P4CLIENT, -P4LANGUAGE, -P4PASSWD, -P4PORT, -P4USER, -SystemRoot, -USER, -and -USERNAME. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Platform( string ) -Returns a callable object -that can be used to initialize -a construction environment using the -platform keyword of the Environment() method. - -Example: - -.ES -env = Environment(platform = Platform('win32')) -.EE -.TP -.RI env.Platform( string ) -Applies the callable object for the specified platform -.I string -to the environment through which the method was called. - -.ES -env.Platform('posix') -.EE -.IP -Note that the -.B win32 -platform adds the -.B SystemDrive -and -.B SystemRoot -variables from the user's external environment -to the construction environment's -.B ENV -dictionary. -This is so that any executed commands -that use sockets to connect with other systems -(such as fetching source files from -external CVS repository specifications like -.BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons ) -will work on Windows systems. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Progress( callable ", [" interval ]) -.TP -.RI Progress( string ", [" interval ", " file ", " overwrite ]) -.TP -.RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ]) -Allows SCons to show progress made during the build -by displaying a string or calling a function while -evaluating Nodes (e.g. files). - -If the first specified argument is a Python callable -(a function or an object that has a -.BR __call__ () -method), -the function will be called -once every -.I interval -times a Node is evaluated. -The callable will be passed the evaluated Node -as its only argument. -(For future compatibility, -it's a good idea to also add -.B *args -and -.B **kw -as arguments to your function or method. -This will prevent the code from breaking -if SCons ever changes the interface -to call the function with additional arguments in the future.) - -An example of a simple custom progress function -that prints a string containing the Node name -every 10 Nodes: - -.ES -def my_progress_function(node, *args, **kw): - print 'Evaluating node %s!' % node -Progress(my_progress_function, interval=10) -.EE -.IP -A more complicated example of a custom progress display object -that prints a string containing a count -every 100 evaluated Nodes. -Note the use of -.B \\\\r -(a carriage return) -at the end so that the string -will overwrite itself on a display: - -.ES -import sys -class ProgressCounter(object): - count = 0 - def __call__(self, node, *args, **kw): - self.count += 100 - sys.stderr.write('Evaluated %s nodes\\r' % self.count) -Progress(ProgressCounter(), interval=100) -.EE -.IP -If the first argument -.BR Progress () -is a string, -the string will be displayed -every -.I interval -evaluated Nodes. -The default is to print the string on standard output; -an alternate output stream -may be specified with the -.B file= -argument. -The following will print a series of dots -on the error output, -one dot for every 100 evaluated Nodes: - -.ES -import sys -Progress('.', interval=100, file=sys.stderr) -.EE -.IP -If the string contains the verbatim substring -.B $TARGET, -it will be replaced with the Node. -Note that, for performance reasons, this is -.I not -a regular SCons variable substition, -so you can not use other variables -or use curly braces. -The following example will print the name of -every evaluated Node, -using a -.B \\\\r -(carriage return) to cause each line to overwritten by the next line, -and the -.B overwrite= -keyword argument to make sure the previously-printed -file name is overwritten with blank spaces: - -.ES -import sys -Progress('$TARGET\\r', overwrite=True) -.EE -.IP -If the first argument to -.BR Progress () -is a list of strings, -then each string in the list will be displayed -in rotating fashion every -.I interval -evaluated Nodes. -This can be used to implement a "spinner" -on the user's screen as follows: - -.ES -Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Precious( target ", ...)" -.TP -.RI env.Precious( target ", ...)" -Marks each given -.I target -as precious so it is not deleted before it is rebuilt. Normally -.B scons -deletes a target before building it. -Multiple targets can be passed in to a single call to -.BR Precious (). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Prepend( key = val ", [...])" -Appends the specified keyword arguments -to the beginning of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the values of the construction variable -and the keyword argument are the same type, -then the two values will be simply added together. -Otherwise, the construction variable -and the value of the keyword argument -are both coerced to lists, -and the lists are added together. -(See also the Append method, above.) - -Example: - -.ES -env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) -This appends new path elements to the given path in the -specified external environment -.RB ( ENV -by default). -This will only add -any particular path once (leaving the first one it encounters and -ignoring the rest, to preserve path order), -and to help assure this, -will normalize all paths (using -.B os.path.normpath -and -.BR os.path.normcase ). -This can also handle the -case where the given old path variable is a list instead of a -string, in which case a list will be returned instead of a string. - -If -.I delete_existing -is 0, then adding a path that already exists -will not move it to the beginning; -it will stay where it is in the list. - -Example: - -.ES -print 'before:',env['ENV']['INCLUDE'] -include_path = '/foo/bar:/foo' -env.PrependENVPath('INCLUDE', include_path) -print 'after:',env['ENV']['INCLUDE'] -.EE - -The above exmaple will print: - -.ES -before: /biz:/foo -after: /foo/bar:/foo:/biz -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.PrependUnique( key = val ", delete_existing=0, [...])" -Appends the specified keyword arguments -to the beginning of construction variables in the environment. -If the Environment does not have -the specified construction variable, -it is simply added to the environment. -If the construction variable being appended to is a list, -then any value(s) that already exist in the -construction variable will -.I not -be added again to the list. -However, if delete_existing is 1, -existing matching values are removed first, so -existing values in the arg list move to the front of the list. - -Example: - -.ES -env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -env.RCS() -A factory function that -returns a Builder object -to be used to fetch source files -from RCS. -The returned Builder -is intended to be passed to the -.B SourceCode -function: - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Examples: - -.ES -env.SourceCode('.', env.RCS()) -.EE -.IP -Note that -.B scons -will fetch source files -from RCS subdirectories automatically, -so configuring RCS -as demonstrated in the above example -should only be necessary if -you are fetching from -RCS,v -files in the same -directory as the source files, -or if you need to explicitly specify RCS -for a specific subdirectory. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.Replace( key = val ", [...])" -Replaces construction variables in the Environment -with the specified keyword arguments. - -Example: - -.ES -env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Repository( directory ) -.TP -.RI env.Repository( directory ) -Specifies that -.I directory -is a repository to be searched for files. -Multiple calls to -.BR Repository () -are legal, -and each one adds to the list of -repositories that will be searched. - -To -.BR scons , -a repository is a copy of the source tree, -from the top-level directory on down, -which may contain -both source files and derived files -that can be used to build targets in -the local source tree. -The canonical example would be an -official source tree maintained by an integrator. -If the repository contains derived files, -then the derived files should have been built using -.BR scons , -so that the repository contains the necessary -signature information to allow -.B scons -to figure out when it is appropriate to -use the repository copy of a derived file, -instead of building one locally. - -Note that if an up-to-date derived file -already exists in a repository, -.B scons -will -.I not -make a copy in the local directory tree. -In order to guarantee that a local copy -will be made, -use the -.B Local() -method. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Requires( target ", " prerequisite ) -.TP -.RI env.Requires( target ", " prerequisite ) -Specifies an order-only relationship -between the specified target file(s) -and the specified prerequisite file(s). -The prerequisite file(s) -will be (re)built, if necessary, -.I before -the target file(s), -but the target file(s) do not actually -depend on the prerequisites -and will not be rebuilt simply because -the prerequisite file(s) change. - -Example: - -.ES -env.Requires('foo', 'file-that-must-be-built-before-foo') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Return([ vars "... , " stop= ]) -By default, -this stops processing the current SConscript -file and returns to the calling SConscript file -the values of the variables named in the -.I vars -string arguments. -Multiple strings contaning variable names may be passed to -.BR Return (). -Any strings that contain white space - -The optional -.B stop= -keyword argument may be set to a false value -to continue processing the rest of the SConscript -file after the -.BR Return () -call. -This was the default behavior prior to SCons 0.98. -However, the values returned -are still the values of the variables in the named -.I vars -at the point -.BR Return () -is called. - -Examples: - -.ES -# Returns without returning a value. -Return() - -# Returns the value of the 'foo' Python variable. -Return("foo") - -# Returns the values of the Python variables 'foo' and 'bar'. -Return("foo", "bar") - -# Returns the values of Python variables 'val1' and 'val2'. -Return('val1 val2') -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) -.TP -.RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ]) -Creates a Scanner object for -the specified -.IR function . -See the section "Scanner Objects," -below, for a complete explanation of the arguments and behavior. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -env.SCCS() -A factory function that -returns a Builder object -to be used to fetch source files -from SCCS. -The returned Builder -is intended to be passed to the -.B SourceCode -function. - -This function is deprecated. For details, see the entry for the -.B SourceCode -function. - -Example: - -.ES -env.SourceCode('.', env.SCCS()) -.EE -.IP -Note that -.B scons -will fetch source files -from SCCS subdirectories automatically, -so configuring SCCS -as demonstrated in the above example -should only be necessary if -you are fetching from -.I s.SCCS -files in the same -directory as the source files, -or if you need to explicitly specify SCCS -for a specific subdirectory. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) -'\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) -.TP -.RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ]) -'\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ]) -.TP -.RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) -'\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) -.TP -.RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ]) -'\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ]) -This tells -.B scons -to execute -one or more subsidiary SConscript (configuration) files. -Any variables returned by a called script using -.BR Return () -will be returned by the call to -.BR SConscript (). -There are two ways to call the -.BR SConscript () -function. - -The first way you can call -.BR SConscript () -is to explicitly specify one or more -.I scripts -as the first argument. -A single script may be specified as a string; -multiple scripts must be specified as a list -(either explicitly or as created by -a function like -.BR Split ()). -Examples: -.ES -SConscript('SConscript') # run SConscript in the current directory -SConscript('src/SConscript') # run SConscript in the src directory -SConscript(['src/SConscript', 'doc/SConscript']) -config = SConscript('MyConfig.py') -.EE - -The second way you can call -.BR SConscript () -is to specify a list of (sub)directory names -as a -.RI dirs= subdirs -keyword argument. -In this case, -.B scons -will, by default, -execute a subsidiary configuration file named -.B SConscript -in each of the specified directories. -You may specify a name other than -.B SConscript -by supplying an optional -.RI name= script -keyword argument. -The first three examples below have the same effect -as the first three examples above: -.ES -SConscript(dirs='.') # run SConscript in the current directory -SConscript(dirs='src') # run SConscript in the src directory -SConscript(dirs=['src', 'doc']) -SConscript(dirs=['sub1', 'sub2'], name='MySConscript') -.EE - -The optional -.I exports -argument provides a list of variable names or a dictionary of -named values to export to the -.IR script(s) . -These variables are locally exported only to the specified -.IR script(s) , -and do not affect the global pool of variables used by the -.BR Export () -function. -'\"If multiple dirs are provided, each script gets a fresh export. -The subsidiary -.I script(s) -must use the -.BR Import () -function to import the variables. -Examples: -.ES -foo = SConscript('sub/SConscript', exports='env') -SConscript('dir/SConscript', exports=['env', 'variable']) -SConscript(dirs='subdir', exports='env variable') -SConscript(dirs=['one', 'two', 'three'], exports='shared_info') -.EE - -If the optional -.I variant_dir -argument is present, it causes an effect equivalent to the -.BR VariantDir () -method described below. -(If -.I variant_dir -is not present, the -'\" .IR src_dir and -.I duplicate -'\" arguments are ignored.) -argument is ignored.) -The -.I variant_dir -'\" and -'\" .I src_dir -'\" arguments are interpreted relative to the directory of the calling -argument is interpreted relative to the directory of the calling -.B SConscript -file. -See the description of the -.BR VariantDir () -function below for additional details and restrictions. - -If -.I variant_dir -is present, -'\" but -'\" .IR src_dir " is not," -the source directory is the directory in which the -.B SConscript -file resides and the -.B SConscript -file is evaluated as if it were in the -.I variant_dir -directory: -.ES -SConscript('src/SConscript', variant_dir = 'build') -.EE -is equivalent to -.ES -VariantDir('build', 'src') -SConscript('build/SConscript') -.EE -This later paradigm is often used when the sources are -in the same directory as the -.BR SConstruct: -.ES -SConscript('SConscript', variant_dir = 'build') -.EE -is equivalent to -.ES -VariantDir('build', '.') -SConscript('build/SConscript') -.EE - -'\" If -'\" .IR variant_dir " and" -'\" .IR src_dir " are both present," -'\" xxxxx everything is in a state of confusion. -'\" .ES -'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.') -'\" runs src/SConscript in build/src, but -'\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src') -'\" runs lib/SConscript (in lib!). However, -'\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src') -'\" runs src/SConscript in build. Moreover, -'\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src') -'\" runs src/lib/SConscript in build/lib. Moreover, -'\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src') -'\" can't find build/src/lib/SConscript, even though it ought to exist. -'\" .EE -'\" is equivalent to -'\" .ES -'\" ???????????????? -'\" .EE -'\" and what about this alternative? -'\"TODO??? SConscript('build/SConscript', src_dir='src') - -Here are some composite examples: - -.ES -# collect the configuration information and use it to build src and doc -shared_info = SConscript('MyConfig.py') -SConscript('src/SConscript', exports='shared_info') -SConscript('doc/SConscript', exports='shared_info') -.EE - -.ES -# build debugging and production versions. SConscript -# can use Dir('.').path to determine variant. -SConscript('SConscript', variant_dir='debug', duplicate=0) -SConscript('SConscript', variant_dir='prod', duplicate=0) -.EE - -.ES -# build debugging and production versions. SConscript -# is passed flags to use. -opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' } -SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts) -opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' } -SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts) -.EE - -.ES -# build common documentation and compile for different architectures -SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0) -SConscript('src/SConscript', variant_dir='build/x86', duplicate=0) -SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConscriptChdir( value ) -.TP -.RI env.SConscriptChdir( value ) -By default, -.B scons -changes its working directory -to the directory in which each -subsidiary SConscript file lives. -This behavior may be disabled -by specifying either: - -.ES -SConscriptChdir(0) -env.SConscriptChdir(0) -.EE -.IP -in which case -.B scons -will stay in the top-level directory -while reading all SConscript files. -(This may be necessary when building from repositories, -when all the directories in which SConscript files may be found -don't necessarily exist locally.) -You may enable and disable -this ability by calling -SConscriptChdir() -multiple times. - -Example: - -.ES -env = Environment() -SConscriptChdir(0) -SConscript('foo/SConscript') # will not chdir to foo -env.SConscriptChdir(1) -SConscript('bar/SConscript') # will chdir to bar -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SConsignFile([ file , dbm_module ]) -.TP -.RI env.SConsignFile([ file , dbm_module ]) -This tells -.B scons -to store all file signatures -in the specified database -.IR file . -If the -.I file -name is omitted, -.B .sconsign -is used by default. -(The actual file name(s) stored on disk -may have an appropriated suffix appended -by the -.IR dbm_module .) -If -.I file -is not an absolute path name, -the file is placed in the same directory as the top-level -.B SConstruct -file. - -If -.I file -is -.BR None , -then -.B scons -will store file signatures -in a separate -.B .sconsign -file in each directory, -not in one global database file. -(This was the default behavior -prior to SCons 0.96.91 and 0.97.) - -The optional -.I dbm_module -argument can be used to specify -which Python database module -The default is to use a custom -.B SCons.dblite -module that uses pickled -Python data structures, -and which works on all Python versions. - -Examples: - -.ES -# Explicitly stores signatures in ".sconsign.dblite" -# in the top-level SConstruct directory (the -# default behavior). -SConsignFile() - -# Stores signatures in the file "etc/scons-signatures" -# relative to the top-level SConstruct directory. -SConsignFile("etc/scons-signatures") - -# Stores signatures in the specified absolute file name. -SConsignFile("/home/me/SCons/signatures") - -# Stores signatures in a separate .sconsign file -# in each directory. -SConsignFile(None) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.SetDefault(key = val ", [...])" -Sets construction variables to default values specified with the keyword -arguments if (and only if) the variables are not already set. -The following statements are equivalent: - -.ES -env.SetDefault(FOO = 'foo') - -if 'FOO' not in env: env['FOO'] = 'foo' -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SetOption( name ", " value ) -.TP -.RI env.SetOption( name ", " value ) -This function provides a way to set a select subset of the scons command -line options from a SConscript file. The options supported are: - -.RS 10 -.TP 6 -.B clean -which corresponds to -c, --clean and --remove; -.TP 6 -.B duplicate -which corresponds to --duplicate; -.TP 6 -.B help -which corresponds to -h and --help; -.TP 6 -.B implicit_cache -which corresponds to --implicit-cache; -.TP 6 -.B max_drift -which corresponds to --max-drift; -.TP 6 -.B no_exec -which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; -.TP 6 -.B num_jobs -which corresponds to -j and --jobs; -.TP 6 -.B random -which corresponds to --random; and -.TP 6 -.B stack_size -which corresponds to --stack-size. -.RE - -.IP -See the documentation for the -corresponding command line object for information about each specific -option. - -Example: - -.ES -SetOption('max_drift', 1) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SideEffect( side_effect ", " target ) -.TP -.RI env.SideEffect( side_effect ", " target ) -Declares -.I side_effect -as a side effect of building -.IR target . -Both -.I side_effect -and -.I target -can be a list, a file name, or a node. -A side effect is a target file that is created or updated -as a side effect of building other targets. -For example, a Windows PDB -file is created as a side effect of building the .obj -files for a static library, -and various log files are created updated -as side effects of various TeX commands. -If a target is a side effect of multiple build commands, -.B scons -will ensure that only one set of commands -is executed at a time. -Consequently, you only need to use this method -for side-effect targets that are built as a result of -multiple build commands. - -Because multiple build commands may update -the same side effect file, -by default the -.I side_effect -target is -.I not -automatically removed -when the -.I target -is removed by the -.B -c -option. -(Note, however, that the -.I side_effect -might be removed as part of -cleaning the directory in which it lives.) -If you want to make sure the -.I side_effect -is cleaned whenever a specific -.I target -is cleaned, -you must specify this explicitly -with the -.BR Clean () -or -.BR env.Clean () -function. - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SourceCode( entries ", " builder ) -.TP -.RI env.SourceCode( entries ", " builder ) -This function and its associate factory functions are deprecated. -There is no replacement. -The intended use was to keep a local tree in sync with an archive, -but in actuality the function only causes the archive -to be fetched on the first run. -Synchronizing with the archive is best done external to SCons. - -Arrange for non-existent source files to -be fetched from a source code management system -using the specified -.IR builder . -The specified -.I entries -may be a Node, string or list of both, -and may represent either individual -source files or directories in which -source files can be found. - -For any non-existent source files, -.B scons -will search up the directory tree -and use the first -.B SourceCode -builder it finds. -The specified -.I builder -may be -.BR None , -in which case -.B scons -will not use a builder to fetch -source files for the specified -.IR entries , -even if a -.B SourceCode -builder has been specified -for a directory higher up the tree. - -.B scons -will, by default, -fetch files from SCCS or RCS subdirectories -without explicit configuration. -This takes some extra processing time -to search for the necessary -source code management files on disk. -You can avoid these extra searches -and speed up your build a little -by disabling these searches as follows: - -.ES -env.SourceCode('.', None) -.EE - -.IP -Note that if the specified -.I builder -is one you create by hand, -it must have an associated -construction environment to use -when fetching a source file. - -.B scons -provides a set of canned factory -functions that return appropriate -Builders for various popular -source code management systems. -Canonical examples of invocation include: - -.ES -env.SourceCode('.', env.BitKeeper('/usr/local/BKsources')) -env.SourceCode('src', env.CVS('/usr/local/CVSROOT')) -env.SourceCode('/', env.RCS()) -env.SourceCode(['f1.c', 'f2.c'], env.SCCS()) -env.SourceCode('no_source.c', None) -.EE -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI env.subst( input ", [" raw ", " target ", " source ", " conv ]) -Performs construction variable interpolation -on the specified string or sequence argument -.IR input . - -By default, -leading or trailing white space will -be removed from the result. -and all sequences of white space -will be compressed to a single space character. -Additionally, any -.B $( -and -.B $) -character sequences will be stripped from the returned string, -The optional -.I raw -argument may be set to -.B 1 -if you want to preserve white space and -.BR $( - $) -sequences. -The -.I raw -argument may be set to -.B 2 -if you want to strip -all characters between -any -.B $( -and -.B $) -pairs -(as is done for signature calculation). - -If the input is a sequence -(list or tuple), -the individual elements of -the sequence will be expanded, -and the results will be returned as a list. - -The optional -.I target -and -.I source -keyword arguments -must be set to lists of -target and source nodes, respectively, -if you want the -.BR $TARGET , -.BR $TARGETS , -.BR $SOURCE -and -.BR $SOURCES -to be available for expansion. -This is usually necessary if you are -calling -.BR env.subst () -from within a Python function used -as an SCons action. - -Returned string values or sequence elements -are converted to their string representation by default. -The optional -.I conv -argument -may specify a conversion function -that will be used in place of -the default. -For example, if you want Python objects -(including SCons Nodes) -to be returned as Python objects, -you can use the Python -.B lambda -idiom to pass in an unnamed function -that simply returns its unconverted argument. - -Example: - -.ES -print env.subst("The C compiler is: $CC") - -def compile(target, source, env): - sourceDir = env.subst("${SOURCE.srcdir}", - target=target, - source=source) - -source_nodes = env.subst('$EXPAND_TO_NODELIST', - conv=lambda x: x) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -'\".TP -'\".RI Subversion( repository ", " module ) -'\"A factory function that -'\"returns a Builder object -'\"to be used to fetch source files -'\"from the specified Subversion -'\".IR repository . -'\"The returned Builder -'\"is intended to be passed to the -'\".B SourceCode -'\"function. -'\" -'\"The optional specified -'\".I module -'\"will be added to the beginning -'\"of all repository path names; -'\"this can be used, in essence, -'\"to strip initial directory names -'\"from the repository path names, -'\"so that you only have to -'\"replicate part of the repository -'\"directory hierarchy in your -'\"local build directory. -'\" -'\"This function is deprecated. For details, see the entry for the -'\".B SourceCode -'\"function. -'\" -'\"Example: -'\" -'\".ES -'\"# Will fetch foo/bar/src.c -'\"# from /usr/local/Subversion/foo/bar/src.c. -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion')) +'\" BEGIN GENERATED FUNCTION DESCRIPTIONS '\" -'\"# Will fetch bar/src.c -'\"# from /usr/local/Subversion/foo/bar/src.c. -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo')) +'\" The descriptions below of the various SCons functions are generated +'\" from the .xml files that live next to the various Python modules in +'\" the build enginer library. If you're reading this [gnt]roff file +'\" with an eye towards patching this man page, you can still submit +'\" a diff against this text, but it will have to be translated to a +'\" diff against the underlying .xml file before the patch is actually +'\" accepted. If you do that yourself, it will make it easier to +'\" integrate the patch. '\" -'\"# Will fetch src.c -'\"# from /usr/local/Subversion/foo/bar/src.c. -'\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar')) -'\".EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI SourceSignatures( type ) -.TP -.RI env.SourceSignatures( type ) -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -.BR Decider () -function for a more flexible and straightforward way -to configure SCons' decision-making. - -The -.BR SourceSignatures () -function tells -.B scons -how to decide if a source file -(a file that is not built from any other files) -has changed since the last time it -was used to build a particular target file. -Legal values are -.B "MD5" -or -.BR "timestamp" . - -If the environment method is used, -the specified type of source signature -is only used when deciding whether targets -built with that environment are up-to-date or must be rebuilt. -If the global function is used, -the specified type of source signature becomes the default -used for all decisions -about whether targets are up-to-date. - -.B "MD5" -means -.B scons -decides that a source file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild a particular target file. - -.B "timestamp" -means -.B scons -decides that a source file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild a particular target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -.I older -than the last time it was used to rebuild the target file.) - -There is no different between the two behaviors -for Python -.BR Value () -node objects. - -.B "MD5" -signatures take longer to compute, -but are more accurate than -.B "timestamp" -signatures. -The default value is -.BR "MD5" . - -Note that the default -.BR TargetSignatures () -setting (see below) -is to use this -.BR SourceSignatures () -setting for any target files that are used -to build other target files. -Consequently, changing the value of -.BR SourceSignatures () -will, by default, -affect the up-to-date decision for all files in the build -(or all files built with a specific construction environment -when -.BR env.SourceSignatures () -is used). - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Split( arg ) -.TP -.RI env.Split( arg ) -Returns a list of file names or other objects. -If arg is a string, -it will be split on strings of white-space characters -within the string, -making it easier to write long lists of file names. -If arg is already a list, -the list will be returned untouched. -If arg is any other type of object, -it will be returned as a list -containing just the object. - -Example: - -.ES -files = Split("f1.c f2.c f3.c") -files = env.Split("f4.c f5.c f6.c") -files = Split(""" - f7.c - f8.c - f9.c -""") -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Tag( node ", " tags ) -Annotates file or directory Nodes with -information about how the -.BR Package () -Builder should package those files or directories. -All tags are optional. - -Examples: - -.ES -# makes sure the built library will be installed with 0644 file -# access mode -Tag( Library( 'lib.c' ), UNIX_ATTR="0644" ) - -# marks file2.txt to be a documentation file -Tag( 'file2.txt', DOC ) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI TargetSignatures( type ) -.TP -.RI env.TargetSignatures( type ) -Note: Although it is not yet officially deprecated, -use of this function is discouraged. -See the -.BR Decider () -function for a more flexible and straightforward way -to configure SCons' decision-making. - -The -.BR TargetSignatures () -function tells -.B scons -how to decide if a target file -(a file that -.I is -built from any other files) -has changed since the last time it -was used to build some other target file. -Legal values are -.BR "build" ; -.BR "content" -(or its synonym -.BR "MD5" ); -.BR "timestamp" ; -or -.BR "source" . - -If the environment method is used, -the specified type of target signature is only used -for targets built with that environment. -If the global function is used, -the specified type of signature becomes the default -used for all target files that -don't have an explicit target signature type -specified for their environments. - -.B "content" -(or its synonym -.BR "MD5" ) -means -.B scons -decides that a target file has changed -if the MD5 checksum of its contents has changed since -the last time it was used to rebuild some other target file. -This means -.B scons -will open up -MD5 sum the contents -of target files after they're built, -and may decide that it does not need to rebuild -"downstream" target files if a file was -rebuilt with exactly the same contents as the last time. - -.B "timestamp" -means -.B scons -decides that a target file has changed -if its timestamp (modification time) has changed since -the last time it was used to rebuild some other target file. -(Note that although this is similar to the behavior of Make, -by default it will also rebuild if the dependency is -.I older -than the last time it was used to rebuild the target file.) - -.B "source" -means -.B scons -decides that a target file has changed -as specified by the corresponding -.BR SourceSignatures () -setting -.BR "" ( "MD5" -or -.BR "timestamp" ). -This means that -.B scons -will treat all input files to a target the same way, -regardless of whether they are source files -or have been built from other files. - -.B "build" -means -.B scons -decides that a target file has changed -if it has been rebuilt in this invocation -or if its content or timestamp have changed -as specified by the corresponding -.BR SourceSignatures () -setting. -This "propagates" the status of a rebuilt file -so that other "downstream" target files -will always be rebuilt, -even if the contents or the timestamp -have not changed. - -.B "build" -signatures are fastest because -.B "content" -(or -.BR "MD5" ) -signatures take longer to compute, -but are more accurate than -.B "timestamp" -signatures, -and can prevent unnecessary "downstream" rebuilds -when a target file is rebuilt to the exact same contents -as the previous build. -The -.B "source" -setting provides the most consistent behavior -when other target files may be rebuilt from -both source and target input files. -The default value is -.BR "source" . - -Because the default setting is -.BR "source" , -using -.BR SourceSignatures () -is generally preferable to -.BR TargetSignatures () , -so that the up-to-date decision -will be consistent for all files -(or all files built with a specific construction environment). -Use of -.BR TargetSignatures () -provides specific control for how built target files -affect their "downstream" dependencies. - +'\" BEGIN GENERATED FUNCTION DESCRIPTIONS '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Tool( string [, toolpath ", " **kw ]) -Returns a callable object -that can be used to initialize -a construction environment using the -tools keyword of the Environment() method. -The object may be called with a construction -environment as an argument, -in which case the object will -add the necessary variables -to the construction environment -and the name of the tool will be added to the -.B $TOOLS -construction variable. - -Additional keyword arguments are passed to the tool's -.B generate() -method. - -Examples: - -.ES -env = Environment(tools = [ Tool('msvc') ]) - -env = Environment() -t = Tool('msvc') -t(env) # adds 'msvc' to the TOOLS variable -u = Tool('opengl', toolpath = ['tools']) -u(env) # adds 'opengl' to the TOOLS variable -.EE -.TP -.RI env.Tool( string [, toolpath ", " **kw ]) -Applies the callable object for the specified tool -.I string -to the environment through which the method was called. - -Additional keyword arguments are passed to the tool's -.B generate() -method. - -.ES -env.Tool('gcc') -env.Tool('opengl', toolpath = ['build/tools']) -.EE - +.so functions.man '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI Value( value ", [" built_value ]) -.TP -.RI env.Value( value ", [" built_value ]) -Returns a Node object representing the specified Python value. Value -Nodes can be used as dependencies of targets. If the result of -calling -.BR str( value ) -changes between SCons runs, any targets depending on -.BR Value( value ) -will be rebuilt. -(This is true even when using timestamps to decide if -files are up-to-date.) -When using timestamp source signatures, Value Nodes' -timestamps are equal to the system time when the Node is created. - -The returned Value Node object has a -.BR write () -method that can be used to "build" a Value Node -by setting a new value. -The optional -.I built_value -argument can be specified -when the Value Node is created -to indicate the Node should already be considered -"built." -There is a corresponding -.BR read () -method that will return the built value of the Node. - -Examples: - -.ES -env = Environment() - -def create(target, source, env): - # A function that will write a 'prefix=$SOURCE' - # string into the file name specified as the - # $TARGET. - f = open(str(target[0]), 'wb') - f.write('prefix=' + source[0].get_contents()) - -# Fetch the prefix= argument, if any, from the command -# line, and use /usr/local as the default. -prefix = ARGUMENTS.get('prefix', '/usr/local') - -# Attach a .Config() builder for the above function action -# to the construction environment. -env['BUILDERS']['Config'] = Builder(action = create) -env.Config(target = 'package-config', source = Value(prefix)) - -def build_value(target, source, env): - # A function that "builds" a Python Value by updating - # the the Python value with the contents of the file - # specified as the source of the Builder call ($SOURCE). - target[0].write(source[0].get_contents()) - -output = env.Value('before') -input = env.Value('after') - -# Attach a .UpdateValue() builder for the above function -# action to the construction environment. -env['BUILDERS']['UpdateValue'] = Builder(action = build_value) -env.UpdateValue(target = Value(output), source = Value(input)) -.EE - -'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -.TP -.RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -Use the -.BR VariantDir () -function to create a copy of your sources in another location: -if a name under -.IR variant_dir -is not found but exists under -.IR src_dir , -the file or directory is copied to -.IR variant_dir . -Target files can be built in a different directory -than the original sources by simply refering to the sources (and targets) -within the variant tree. - -.BR VariantDir () -can be called multiple times with the same -.I src_dir -to set up multiple builds with different options -.RI ( variants ). -The -.I src_dir -location must be in or underneath the SConstruct file's directory, and -.I variant_dir -may not be underneath -.IR src_dir . -'\"TODO: Can the above restrictions be clarified or relaxed? -'\"TODO: The latter restriction is clearly not completely right; -'\"TODO: src_dir = '.' works fine with a build dir under it. - -The default behavior is for -.B scons -to physically duplicate the source files in the variant tree. -Thus, a build performed in the variant tree is guaranteed to be identical -to a build performed in the source tree even if -intermediate source files are generated during the build, -or preprocessors or other scanners search for included files -relative to the source file, -or individual compilers or other invoked tools are hard-coded -to put derived files in the same directory as source files. - -If possible on the platform, -the duplication is performed by linking rather than copying; -see also the -.IR --duplicate -command-line option. -Moreover, only the files needed for the build are duplicated; -files and directories that are not used are not present in -.IR variant_dir . - -Duplicating the source tree may be disabled by setting the -.I duplicate -argument to 0 (zero). -This will cause -.B scons -to invoke Builders using the path names of source files in -.I src_dir -and the path names of derived files within -.IR variant_dir . -This is always more efficient than -.IR duplicate =1, -and is usually safe for most builds -(but see above for cases that may cause problems). - -Note that -.BR VariantDir () -works most naturally with a subsidiary SConscript file. -However, you would then call the subsidiary SConscript file -not in the source directory, but in the -.I variant_dir , -regardless of the value of -.IR duplicate . -This is how you tell -.B scons -which variant of a source tree to build: - -.ES -# run src/SConscript in two variant directories -VariantDir('build/variant1', 'src') -SConscript('build/variant1/SConscript') -VariantDir('build/variant2', 'src') -SConscript('build/variant2/SConscript') -.EE - -.IP -See also the -.BR SConscript () -function, described above, -for another way to specify a variant directory -in conjunction with calling a subsidiary SConscript file. - -Examples: - -.ES -# use names in the build directory, not the source directory -VariantDir('build', 'src', duplicate=0) -Program('build/prog', 'build/source.c') -.EE - -.ES -# this builds both the source and docs in a separate subtree -VariantDir('build', '.', duplicate=0) -SConscript(dirs=['build/src','build/doc']) -.EE - -.ES -# same as previous example, but only uses SConscript -SConscript(dirs='src', variant_dir='build/src', duplicate=0) -SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) -.EE - +'\" END GENERATED FUNCTION DESCRIPTIONS +'\" +'\" The descriptions above of the various SCons functions are generated +'\" from the .xml files that live next to the various Python modules in +'\" the build enginer library. If you're reading this [gnt]roff file +'\" with an eye towards patching this man page, you can still submit +'\" a diff against this text, but it will have to be translated to a +'\" diff against the underlying .xml file before the patch is actually +'\" accepted. If you do that yourself, it will make it easier to +'\" integrate the patch. +'\" +'\" END GENERATED FUNCTION DESCRIPTIONS '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -.TP -.RI WhereIs( program ", [" path ", " pathext ", " reject ]) -.TP -.RI env.WhereIs( program ", [" path ", " pathext ", " reject ]) - -Searches for the specified executable -.I program, -returning the full path name to the program -if it is found, -and returning None if not. -Searches the specified -.I path, -the value of the calling environment's PATH -(env['ENV']['PATH']), -or the user's current external PATH -(os.environ['PATH']) -by default. -On Windows systems, searches for executable -programs with any of the file extensions -listed in the specified -.I pathext, -the calling environment's PATHEXT -(env['ENV']['PATHEXT']) -or the user's current PATHEXT -(os.environ['PATHEXT']) -by default. -Will not select any -path name or names -in the specified -.I reject -list, if any. .SS SConscript Variables In addition to the global functions and methods, @@ -8105,14 +4150,14 @@ implicit dependencies based only on the target file and the construction environment, .I not -for implicit -(See the section "Scanner Objects," below, +for implicit dependencies based on source files. +(See the section "Scanner Objects" below, for information about creating Scanner objects.) .IP source_scanner A Scanner object that will be invoked to -find implicit dependences in +find implicit dependencies in any source files used to build this target file. This is where you would @@ -8129,7 +4174,7 @@ for on-disk changes to files that .B scons does not know about from other Builder or function calls. -(See the section "Scanner Objects," below, +(See the section "Scanner Objects" below, for information about creating your own Scanner objects.) .IP target_factory @@ -9234,7 +5279,7 @@ to enclose arbitrary Python code to be evaluated. (In fact, this is how the above modifiers are substituted, they are simply attributes of the Python objects that represent TARGET, SOURCES, etc.) -See the section "Python Code Substitution," below, +See the section "Python Code Substitution" below, for more thorough examples of how this can be used. @@ -9411,9 +5456,9 @@ function accepts the following arguments: This can be either: 1) a Python function that will process the Node (file) -and return a list of strings (file names) +and return a list of File Nodes representing the implicit -dependencies found in the contents; +dependencies (file names) found in the contents; or: 2) a dictionary that maps keys (typically the file suffix, but see below for more discussion) @@ -9587,7 +5632,7 @@ def xyz_scan(node, env, path): XYZScanner = Scanner(xyz_scan) -SourceFileScanner.add_scanner('.xyx', XYZScanner) +SourceFileScanner.add_scanner('.xyz', XYZScanner) env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz']) .EE @@ -9856,7 +5901,7 @@ include_re = re.compile(r'^include\\s+(\\S+)$', re.M) def kfile_scan(node, env, path, arg): contents = node.get_text_contents() includes = include_re.findall(contents) - return includes + return env.File(includes) kscan = Scanner(name = 'kfile', function = kfile_scan, @@ -9872,6 +5917,14 @@ env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET') bar_in.target_scanner = kscan .EE +It is important to note that you +have to return a list of File nodes from the scan function, simple +strings for the file names won't do. As in the examples we are showing here, +you can use the +.BR File() +function of your current Environment in order to create nodes on the fly from +a sequence of file names with relative paths. + Here is a similar but more complete example that searches a path of directories (specified as the @@ -9880,30 +5933,35 @@ construction variable) for files that actually exist: .ES +import re +import os include_re = re.compile(r'^include\\s+(\\S+)$', re.M) def my_scan(node, env, path, arg): - contents = node.get_text_contents() - includes = include_re.findall(contents) - if includes == []: + contents = node.get_text_contents() + includes = include_re.findall(contents) + if includes == []: return [] results = [] for inc in includes: for dir in path: - file = dir + os.sep + inc + file = str(dir) + os.sep + inc if os.path.exists(file): results.append(file) break - return results + return env.File(results) scanner = Scanner(name = 'myscanner', function = my_scan, argument = None, skeys = ['.x'], - path_function = FindPathDirs('MYPATH'), + path_function = FindPathDirs('MYPATH') ) scanners = Environment().Dictionary('SCANNERS') -env = Environment(SCANNERS = scanners + [scanner]) +env = Environment(SCANNERS = scanners + [scanner], + MYPATH = ['incs']) + +env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') .EE The @@ -9913,7 +5971,13 @@ function used in the previous example returns a function that will return a list of directories specified in the .B $MYPATH -construction variable. +construction variable. It lets SCons detect the file +.B incs/foo.inc +, even if +.B foo.x +contains the line +.B include foo.inc +only. If you need to customize how the search path is derived, you would provide your own .B path_function @@ -9934,7 +5998,7 @@ scanner = Scanner(name = 'myscanner', function = my_scan, argument = None, skeys = ['.x'], - path_function = pf, + path_function = pf ) .EE diff --git a/doc/man/sconsign.1 b/doc/man/sconsign.1 index d7f7ef9..2cd2fca 100644 --- a/doc/man/sconsign.1 +++ b/doc/man/sconsign.1 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +.\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the @@ -19,7 +19,7 @@ .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" -.\" doc/man/sconsign.1 5134 2010/08/16 23:02:40 bdeegan +.\" doc/man/sconsign.1 5357 2011/09/09 21:31:03 bdeegan .\" .\" ES - Example Start - indents and turns off line fill .de ES @@ -31,7 +31,7 @@ .RE .fi .. -.TH SCONSIGN 1 "August 2010" +.TH SCONSIGN 1 "September 2011" .SH NAME sconsign \- print SCons .sconsign file information .SH SYNOPSIS diff --git a/doc/python10/scons.mod b/doc/python10/scons.mod index ee5b1bb..bec5425 100644 --- a/doc/python10/scons.mod +++ b/doc/python10/scons.mod @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation An SCons-specific DTD module, for use with SCons DocBook documentation, that contains names, phrases, acronyms, etc. used diff --git a/doc/scons.mod b/doc/scons.mod index b1993d4..73ea8f3 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation An SCons-specific DTD module, for use with SCons DocBook documentation, that contains names, phrases, acronyms, etc. used @@ -100,6 +100,7 @@ <!ENTITY debug-explain "<literal>--debug=explain</literal>"> <!ENTITY debug-findlibs "<literal>--debug=findlibs</literal>"> <!ENTITY debug-includes "<literal>--debug=includes</literal>"> +<!ENTITY debug-prepare "<literal>--debug=prepare</literal>"> <!ENTITY debug-presub "<literal>--debug=presub</literal>"> <!ENTITY debug-stacktrace "<literal>--debug=stacktrace</literal>"> <!ENTITY implicit-cache "<literal>--implicit-cache</literal>"> @@ -180,6 +181,7 @@ <!ENTITY Depends "<function>Depends</function>"> <!ENTITY Dir "<function>Dir</function>"> <!ENTITY Dump "<function>Dump</function>"> +<!ENTITY Duplicate "<function>Duplicate</function>"> <!ENTITY Entry "<function>Entry</function>"> <!ENTITY EnumOption "<function>EnumOption</function>"> <!ENTITY EnumVariable "<function>EnumVariable</function>"> diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index ef273d3..0994f2b 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -17,6 +17,7 @@ errors.xml example.xml factories.xml file-removal.xml +functions.xml hierarchy.xml install.xml java.xml diff --git a/doc/user/README b/doc/user/README index 773fbc2..7ebdb93 100644 --- a/doc/user/README +++ b/doc/user/README @@ -1,4 +1,4 @@ -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation When adding a new file, add it to main.xml and MANIFEST. diff --git a/doc/user/actions.in b/doc/user/actions.in index 06dcd63..6634a0d 100644 --- a/doc/user/actions.in +++ b/doc/user/actions.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/actions.xml b/doc/user/actions.xml index 7231a70..a3cce98 100644 --- a/doc/user/actions.xml +++ b/doc/user/actions.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/add-method.in b/doc/user/add-method.in index a9595a9..815e0a7 100644 --- a/doc/user/add-method.in +++ b/doc/user/add-method.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 46f858d..6cb1a93 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -113,6 +113,7 @@ rc /fores.res res.rc cl /Fotest_stuff.obj /c test_stuff.c /nologo link /nologo /OUT:tests\test_stuff.exe test_stuff.obj res.res + embedManifestExeCheck(target, source, env) </screen> <para> diff --git a/doc/user/alias.in b/doc/user/alias.in index c17d76a..1fb7e30 100644 --- a/doc/user/alias.in +++ b/doc/user/alias.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/alias.xml b/doc/user/alias.xml index fed201f..8888f77 100644 --- a/doc/user/alias.xml +++ b/doc/user/alias.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/ant.in b/doc/user/ant.in index d39207d..2cc83a3 100644 --- a/doc/user/ant.in +++ b/doc/user/ant.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/ant.xml b/doc/user/ant.xml index d39207d..2cc83a3 100644 --- a/doc/user/ant.xml +++ b/doc/user/ant.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/build-install.in b/doc/user/build-install.in index 8d1c005..aad4a44 100644 --- a/doc/user/build-install.in +++ b/doc/user/build-install.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -121,9 +121,10 @@ <para> - &SCons; will work with any version of Python from 2.4 or later. + &SCons; will work with any 2.x version of Python from 2.4 on; + 3.0 and later are not yet supported. If you need to install Python and have a choice, - we recommend using the most recent Python version available. + we recommend using the most recent 2.x Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;. @@ -198,7 +199,7 @@ </para> <screen> - # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput> + # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput> </screen> <para> @@ -260,7 +261,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the <filename>scons-2.0.1.win32.exe</filename> + Download the <filename>scons-2.1.0.win32.exe</filename> file from the &SCons; download page at <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>. Then all you need to do is execute the file @@ -370,8 +371,8 @@ <para> The first step is to download either the - <filename>scons-2.0.1.tar.gz</filename> - or <filename>scons-2.0.1.zip</filename>, + <filename>scons-2.1.0.tar.gz</filename> + or <filename>scons-2.1.0.zip</filename>, which are available from the SCons download page at <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>. @@ -384,7 +385,7 @@ on Linux or UNIX, or <application>WinZip</application> on Windows. This will create a directory called - <filename>scons-2.0.1</filename>, + <filename>scons-2.1.0</filename>, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -392,7 +393,7 @@ </para> <screen> - # <userinput>cd scons-2.0.1</userinput> + # <userinput>cd scons-2.1.0</userinput> # <userinput>python setup.py install</userinput> </screen> @@ -460,9 +461,9 @@ This will install the &SCons; build engine in the - <filename>/usr/lib/scons-2.0.1</filename> + <filename>/usr/lib/scons-2.1.0</filename> or - <filename>C:\Python25\scons-2.0.1</filename> + <filename>C:\Python25\scons-2.1.0</filename> directory, for example. </para> @@ -519,7 +520,7 @@ relative to the specified prefix. Adding <option>--version-lib</option> to the above example would install the build engine in - <filename>/opt/scons/lib/scons-2.0.1</filename>. + <filename>/opt/scons/lib/scons-2.1.0</filename>. </para> diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index 8d1c005..aad4a44 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -121,9 +121,10 @@ <para> - &SCons; will work with any version of Python from 2.4 or later. + &SCons; will work with any 2.x version of Python from 2.4 on; + 3.0 and later are not yet supported. If you need to install Python and have a choice, - we recommend using the most recent Python version available. + we recommend using the most recent 2.x Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;. @@ -198,7 +199,7 @@ </para> <screen> - # <userinput>rpm -Uvh scons-2.0.1-1.noarch.rpm</userinput> + # <userinput>rpm -Uvh scons-2.1.0-1.noarch.rpm</userinput> </screen> <para> @@ -260,7 +261,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the <filename>scons-2.0.1.win32.exe</filename> + Download the <filename>scons-2.1.0.win32.exe</filename> file from the &SCons; download page at <ulink url="http://www.scons.org/download.php">http://www.scons.org/download.php</ulink>. Then all you need to do is execute the file @@ -370,8 +371,8 @@ <para> The first step is to download either the - <filename>scons-2.0.1.tar.gz</filename> - or <filename>scons-2.0.1.zip</filename>, + <filename>scons-2.1.0.tar.gz</filename> + or <filename>scons-2.1.0.zip</filename>, which are available from the SCons download page at <ulink url="http://www.scons.org/download.html">http://www.scons.org/download.html</ulink>. @@ -384,7 +385,7 @@ on Linux or UNIX, or <application>WinZip</application> on Windows. This will create a directory called - <filename>scons-2.0.1</filename>, + <filename>scons-2.1.0</filename>, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -392,7 +393,7 @@ </para> <screen> - # <userinput>cd scons-2.0.1</userinput> + # <userinput>cd scons-2.1.0</userinput> # <userinput>python setup.py install</userinput> </screen> @@ -460,9 +461,9 @@ This will install the &SCons; build engine in the - <filename>/usr/lib/scons-2.0.1</filename> + <filename>/usr/lib/scons-2.1.0</filename> or - <filename>C:\Python25\scons-2.0.1</filename> + <filename>C:\Python25\scons-2.1.0</filename> directory, for example. </para> @@ -519,7 +520,7 @@ relative to the specified prefix. Adding <option>--version-lib</option> to the above example would install the build engine in - <filename>/opt/scons/lib/scons-2.0.1</filename>. + <filename>/opt/scons/lib/scons-2.1.0</filename>. </para> diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in index f7da806..d16e8c3 100644 --- a/doc/user/builders-built-in.in +++ b/doc/user/builders-built-in.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index 3d47f5c..39e0533 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -160,6 +160,7 @@ cl /Fogoodbye.obj /c goodbye.c /nologo cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe /LIBPATH:\usr\dir1 /LIBPATH:dir2 foo1.lib foo2.lib hello.obj goodbye.obj + embedManifestExeCheck(target, source, env) </screen> <para> diff --git a/doc/user/builders-commands.in b/doc/user/builders-commands.in index af3aec8..1082058 100644 --- a/doc/user/builders-commands.in +++ b/doc/user/builders-commands.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -72,7 +72,7 @@ <scons_example name="ex1"> <file name="SConstruct" printme="1"> env = Environment() - env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") + env.Command('foo.out', 'foo.in', "sed 's/x/y/' < $SOURCE > $TARGET") </file> <file name="foo.in"> foo.in diff --git a/doc/user/builders-commands.xml b/doc/user/builders-commands.xml index 7e48660..e3066c6 100644 --- a/doc/user/builders-commands.xml +++ b/doc/user/builders-commands.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index 0bf6971..addc837 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -823,7 +823,6 @@ This functionality could be invoked as in the following example: <file name="my_command" chmod="0755"> cat </file> - </file> </scons_example> @@ -842,7 +841,6 @@ This functionality could be invoked as in the following example: MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2') - </file> </sconstruct> <para> @@ -899,8 +897,8 @@ This functionality could be invoked as in the following example: <para> - The <filename>site_scons</filename> directory gives you a place to - put Python modules you can import into your &SConscript; files + The <filename>site_scons</filename> directories give you a place to + put Python modules and packages that you can import into your &SConscript; files (<filename>site_scons</filename>), add-on tools that can integrate into &SCons; (<filename>site_scons/site_tools</filename>), @@ -912,11 +910,21 @@ This functionality could be invoked as in the following example: <para> + Each system type (Windows, Mac, Linux, etc.) searches a canonical + set of directories for site_scons; see the man page for details. + The top-level SConstruct's site_scons dir is always searched last, + and its dir is placed first in the tool path so it overrides all + others. + + </para> + + <para> + If you get a tool from somewhere (the &SCons; wiki or a third party, - for instance) and you'd like to use it in your project, the + for instance) and you'd like to use it in your project, a <filename>site_scons</filename> dir is the simplest place to put it. Tools come in two flavors; either a Python function that operates on - an &Environment; or a Python file containing two functions, + an &Environment; or a Python module or package containing two functions, <function>exists()</function> and <function>generate()</function>. </para> @@ -931,7 +939,7 @@ This functionality could be invoked as in the following example: </para> <scons_example name="site1"> - <file name="site_scons/site_init.py" printme=1> + <file name="site_scons/site_init.py" printme="1"> def TOOL_ADD_HEADER(env): """A Tool to add a header from $HEADER to the source file""" add_header = Builder(action=['echo "$HEADER" > $TARGET', @@ -975,16 +983,23 @@ This functionality could be invoked as in the following example: --> <para> - Similarly, a more full-fledged tool with + A more full-fledged tool with <function>exists()</function> and <function>generate()</function> - methods can be installed in - <filename>site_scons/site_tools/toolname.py</filename>. Since - <filename>site_scons/site_tools</filename> is automatically added - to the head of the tool search path, any tool found there will be - available to all environments. Furthermore, a tool found there - will override a built-in tool of the same name, so if you need to - change the behavior of a built-in tool, site_scons gives you the - hook you need. + methods can be installed either as a module in the file + <filename>site_scons/site_tools/toolname.py</filename> or as a + package in the + directory <filename>site_scons/site_tools/toolname</filename>. In + the case of using a package, the <function>exists()</function> + and <function>generate()</function> are in the + file <filename>site_scons/site_tools/toolname/__init__.py</filename>. + (In all the above case <filename>toolname</filename> is replaced + by the name of the tool.) + Since <filename>site_scons/site_tools</filename> is automatically + added to the head of the tool search path, any tool found there + will be available to all environments. Furthermore, a tool found + there will override a built-in tool of the same name, so if you + need to change the behavior of a built-in + tool, <filename>site_scons</filename> gives you the hook you need. </para> <para> @@ -998,7 +1013,7 @@ This functionality could be invoked as in the following example: </para> <scons_example name="site2"> - <file name="site_scons/my_utils.py" printme=1> + <file name="site_scons/my_utils.py" printme="1"> from SCons.Script import * # for Execute and Mkdir def build_id(): """Return a build ID (stub version)""" @@ -1047,13 +1062,15 @@ This functionality could be invoked as in the following example: <para> - If you have a machine-wide site dir you'd like to use instead of - <filename>./site_scons</filename>, use the - <literal>--site-dir</literal> option to point to your dir. + You can use any of the user- or machine-wide site dirs such as + <filename>~/.scons/site_scons</filename> instead of + <filename>./site_scons</filename>, or use the + <literal>--site-dir</literal> option to point to your own dir. <filename>site_init.py</filename> and <filename>site_tools</filename> will be located under that dir. - To avoid using a <filename>site_scons</filename> dir at all, even - if it exists, use the <literal>--no-site-dir</literal> option. + To avoid using a <filename>site_scons</filename> dir at all, + even if it exists, use the <literal>--no-site-dir</literal> + option. </para> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index f364e27..d9bda79 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -703,7 +703,6 @@ This functionality could be invoked as in the following example: import os env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - </programlisting> @@ -722,7 +721,6 @@ This functionality could be invoked as in the following example: MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2') - </programlisting> <para> @@ -781,8 +779,8 @@ This functionality could be invoked as in the following example: <para> - The <filename>site_scons</filename> directory gives you a place to - put Python modules you can import into your &SConscript; files + The <filename>site_scons</filename> directories give you a place to + put Python modules and packages that you can import into your &SConscript; files (<filename>site_scons</filename>), add-on tools that can integrate into &SCons; (<filename>site_scons/site_tools</filename>), @@ -794,11 +792,21 @@ This functionality could be invoked as in the following example: <para> + Each system type (Windows, Mac, Linux, etc.) searches a canonical + set of directories for site_scons; see the man page for details. + The top-level SConstruct's site_scons dir is always searched last, + and its dir is placed first in the tool path so it overrides all + others. + + </para> + + <para> + If you get a tool from somewhere (the &SCons; wiki or a third party, - for instance) and you'd like to use it in your project, the + for instance) and you'd like to use it in your project, a <filename>site_scons</filename> dir is the simplest place to put it. Tools come in two flavors; either a Python function that operates on - an &Environment; or a Python file containing two functions, + an &Environment; or a Python module or package containing two functions, <function>exists()</function> and <function>generate()</function>. </para> @@ -848,16 +856,23 @@ This functionality could be invoked as in the following example: --> <para> - Similarly, a more full-fledged tool with + A more full-fledged tool with <function>exists()</function> and <function>generate()</function> - methods can be installed in - <filename>site_scons/site_tools/toolname.py</filename>. Since - <filename>site_scons/site_tools</filename> is automatically added - to the head of the tool search path, any tool found there will be - available to all environments. Furthermore, a tool found there - will override a built-in tool of the same name, so if you need to - change the behavior of a built-in tool, site_scons gives you the - hook you need. + methods can be installed either as a module in the file + <filename>site_scons/site_tools/toolname.py</filename> or as a + package in the + directory <filename>site_scons/site_tools/toolname</filename>. In + the case of using a package, the <function>exists()</function> + and <function>generate()</function> are in the + file <filename>site_scons/site_tools/toolname/__init__.py</filename>. + (In all the above case <filename>toolname</filename> is replaced + by the name of the tool.) + Since <filename>site_scons/site_tools</filename> is automatically + added to the head of the tool search path, any tool found there + will be available to all environments. Furthermore, a tool found + there will override a built-in tool of the same name, so if you + need to change the behavior of a built-in + tool, <filename>site_scons</filename> gives you the hook you need. </para> <para> @@ -913,13 +928,15 @@ This functionality could be invoked as in the following example: <para> - If you have a machine-wide site dir you'd like to use instead of - <filename>./site_scons</filename>, use the - <literal>--site-dir</literal> option to point to your dir. + You can use any of the user- or machine-wide site dirs such as + <filename>~/.scons/site_scons</filename> instead of + <filename>./site_scons</filename>, or use the + <literal>--site-dir</literal> option to point to your own dir. <filename>site_init.py</filename> and <filename>site_tools</filename> will be located under that dir. - To avoid using a <filename>site_scons</filename> dir at all, even - if it exists, use the <literal>--no-site-dir</literal> option. + To avoid using a <filename>site_scons</filename> dir at all, + even if it exists, use the <literal>--no-site-dir</literal> + option. </para> diff --git a/doc/user/builders.in b/doc/user/builders.in index 9e9b647..f2bf36d 100644 --- a/doc/user/builders.in +++ b/doc/user/builders.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/builders.xml b/doc/user/builders.xml index 9e9b647..f2bf36d 100644 --- a/doc/user/builders.xml +++ b/doc/user/builders.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/caching.in b/doc/user/caching.in index e5e2742..d60f067 100644 --- a/doc/user/caching.in +++ b/doc/user/caching.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/caching.xml b/doc/user/caching.xml index 5a64e7d..c3dae0a 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/command-line.in b/doc/user/command-line.in index cd5ead6..52a61ac 100644 --- a/doc/user/command-line.in +++ b/doc/user/command-line.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -221,7 +221,7 @@ </para> - <sconstruct) + <sconstruct> if not GetOption('help'): SConscript('src/SConscript', export='env') </sconstruct> @@ -2195,7 +2195,7 @@ Second, the contents of the &DEFAULT_TARGETS; list change - in response to calls to the &Default: function, + in response to calls to the &Default; function, as you can see from the following &SConstruct; file: </para> diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 8bc72bb..f06442e 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -214,7 +214,10 @@ </para> - <programlisting></programlisting> + <programlisting> + if not GetOption('help'): + SConscript('src/SConscript', export='env') + </programlisting> <para> @@ -1252,7 +1255,7 @@ <screen> % <userinput>scons -Q COLOR=magenta foo.o</userinput> - scons: *** Invalid value for option COLOR: magenta + scons: *** Invalid value for option COLOR: magenta. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 5, in <module> </screen> @@ -1308,15 +1311,15 @@ <screen> % <userinput>scons -Q COLOR=Red foo.o</userinput> - scons: *** Invalid value for option COLOR: Red + scons: *** Invalid value for option COLOR: Red. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 5, in <module> % <userinput>scons -Q COLOR=BLUE foo.o</userinput> - scons: *** Invalid value for option COLOR: BLUE + scons: *** Invalid value for option COLOR: BLUE. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 5, in <module> % <userinput>scons -Q COLOR=nAvY foo.o</userinput> - scons: *** Invalid value for option COLOR: nAvY + scons: *** Invalid value for option COLOR: nAvY. Valid values are: ('red', 'green', 'blue') File "/home/my/project/SConstruct", line 5, in <module> </screen> @@ -2107,7 +2110,7 @@ Second, the contents of the &DEFAULT_TARGETS; list change - in response to calls to the &Default;: function, + in response to calls to the &Default; function, as you can see from the following &SConstruct; file: </para> diff --git a/doc/user/copyright.in b/doc/user/copyright.in index 8b90dbc..19689fe 100644 --- a/doc/user/copyright.in +++ b/doc/user/copyright.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/copyright.xml b/doc/user/copyright.xml index 8b90dbc..19689fe 100644 --- a/doc/user/copyright.xml +++ b/doc/user/copyright.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/depends.in b/doc/user/depends.in index 69bb242..190670c 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -386,7 +386,7 @@ <para> - So configured, &SCons will still behave like + So configured, &SCons; will still behave like it does when using <literal>Decider('MD5')</literal>: </para> @@ -487,7 +487,7 @@ only its section of the input file. However, since the input file may contain a lot of data, we want to open the input file only if its timestamp has changed. - This could done with a custom + This could be done with a custom &Decider; function that might look something like this: </para> @@ -591,6 +591,59 @@ </para> + <para> + + Another thing to look out for, is the fact that the three + attributes above may not be present at the time of the first run. + Without any prior build, no targets got created and no + <filename>.sconsign</filename> DB file exists yet. + So, it is recommended to always check whether the + <varname>prev_ni</varname> attribute in question is available. + + </para> + + <para> + + We finally present a small example for a + <varname>csig</varname>-based decider function. Note how the + signature information for the <varname>dependency</varname> file + has to get initialized via <function>get_csig</function> + during each function call (this is mandatory!). + + </para> + + <sconstruct> + env = Environment() + + def config_file_decider(dependency, target, prev_ni): + import os.path + + # We always have to init the .csig value... + dep_csig = dependency.get_csig() + # .csig may not exist, because no target was built yet... + if 'csig' not in dir(prev_ni): + return True + # Target file may not exist yet + if not os.path.exists(str(target.abspath)): + return True + if dep_csig != prev_ni.csig: + # Some change on source file => update installed one + return True + return False + + def update_file(): + f = open("test.txt","a") + f.write("some line\n") + f.close() + + update_file() + + # Activate our own decider function + env.Decider(config_file_decider) + + env.Install("install","test.txt") + </sconstruct> + </section> <section> @@ -861,7 +914,7 @@ </section> - <section> + <section id="sect-implicit-dependencies"> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 430e64a..5b19220 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -488,7 +488,7 @@ only its section of the input file. However, since the input file may contain a lot of data, we want to open the input file only if its timestamp has changed. - This could done with a custom + This could be done with a custom &Decider; function that might look something like this: </para> @@ -587,6 +587,59 @@ </para> + <para> + + Another thing to look out for, is the fact that the three + attributes above may not be present at the time of the first run. + Without any prior build, no targets got created and no + <filename>.sconsign</filename> DB file exists yet. + So, it is recommended to always check whether the + <varname>prev_ni</varname> attribute in question is available. + + </para> + + <para> + + We finally present a small example for a + <varname>csig</varname>-based decider function. Note how the + signature information for the <varname>dependency</varname> file + has to get initialized via <function>get_csig</function> + during each function call (this is mandatory!). + + </para> + + <programlisting> + env = Environment() + + def config_file_decider(dependency, target, prev_ni): + import os.path + + # We always have to init the .csig value... + dep_csig = dependency.get_csig() + # .csig may not exist, because no target was built yet... + if 'csig' not in dir(prev_ni): + return True + # Target file may not exist yet + if not os.path.exists(str(target.abspath)): + return True + if dep_csig != prev_ni.csig: + # Some change on source file => update installed one + return True + return False + + def update_file(): + f = open("test.txt","a") + f.write("some line\n") + f.close() + + update_file() + + # Activate our own decider function + env.Decider(config_file_decider) + + env.Install("install","test.txt") + </programlisting> + </section> <section> @@ -850,7 +903,7 @@ </section> - <section> + <section id="sect-implicit-dependencies"> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> <para> @@ -989,6 +1042,7 @@ C:\><userinput>scons -Q hello.exe</userinput> cl /Fohello.obj /c hello.c /nologo /Iinclude /I\home\project\inc link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) </screen> </section> diff --git a/doc/user/environments.in b/doc/user/environments.in index 9ce5568..ecfea8a 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -347,7 +347,7 @@ environment, of directory names, suffixes, etc. The <literal>external environment</literal> is the set of variables in the user's environment - at the time the user runs &SCons. + at the time the user runs &SCons;. These variables are available within the &SConscript; files through the Python <literal>os.environ</literal> dictionary. See <xref linkend="sect-external-environments"></xref>, below. @@ -406,7 +406,7 @@ environment, of directory names, suffixes, etc. Unlike &Make;, &SCons; does not automatically copy or import values between different environments - (with the exception of explicit clones of &consenvs, + (with the exception of explicit clones of &consenvs;, which inherit values from their parent). This is a deliberate design choice to make sure that builds are, @@ -638,7 +638,7 @@ environment, of directory names, suffixes, etc. for key in ['OBJSUFFIX', 'LIBSUFFIX', 'PROGSUFFIX']: print "key = %s, value = %s" % (key, dict[key]) </file> - </scons_Example> + </scons_example> <para> @@ -779,18 +779,20 @@ environment, of directory names, suffixes, etc. If a problem occurs when expanding a construction variable, by default it is expanded to <literal>''</literal> (a null string), and will not cause scons to fail. - + </para> + <scons_example name="missing1"> <file name="SConstruct" printme="1"> env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) + print "value is:", env.subst( '->$MISSING<-' ) </file> </scons_example> <scons_output example="missing1"> <scons_output_command>scons -Q</scons_output_command> </scons_output> - + + <para> This default behaviour can be changed using the &AllowSubstExceptions; function. When a problem occurs with a variable expansion it generates @@ -810,7 +812,7 @@ environment, of directory names, suffixes, etc. <file name="SConstruct" printme="1"> AllowSubstExceptions() env = Environment() - print "value is:", env.subst( '->$MISSING<-' ) + print "value is:", env.subst( '->$MISSING<-' ) </file> </scons_example> @@ -830,7 +832,7 @@ environment, of directory names, suffixes, etc. <file name="SConstruct" printme="1"> AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) env = Environment() - print "value is:", env.subst( '->${1 / 0}<-' ) + print "value is:", env.subst( '->${1 / 0}<-' ) </file> </scons_example> @@ -1093,7 +1095,7 @@ environment, of directory names, suffixes, etc. </section> - <section> + <section id="sect-clone-environments"> <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> <para> diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 5bb1089..81f43a4 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -779,7 +779,8 @@ environment, of directory names, suffixes, etc. If a problem occurs when expanding a construction variable, by default it is expanded to <literal>''</literal> (a null string), and will not cause scons to fail. - + </para> + <programlisting> env = Environment() print "value is:", env.subst( '->$MISSING<-' ) @@ -790,7 +791,8 @@ environment, of directory names, suffixes, etc. value is: -><- scons: `.' is up to date. </screen> - + + <para> This default behaviour can be changed using the &AllowSubstExceptions; function. When a problem occurs with a variable expansion it generates @@ -1087,7 +1089,7 @@ environment, of directory names, suffixes, etc. </section> - <section> + <section id="sect-clone-environments"> <title>Making Copies of &ConsEnvs;: the &Clone; Method</title> <para> diff --git a/doc/user/errors.in b/doc/user/errors.in index ad4c2ef..7e33118 100644 --- a/doc/user/errors.in +++ b/doc/user/errors.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/errors.xml b/doc/user/errors.xml index ad4c2ef..7e33118 100644 --- a/doc/user/errors.xml +++ b/doc/user/errors.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/example.in b/doc/user/example.in index ad4c2ef..7e33118 100644 --- a/doc/user/example.in +++ b/doc/user/example.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/example.xml b/doc/user/example.xml index ad4c2ef..7e33118 100644 --- a/doc/user/example.xml +++ b/doc/user/example.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/factories.in b/doc/user/factories.in index c0f524d..da92082 100644 --- a/doc/user/factories.in +++ b/doc/user/factories.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -209,7 +209,7 @@ <para> Of course, like all of these &Action; factories, - the &Delete factory also expands + the &Delete; factory also expands &cv-link-TARGET; and &cv-link-SOURCE; variables appropriately. For example: diff --git a/doc/user/factories.xml b/doc/user/factories.xml index 6a92b0c..7f51c8d 100644 --- a/doc/user/factories.xml +++ b/doc/user/factories.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/file-removal.in b/doc/user/file-removal.in index 1b12d35..b664ba0 100644 --- a/doc/user/file-removal.in +++ b/doc/user/file-removal.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/file-removal.xml b/doc/user/file-removal.xml index 92c1c0d..47b081a 100644 --- a/doc/user/file-removal.xml +++ b/doc/user/file-removal.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/functions.in b/doc/user/functions.in new file mode 100644 index 0000000..7c96c54 --- /dev/null +++ b/doc/user/functions.in @@ -0,0 +1,38 @@ +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +function and construction environment methods +in this version of &SCons; + +</para> + +<variablelist> + +&functions-gen; + +</variablelist> diff --git a/doc/user/functions.xml b/doc/user/functions.xml new file mode 100644 index 0000000..7c96c54 --- /dev/null +++ b/doc/user/functions.xml @@ -0,0 +1,38 @@ +<!-- + + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + +<para> + +This appendix contains descriptions of all of the +function and construction environment methods +in this version of &SCons; + +</para> + +<variablelist> + +&functions-gen; + +</variablelist> diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 16d9389..950bc8a 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -478,7 +478,7 @@ make no difference to the build. </section> - <section> + <section id="sect-sharing-environments"> <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> <para> @@ -688,7 +688,7 @@ make no difference to the build. Sometimes, you would like to be able to use information from a subsidiary - &SConscript file in some way. + &SConscript; file in some way. For example, suppose that you want to create one library from source files diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index bc4073e..6691e70 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -442,7 +442,7 @@ make no difference to the build. </section> - <section> + <section id="sect-sharing-environments"> <title>Sharing Environments (and Other Variables) Between &SConscript; Files</title> <para> diff --git a/doc/user/install.in b/doc/user/install.in index 8f9498e..131fc6a 100644 --- a/doc/user/install.in +++ b/doc/user/install.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/install.xml b/doc/user/install.xml index f119b00..6b49ae8 100644 --- a/doc/user/install.xml +++ b/doc/user/install.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/java.in b/doc/user/java.in index 290cd43..bad5c34 100644 --- a/doc/user/java.in +++ b/doc/user/java.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -390,7 +390,7 @@ You can generate C header and source files for implementing native methods, by using the &b-link-JavaH; Builder. - There are several ways of using the &JavaH Builder. + There are several ways of using the &JavaH; Builder. One typical invocation might look like: </para> @@ -636,7 +636,7 @@ As it did with the &b-link-JavaH; Builder, &SCons; remembers the class directory and passes it as the <option>-classpath</option> option - to &rmic: + to &rmic;: </para> diff --git a/doc/user/java.xml b/doc/user/java.xml index a0544f7..f277558 100644 --- a/doc/user/java.xml +++ b/doc/user/java.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in index cccad83..d717014 100644 --- a/doc/user/less-simple.in +++ b/doc/user/less-simple.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index 24b45e6..e269490 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -102,6 +102,7 @@ C:\><userinput>scons -Q</userinput> cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:new_hello.exe hello.obj + embedManifestExeCheck(target, source, env) </screen> </section> @@ -193,6 +194,7 @@ cl /Fofile2.obj /c file2.c /nologo cl /Foprog.obj /c prog.c /nologo link /nologo /OUT:program.exe prog.obj file1.obj file2.obj + embedManifestExeCheck(target, source, env) </screen> </section> diff --git a/doc/user/libraries.in b/doc/user/libraries.in index 5b449e7..a56f2c3 100644 --- a/doc/user/libraries.in +++ b/doc/user/libraries.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/libraries.xml b/doc/user/libraries.xml index 3eed3cc..6909758 100644 --- a/doc/user/libraries.xml +++ b/doc/user/libraries.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -206,6 +206,7 @@ cl /Fof3.obj /c f3.c /nologo link /nologo /dll /out:foo.dll /implib:foo.lib f1.obj f2.obj f3.obj RegServerFunc(target, source, env) + embedManifestDllCheck(target, source, env) </screen> <para> @@ -288,6 +289,7 @@ lib /nologo /OUT:foo.lib f1.obj f2.obj f3.obj cl /Foprog.obj /c prog.c /nologo link /nologo /OUT:prog.exe /LIBPATH:. foo.lib bar.lib prog.obj + embedManifestExeCheck(target, source, env) </screen> <para> @@ -412,6 +414,7 @@ C:\><userinput>scons -Q</userinput> cl /Foprog.obj /c prog.c /nologo link /nologo /OUT:prog.exe /LIBPATH:\usr\lib /LIBPATH:\usr\local\lib m.lib prog.obj + embedManifestExeCheck(target, source, env) </screen> <!-- The link command is too wide in the PDF version. There are some other examples of this throughout the document. --> diff --git a/doc/user/main.in b/doc/user/main.in index fbc28df..feb8c25 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -37,6 +37,9 @@ <!ENTITY % builders-mod SYSTEM "builders.mod"> %builders-mod; + <!ENTITY % functions-mod SYSTEM "functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "tools.mod"> %tools-mod; @@ -61,6 +64,7 @@ <!ENTITY example SYSTEM "example.xml"> <!ENTITY factories SYSTEM "factories.xml"> <!ENTITY file-removal SYSTEM "file-removal.xml"> + <!ENTITY functions SYSTEM "functions.xml"> <!ENTITY hierarchy SYSTEM "hierarchy.xml"> <!ENTITY java SYSTEM "java.xml"> <!ENTITY install SYSTEM "install.xml"> @@ -89,6 +93,7 @@ <!ENTITY variants SYSTEM "variants.xml"> <!ENTITY builders-gen SYSTEM "builders.gen"> + <!ENTITY functions-gen SYSTEM "functions.gen"> <!ENTITY tools-gen SYSTEM "tools.gen"> <!ENTITY variables-gen SYSTEM "variables.gen"> @@ -177,18 +182,35 @@ &environments; </chapter> - <!-- These next three sections should be combined into one chapter --> - <chapter id="chap-mergeflags"> - <title>Merging Options into the Environment: the &MergeFlags; Function</title> - &mergeflags; - </chapter> - <chapter id="chap-parseflags"> - <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> - &parseflags; - </chapter> - <chapter id="chap-parseconfig"> - <title>Finding Installed Library Information: the &ParseConfig; Function</title> - &parseconfig; + <chapter id="chap-manip-options"> + <title>Automatically Putting Command-line Options into their Construction Variables</title> + <!-- TODO: This intro paragraph should describe at a high-level + what these things do. People are likely to use the intro as a + (brief) overview of *what* these functions do to decide if this + chapter is where they should read in more detail. --> + <para> + This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. + </para> + <section id="sect-mergeflags"> + <title>Merging Options into the Environment: the &MergeFlags; Function</title> + &mergeflags; + </section> + <section id="sect-parseflags"> + <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> + &parseflags; + </section> + <section id="sect-parseconfig"> + <title>Finding Installed Library Information: the &ParseConfig; Function</title> + &parseconfig; + </section> + <!-- + XXX parse_flags= option of Environment() + + <section id="sect-env-parseflags"> + <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title> + &envparseflags; + </section> + --> </chapter> <chapter id="chap-output"> @@ -341,6 +363,11 @@ &tools; </appendix> + <appendix id="app-functions"> + <title>Functions and Environment Methods</title> + &functions; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; diff --git a/doc/user/main.xml b/doc/user/main.xml index fbc28df..feb8c25 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -1,7 +1,7 @@ <?xml version="1.0"?> <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -37,6 +37,9 @@ <!ENTITY % builders-mod SYSTEM "builders.mod"> %builders-mod; + <!ENTITY % functions-mod SYSTEM "functions.mod"> + %functions-mod; + <!ENTITY % tools-mod SYSTEM "tools.mod"> %tools-mod; @@ -61,6 +64,7 @@ <!ENTITY example SYSTEM "example.xml"> <!ENTITY factories SYSTEM "factories.xml"> <!ENTITY file-removal SYSTEM "file-removal.xml"> + <!ENTITY functions SYSTEM "functions.xml"> <!ENTITY hierarchy SYSTEM "hierarchy.xml"> <!ENTITY java SYSTEM "java.xml"> <!ENTITY install SYSTEM "install.xml"> @@ -89,6 +93,7 @@ <!ENTITY variants SYSTEM "variants.xml"> <!ENTITY builders-gen SYSTEM "builders.gen"> + <!ENTITY functions-gen SYSTEM "functions.gen"> <!ENTITY tools-gen SYSTEM "tools.gen"> <!ENTITY variables-gen SYSTEM "variables.gen"> @@ -177,18 +182,35 @@ &environments; </chapter> - <!-- These next three sections should be combined into one chapter --> - <chapter id="chap-mergeflags"> - <title>Merging Options into the Environment: the &MergeFlags; Function</title> - &mergeflags; - </chapter> - <chapter id="chap-parseflags"> - <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> - &parseflags; - </chapter> - <chapter id="chap-parseconfig"> - <title>Finding Installed Library Information: the &ParseConfig; Function</title> - &parseconfig; + <chapter id="chap-manip-options"> + <title>Automatically Putting Command-line Options into their Construction Variables</title> + <!-- TODO: This intro paragraph should describe at a high-level + what these things do. People are likely to use the intro as a + (brief) overview of *what* these functions do to decide if this + chapter is where they should read in more detail. --> + <para> + This chapter describes the &MergeFlags;, &ParseFlags;, and &ParseConfig; methods of a &consenv;. + </para> + <section id="sect-mergeflags"> + <title>Merging Options into the Environment: the &MergeFlags; Function</title> + &mergeflags; + </section> + <section id="sect-parseflags"> + <title>Separating Compile Arguments into their Variables: the &ParseFlags; Function</title> + &parseflags; + </section> + <section id="sect-parseconfig"> + <title>Finding Installed Library Information: the &ParseConfig; Function</title> + &parseconfig; + </section> + <!-- + XXX parse_flags= option of Environment() + + <section id="sect-env-parseflags"> + <title>Adding Flags when Constructing Enviroment: the parse_flags Optional Argument</title> + &envparseflags; + </section> + --> </chapter> <chapter id="chap-output"> @@ -341,6 +363,11 @@ &tools; </appendix> + <appendix id="app-functions"> + <title>Functions and Environment Methods</title> + &functions; + </appendix> + <appendix id="app-tasks"> <title>Handling Common Tasks</title> &tasks; diff --git a/doc/user/make.in b/doc/user/make.in index c17b047..7102557 100644 --- a/doc/user/make.in +++ b/doc/user/make.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/make.xml b/doc/user/make.xml index c17b047..7102557 100644 --- a/doc/user/make.xml +++ b/doc/user/make.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/mergeflags.in b/doc/user/mergeflags.in index 58d437c..086d042 100644 --- a/doc/user/mergeflags.in +++ b/doc/user/mergeflags.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/mergeflags.xml b/doc/user/mergeflags.xml index ab10e54..f0bc2b6 100644 --- a/doc/user/mergeflags.xml +++ b/doc/user/mergeflags.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/misc.in b/doc/user/misc.in index 87b5db4..fef1b8f 100644 --- a/doc/user/misc.in +++ b/doc/user/misc.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -36,7 +36,7 @@ <para> Although the &SCons; code itself will run - on any Python version 2.4 or later, + on any 2.x Python version 2.4 or later, you are perfectly free to make use of Python syntax and modules from more modern versions (for example, Python 2.5 or 2.6) @@ -82,7 +82,7 @@ <para> - And then &SCons will exit with the following error + And then &SCons; will exit with the following error message when a user runs it with an unsupported earlier version of Python: @@ -151,7 +151,7 @@ <para> - And then &SCons will exit with the following error + And then &SCons; will exit with the following error message when a user runs it with an unsupported earlier version of &SCons;: @@ -274,13 +274,13 @@ </file> <directory name="src"></directory> <directory name="src/include"></directory> - </file> <file name="src/include/private.h"> exists - <directory name="include"></directory> </file> + <directory name="include"></directory> <file name="include/dist.h"> exists + </file> </scons_example> <scons_output example="FindFile1b" os="posix"> diff --git a/doc/user/misc.xml b/doc/user/misc.xml index f79f1cc..069f94b 100644 --- a/doc/user/misc.xml +++ b/doc/user/misc.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -36,7 +36,7 @@ <para> Although the &SCons; code itself will run - on any Python version 2.4 or later, + on any 2.x Python version 2.4 or later, you are perfectly free to make use of Python syntax and modules from more modern versions (for example, Python 2.5 or 2.6) @@ -263,7 +263,7 @@ headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] for hdr in headers: print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) -</programlisting> + </programlisting> <screen> % <userinput>scons -Q</userinput> diff --git a/doc/user/nodes.in b/doc/user/nodes.in index c65a2ad..7799d3f 100644 --- a/doc/user/nodes.in +++ b/doc/user/nodes.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/nodes.xml b/doc/user/nodes.xml index 71ac7c1..fe8e167 100644 --- a/doc/user/nodes.xml +++ b/doc/user/nodes.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -131,6 +131,7 @@ cl /Fogoodbye.obj /c goodbye.c -DGOODBYE cl /Fohello.obj /c hello.c -DHELLO link /nologo /OUT:hello.exe hello.obj goodbye.obj + embedManifestExeCheck(target, source, env) </screen> <para> @@ -275,6 +276,7 @@ The program file is: hello.exe cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) </screen> <para> diff --git a/doc/user/output.in b/doc/user/output.in index e456026..d2823d0 100644 --- a/doc/user/output.in +++ b/doc/user/output.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -490,7 +490,7 @@ over how to print each evaluated node by passing a Python function (or other Python callable) - to the &Progress function. + to the &Progress; function. Your function will be called for each evaluated node, allowing you to diff --git a/doc/user/output.xml b/doc/user/output.xml index 297e6f8..6910b59 100644 --- a/doc/user/output.xml +++ b/doc/user/output.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseconfig.in b/doc/user/parseconfig.in index 667601f..5eb990c 100644 --- a/doc/user/parseconfig.in +++ b/doc/user/parseconfig.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseconfig.xml b/doc/user/parseconfig.xml index 534ea3d..409abfe 100644 --- a/doc/user/parseconfig.xml +++ b/doc/user/parseconfig.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseflags.in b/doc/user/parseflags.in index 2f4bea5..6e72c18 100644 --- a/doc/user/parseflags.in +++ b/doc/user/parseflags.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index fd15de7..7350831 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -91,6 +91,7 @@ LIBS ['foo'] cl /Fof1.obj /c f1.c /nologo /I\opt\include link /nologo /OUT:f1.exe /LIBPATH:\opt\lib foo.lib f1.obj + embedManifestExeCheck(target, source, env) </screen> <para> diff --git a/doc/user/preface.in b/doc/user/preface.in index a60beab..e82ee3b 100644 --- a/doc/user/preface.in +++ b/doc/user/preface.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -104,7 +104,7 @@ <para> There are a few overriding principles - we try to live up to in designing and implementing &SCons: + we try to live up to in designing and implementing &SCons;: </para> @@ -418,7 +418,7 @@ <para> - If you want to receive announcements about &SCons, + If you want to receive announcements about &SCons;, join the low-volume &scons-announce; mailing list. </para> diff --git a/doc/user/preface.xml b/doc/user/preface.xml index db2031d..e82ee3b 100644 --- a/doc/user/preface.xml +++ b/doc/user/preface.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/python.in b/doc/user/python.in index 18679e4..c3ea5fe 100644 --- a/doc/user/python.in +++ b/doc/user/python.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/python.xml b/doc/user/python.xml index 18679e4..c3ea5fe 100644 --- a/doc/user/python.xml +++ b/doc/user/python.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/repositories.in b/doc/user/repositories.in index 531aa8a..5ba9090 100644 --- a/doc/user/repositories.in +++ b/doc/user/repositories.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -210,9 +210,9 @@ in the repository trees, though, it will be unable to find the <literal>#include</literal> files. If, for example, the &hello_c; file in - our previous example includes the &hello.h; + our previous example includes the &hello_h; in its current directory, - and the &hello.h; only exists in the repository: + and the &hello_h; only exists in the repository: </para> diff --git a/doc/user/repositories.xml b/doc/user/repositories.xml index 6400b23..219dbaf 100644 --- a/doc/user/repositories.xml +++ b/doc/user/repositories.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -193,9 +193,9 @@ in the repository trees, though, it will be unable to find the <literal>#include</literal> files. If, for example, the &hello_c; file in - our previous example includes the &hello;.h; + our previous example includes the &hello_h; in its current directory, - and the &hello;.h; only exists in the repository: + and the &hello_h; only exists in the repository: </para> diff --git a/doc/user/run.in b/doc/user/run.in index 761f37c..8d47b27 100644 --- a/doc/user/run.in +++ b/doc/user/run.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/run.xml b/doc/user/run.xml index 761f37c..8d47b27 100644 --- a/doc/user/run.xml +++ b/doc/user/run.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/scanners.in b/doc/user/scanners.in index db3170a..e8bdff7 100644 --- a/doc/user/scanners.in +++ b/doc/user/scanners.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -171,10 +171,21 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path, arg): contents = node.get_text_contents() - return include_re.findall(contents) + return env.File(include_re.findall(contents)) </programlisting> <para> + + It is important to note that you + have to return a list of File nodes from the scanner function, simple + strings for the file names won't do. As in the examples we are showing here, + you can use the &File; + function of your current Environment in order to create nodes on the fly from + a sequence of file names with relative paths. + + </para> + + <para> The scanner function must accept the four specified arguments @@ -283,7 +294,7 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path): contents = node.get_text_contents() includes = include_re.findall(contents) - return includes + return env.File(includes) kscan = Scanner(function = kfile_scan, skeys = ['.k']) diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 2aba7d2..7862265 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -171,10 +171,21 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path, arg): contents = node.get_text_contents() - return include_re.findall(contents) + return env.File(include_re.findall(contents)) </programlisting> <para> + + It is important to note that you + have to return a list of File nodes from the scanner function, simple + strings for the file names won't do. As in the examples we are showing here, + you can use the &File; + function of your current Environment in order to create nodes on the fly from + a sequence of file names with relative paths. + + </para> + + <para> The scanner function must accept the four specified arguments @@ -282,7 +293,7 @@ over the file scanning rather than being called for each input line: def kfile_scan(node, env, path): contents = node.get_text_contents() includes = include_re.findall(contents) - return includes + return env.File(includes) kscan = Scanner(function = kfile_scan, skeys = ['.k']) diff --git a/doc/user/sconf.in b/doc/user/sconf.in index 94a455e..52fe132 100644 --- a/doc/user/sconf.in +++ b/doc/user/sconf.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -31,7 +31,7 @@ figuring out what libraries or header files are available on the local system. This section describes how to use - this &SCons feature. + this &SCons; feature. </para> @@ -446,7 +446,7 @@ when removing targets doesn't hurt anything, it's usually unnecessary. You can avoid this by using the - &GetOption(); method to + &GetOption; method to check whether the <option>-c</option> (clean) option has been invoked on the command line: diff --git a/doc/user/sconf.xml b/doc/user/sconf.xml index 35f4367..460c3d1 100644 --- a/doc/user/sconf.xml +++ b/doc/user/sconf.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -446,7 +446,7 @@ when removing targets doesn't hurt anything, it's usually unnecessary. You can avoid this by using the - &GetOption;(); method to + &GetOption; method to check whether the <option>-c</option> (clean) option has been invoked on the command line: diff --git a/doc/user/separate.in b/doc/user/separate.in index 8c08cbe..932c285 100644 --- a/doc/user/separate.in +++ b/doc/user/separate.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/separate.xml b/doc/user/separate.xml index 2c6f97b..7df53e9 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sideeffect.in b/doc/user/sideeffect.in index 3356d6c..852f99a 100644 --- a/doc/user/sideeffect.in +++ b/doc/user/sideeffect.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sideeffect.xml b/doc/user/sideeffect.xml index f6055f3..35e026f 100644 --- a/doc/user/sideeffect.xml +++ b/doc/user/sideeffect.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/simple.in b/doc/user/simple.in index b4802f8..0d15f12 100644 --- a/doc/user/simple.in +++ b/doc/user/simple.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -297,7 +297,7 @@ </section> - <section> + <section id="sect-sconstruct-file"> <title>The &SConstruct; File</title> <para> @@ -353,14 +353,14 @@ </section> - <section> + <section id="sect-order-independent"> <title>&SCons; Functions Are Order-Independent</title> <para> One important way in which the &SConstruct; file is not exactly like a normal Python script, - and is more like a &Makefile, + and is more like a &Makefile;, is that the order in which the &SCons; functions are called in the &SConstruct; file @@ -453,7 +453,7 @@ <para> Notice also that &SCons; built the &goodbye; program first, - even though the "reading &SConscript" output + even though the "reading &SConscript;" output shows that we called <literal>Program('hello.c')</literal> first in the &SConstruct; file. diff --git a/doc/user/simple.xml b/doc/user/simple.xml index 54f6b56..49b8805 100644 --- a/doc/user/simple.xml +++ b/doc/user/simple.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -110,6 +110,7 @@ scons: Building targets ... cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) scons: done building targets. </screen> @@ -300,6 +301,7 @@ scons: Building targets ... cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) scons: done building targets. C:\><userinput>scons -c</userinput> scons: Reading SConscript files ... @@ -320,7 +322,7 @@ </section> - <section> + <section id="sect-sconstruct-file"> <title>The &SConstruct; File</title> <para> @@ -376,7 +378,7 @@ </section> - <section> + <section id="sect-order-independent"> <title>&SCons; Functions Are Order-Independent</title> <para> @@ -507,6 +509,7 @@ scons: Building targets ... cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) scons: done building targets. </screen> @@ -536,6 +539,7 @@ C:\><userinput>scons -Q</userinput> cl /Fohello.obj /c hello.c /nologo link /nologo /OUT:hello.exe hello.obj + embedManifestExeCheck(target, source, env) </screen> <para> diff --git a/doc/user/sourcecode.in b/doc/user/sourcecode.in index 5a9637e..e4fc5be 100644 --- a/doc/user/sourcecode.in +++ b/doc/user/sourcecode.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/sourcecode.xml b/doc/user/sourcecode.xml index 73c2490..6642d0f 100644 --- a/doc/user/sourcecode.xml +++ b/doc/user/sourcecode.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tasks.in b/doc/user/tasks.in index 8842dcd..aa6a12e 100644 --- a/doc/user/tasks.in +++ b/doc/user/tasks.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -99,14 +99,14 @@ env.Append(CPPPATH = "#") ## Header example env.Append(BUILDERS = - {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET', + {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET', suffix='.h', src_suffix='.bar')}) env.Copy1('test.bar') # produces test.h from test.bar. env.Program('app','main.cpp') # indirectly depends on test.bar ## Source file example env.Append(BUILDERS = - {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET', + {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET', suffix='.cpp', src_suffix='.bar2')}) foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2. diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml index 2b2eb0b..ada4de5 100644 --- a/doc/user/tasks.xml +++ b/doc/user/tasks.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tools.in b/doc/user/tools.in index 16228e7..9dd71df 100644 --- a/doc/user/tools.in +++ b/doc/user/tools.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/tools.xml b/doc/user/tools.xml index 16228e7..9dd71df 100644 --- a/doc/user/tools.xml +++ b/doc/user/tools.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/troubleshoot.in b/doc/user/troubleshoot.in index 97df351..615d677 100644 --- a/doc/user/troubleshoot.in +++ b/doc/user/troubleshoot.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -34,7 +34,7 @@ &SCons; is no different. This appendix contains a number of different ways in which you can - get some additional insight into &SCons' behavior. + get some additional insight into &SCons;' behavior. </para> @@ -410,12 +410,12 @@ <para> - The <literaL>--tree</literal> option only prints + The <literal>--tree</literal> option only prints the dependency graph for the specified targets (or the default target(s) if none are specified on the command line). So if you specify a target like <filename>f2.o</filename> on the command line, - the <literaL>--tree</literal> option will only + the <literal>--tree</literal> option will only print the dependency graph for that file: </para> @@ -722,7 +722,7 @@ <para> - For example, the following &SConstruct file: + For example, the following &SConstruct; file: </para> @@ -842,8 +842,47 @@ </section> + <section> + + <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title> + + <para> + + Sometimes SCons doesn't build the target you want + and it's difficult to figure out why. You can use + the <literal>--debug=prepare</literal> option + to see all the targets &SCons; is considering, whether + they are already up-to-date or not. The message is + printed before &SCons; decides whether to build the target. + </para> + + </section> + + <section> + + <title>Why is a file disappearing? the --debug=duplicate Option</title> + + <para> + + When using the &Duplicate; option to create variant dirs, + sometimes you may find files not getting copied to where you + expect (or not at all), or files mysteriously disappearing. These + are usually because of a misconfiguration of some kind in the + SConstruct/SConscript, but they can be tricky to debug. The + --debug=duplicate option shows each time a variant file is + unlinked and relinked from its source (or copied, depending on + settings), and also shows a message for removing "stale" + variant-dir files that no longer have a corresponding source file. + It also prints a line for each target that's removed just before + building, since that can also be mistaken for the same thing. + + </para> + + </section> + <!-- + <section> <title>Where Are My Build Bottlenecks? the &profile; Option</title> diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 468af92..1f32a35 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -282,7 +282,8 @@ '.mm', '.S', '.spp', - '.SPP'], + '.SPP', + '.sx'], 'DSUFFIXES': ['.d'], 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, @@ -345,7 +346,7 @@ 'CC': 'cl', 'CCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'CCFLAGS': ['/nologo'], - 'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'], + 'CCPCHFLAGS': ['${(PCH and "/Yu%s \\"/Fp%s\\""%(PCHSTOP or "",File(PCH))) or ""}'], 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], 'CFILESUFFIX': '.c', 'CFLAGS': [], @@ -371,9 +372,10 @@ '.mm', '.S', '.spp', - '.SPP'], + '.SPP', + '.sx'], 'CXX': '$CC', - 'CXXCOM': '$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM', + 'CXXCOM': '${TEMPFILE("$CXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $CXXFLAGS $CCFLAGS $_CCCOMCOM")}', 'CXXFILESUFFIX': '.cc', 'CXXFLAGS': ['$(', '/TP', '$)'], 'DSUFFIXES': ['.d'], @@ -415,7 +417,7 @@ 'SHCCFLAGS': ['$CCFLAGS'], 'SHCFLAGS': ['$CFLAGS'], 'SHCXX': '$CXX', - 'SHCXXCOM': '$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM', + 'SHCXXCOM': '${TEMPFILE("$SHCXX $_MSVC_OUTPUT_FLAG /c $CHANGED_SOURCES $SHCXXFLAGS $SHCCFLAGS $_CCCOMCOM")}', 'SHCXXFLAGS': ['$CXXFLAGS'], 'SHELL': None, 'SHLIBPREFIX': '', @@ -1120,9 +1122,9 @@ 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 167, in 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 187, in prepare + 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])) @@ -1260,8 +1262,47 @@ </section> + <section> + + <title>Watch &SCons; prepare targets for building: the &debug-prepare; Option</title> + + <para> + + Sometimes SCons doesn't build the target you want + and it's difficult to figure out why. You can use + the <literal>--debug=prepare</literal> option + to see all the targets &SCons; is considering, whether + they are already up-to-date or not. The message is + printed before &SCons; decides whether to build the target. + </para> + + </section> + + <section> + + <title>Why is a file disappearing? the --debug=duplicate Option</title> + + <para> + + When using the &Duplicate; option to create variant dirs, + sometimes you may find files not getting copied to where you + expect (or not at all), or files mysteriously disappearing. These + are usually because of a misconfiguration of some kind in the + SConstruct/SConscript, but they can be tricky to debug. The + --debug=duplicate option shows each time a variant file is + unlinked and relinked from its source (or copied, depending on + settings), and also shows a message for removing "stale" + variant-dir files that no longer have a corresponding source file. + It also prints a line for each target that's removed just before + building, since that can also be mistaken for the same thing. + + </para> + + </section> + <!-- + <section> <title>Where Are My Build Bottlenecks? the &profile; Option</title> diff --git a/doc/user/variables.in b/doc/user/variables.in index bf8be1b..9b8afc1 100644 --- a/doc/user/variables.in +++ b/doc/user/variables.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variables.xml b/doc/user/variables.xml index bf8be1b..9b8afc1 100644 --- a/doc/user/variables.xml +++ b/doc/user/variables.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variants.in b/doc/user/variants.in index d94e3f3..5050306 100644 --- a/doc/user/variants.in +++ b/doc/user/variants.in @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/doc/user/variants.xml b/doc/user/variants.xml index bca84c8..e096eed 100644 --- a/doc/user/variants.xml +++ b/doc/user/variants.xml @@ -1,6 +1,6 @@ <!-- - Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation + Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the @@ -114,6 +114,7 @@ is pretty smart about rebuilding things when you change options. lib /nologo /OUT:build\windows\world\world.lib build\windows\world\world.obj Install file: "build/windows/world/world.lib" as "export/windows/lib/world.lib" link /nologo /OUT:build\windows\hello\hello.exe /LIBPATH:export\windows\lib world.lib build\windows\hello\hello.obj + embedManifestExeCheck(target, source, env) Install file: "build/windows/hello/hello.exe" as "export/windows/bin/hello.exe" </screen> |