summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/SConscript145
-rw-r--r--doc/design/scons.mod2
-rw-r--r--doc/developer/architecture.xml2
-rw-r--r--doc/developer/branches.xml2
-rw-r--r--doc/developer/copyright.xml2
-rw-r--r--doc/developer/cycle.xml2
-rw-r--r--doc/developer/main.xml2
-rw-r--r--doc/developer/packaging.xml2
-rw-r--r--doc/developer/preface.xml2
-rw-r--r--doc/developer/sourcetree.xml2
-rw-r--r--doc/developer/testing.xml2
-rw-r--r--doc/man/scons-time.16
-rw-r--r--doc/man/scons.14200
-rw-r--r--doc/man/sconsign.16
-rw-r--r--doc/python10/scons.mod2
-rw-r--r--doc/scons.mod4
-rw-r--r--doc/user/MANIFEST1
-rw-r--r--doc/user/README2
-rw-r--r--doc/user/actions.in2
-rw-r--r--doc/user/actions.xml2
-rw-r--r--doc/user/add-method.in2
-rw-r--r--doc/user/add-method.xml3
-rw-r--r--doc/user/alias.in2
-rw-r--r--doc/user/alias.xml2
-rw-r--r--doc/user/ant.in2
-rw-r--r--doc/user/ant.xml2
-rw-r--r--doc/user/build-install.in25
-rw-r--r--doc/user/build-install.xml25
-rw-r--r--doc/user/builders-built-in.in2
-rw-r--r--doc/user/builders-built-in.xml3
-rw-r--r--doc/user/builders-commands.in4
-rw-r--r--doc/user/builders-commands.xml2
-rw-r--r--doc/user/builders-writing.in63
-rw-r--r--doc/user/builders-writing.xml59
-rw-r--r--doc/user/builders.in2
-rw-r--r--doc/user/builders.xml2
-rw-r--r--doc/user/caching.in2
-rw-r--r--doc/user/caching.xml2
-rw-r--r--doc/user/command-line.in6
-rw-r--r--doc/user/command-line.xml17
-rw-r--r--doc/user/copyright.in2
-rw-r--r--doc/user/copyright.xml2
-rw-r--r--doc/user/depends.in61
-rw-r--r--doc/user/depends.xml60
-rw-r--r--doc/user/environments.in22
-rw-r--r--doc/user/environments.xml10
-rw-r--r--doc/user/errors.in2
-rw-r--r--doc/user/errors.xml2
-rw-r--r--doc/user/example.in2
-rw-r--r--doc/user/example.xml2
-rw-r--r--doc/user/factories.in4
-rw-r--r--doc/user/factories.xml2
-rw-r--r--doc/user/file-removal.in2
-rw-r--r--doc/user/file-removal.xml2
-rw-r--r--doc/user/functions.in38
-rw-r--r--doc/user/functions.xml38
-rw-r--r--doc/user/hierarchy.in6
-rw-r--r--doc/user/hierarchy.xml4
-rw-r--r--doc/user/install.in2
-rw-r--r--doc/user/install.xml2
-rw-r--r--doc/user/java.in6
-rw-r--r--doc/user/java.xml2
-rw-r--r--doc/user/less-simple.in2
-rw-r--r--doc/user/less-simple.xml4
-rw-r--r--doc/user/libraries.in2
-rw-r--r--doc/user/libraries.xml5
-rw-r--r--doc/user/main.in53
-rw-r--r--doc/user/main.xml53
-rw-r--r--doc/user/make.in2
-rw-r--r--doc/user/make.xml2
-rw-r--r--doc/user/mergeflags.in2
-rw-r--r--doc/user/mergeflags.xml2
-rw-r--r--doc/user/misc.in12
-rw-r--r--doc/user/misc.xml6
-rw-r--r--doc/user/nodes.in2
-rw-r--r--doc/user/nodes.xml4
-rw-r--r--doc/user/output.in4
-rw-r--r--doc/user/output.xml2
-rw-r--r--doc/user/parseconfig.in2
-rw-r--r--doc/user/parseconfig.xml2
-rw-r--r--doc/user/parseflags.in2
-rw-r--r--doc/user/parseflags.xml3
-rw-r--r--doc/user/preface.in6
-rw-r--r--doc/user/preface.xml2
-rw-r--r--doc/user/python.in2
-rw-r--r--doc/user/python.xml2
-rw-r--r--doc/user/repositories.in6
-rw-r--r--doc/user/repositories.xml6
-rw-r--r--doc/user/run.in2
-rw-r--r--doc/user/run.xml2
-rw-r--r--doc/user/scanners.in17
-rw-r--r--doc/user/scanners.xml17
-rw-r--r--doc/user/sconf.in6
-rw-r--r--doc/user/sconf.xml4
-rw-r--r--doc/user/separate.in2
-rw-r--r--doc/user/separate.xml2
-rw-r--r--doc/user/sideeffect.in2
-rw-r--r--doc/user/sideeffect.xml2
-rw-r--r--doc/user/simple.in10
-rw-r--r--doc/user/simple.xml10
-rw-r--r--doc/user/sourcecode.in2
-rw-r--r--doc/user/sourcecode.xml2
-rw-r--r--doc/user/tasks.in6
-rw-r--r--doc/user/tasks.xml2
-rw-r--r--doc/user/tools.in2
-rw-r--r--doc/user/tools.xml2
-rw-r--r--doc/user/troubleshoot.in49
-rw-r--r--doc/user/troubleshoot.xml57
-rw-r--r--doc/user/variables.in2
-rw-r--r--doc/user/variables.xml2
-rw-r--r--doc/user/variants.in2
-rw-r--r--doc/user/variants.xml3
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/' &lt; $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" &gt; $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 &lt;module&gt;
</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 &lt;module&gt;
% <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 &lt;module&gt;
% <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 &lt;module&gt;
</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 =&gt; 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&lt;-' )
</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&lt;-' )
</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}&lt;-' )
</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( '-&gt;$MISSING&lt;-' )
@@ -790,7 +791,8 @@ environment, of directory names, suffixes, etc.
value is: -&gt;&lt;-
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 &lt; $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 &lt; $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': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&gt;,
'Dirs': &lt;SCons.Defaults.Variable_Method_Caller object at 0x700000&gt;,
@@ -345,7 +346,7 @@
'CC': 'cl',
'CCCOM': &lt;SCons.Action.FunctionAction object at 0x700000&gt;,
'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>