From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Sat, 10 Sep 2011 11:25:53 +0200 Subject: Imported Upstream version 2.1.0 --- src/engine/SCons/Script/Interactive.py | 4 +- src/engine/SCons/Script/Main.py | 93 +++- src/engine/SCons/Script/Main.xml | 710 +++++++++++++++++++++++++++++ src/engine/SCons/Script/MainTests.py | 4 +- src/engine/SCons/Script/SConsOptions.py | 10 +- src/engine/SCons/Script/SConscript.py | 4 +- src/engine/SCons/Script/SConscript.xml | 509 +++++++++++++++++++++ src/engine/SCons/Script/SConscriptTests.py | 4 +- src/engine/SCons/Script/__init__.py | 4 +- 9 files changed, 1316 insertions(+), 26 deletions(-) create mode 100644 src/engine/SCons/Script/Main.xml create mode 100644 src/engine/SCons/Script/SConscript.xml (limited to 'src/engine/SCons/Script') diff --git a/src/engine/SCons/Script/Interactive.py b/src/engine/SCons/Script/Interactive.py index e2906d4..f2151fa 100644 --- a/src/engine/SCons/Script/Interactive.py +++ b/src/engine/SCons/Script/Interactive.py @@ -1,5 +1,5 @@ # -# 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 @@ -20,7 +20,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. -__revision__ = "src/engine/SCons/Script/Interactive.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/Interactive.py 5357 2011/09/09 21:31:03 bdeegan" __doc__ = """ SCons interactive mode diff --git a/src/engine/SCons/Script/Main.py b/src/engine/SCons/Script/Main.py index 31bcff3..2f00e5c 100644 --- a/src/engine/SCons/Script/Main.py +++ b/src/engine/SCons/Script/Main.py @@ -13,7 +13,7 @@ it goes here. unsupported_python_version = (2, 3, 0) deprecated_python_version = (2, 4, 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 @@ -34,7 +34,7 @@ deprecated_python_version = (2, 4, 0) # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -__revision__ = "src/engine/SCons/Script/Main.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/Main.py 5357 2011/09/09 21:31:03 bdeegan" import SCons.compat @@ -60,6 +60,7 @@ import SCons.Errors import SCons.Job import SCons.Node import SCons.Node.FS +import SCons.Platform import SCons.SConf import SCons.Script import SCons.Taskmaster @@ -653,6 +654,10 @@ def _set_debug_values(options): print_time = 1 if "tree" in debug_values: options.tree_printers.append(TreePrinter()) + if "prepare" in debug_values: + SCons.Taskmaster.print_prepare = 1 + if "duplicate" in debug_values: + SCons.Node.FS.print_duplicate = 1 def _create_path(plist): path = '.' @@ -665,15 +670,15 @@ def _create_path(plist): def _load_site_scons_dir(topdir, site_dir_name=None): """Load the site_scons dir under topdir. - Adds site_scons to sys.path, imports site_scons/site_init.py, - and adds site_scons/site_tools to default toolpath.""" + Prepends site_scons to sys.path, imports site_scons/site_init.py, + and prepends site_scons/site_tools to default toolpath.""" if site_dir_name: err_if_not_found = True # user specified: err if missing else: site_dir_name = "site_scons" err_if_not_found = False - site_dir = os.path.join(topdir.path, site_dir_name) + site_dir = os.path.join(topdir, site_dir_name) if not os.path.exists(site_dir): if err_if_not_found: raise SCons.Errors.UserError("site dir %s not found."%site_dir) @@ -682,11 +687,12 @@ def _load_site_scons_dir(topdir, site_dir_name=None): site_init_filename = "site_init.py" site_init_modname = "site_init" site_tools_dirname = "site_tools" + # prepend to sys.path sys.path = [os.path.abspath(site_dir)] + sys.path site_init_file = os.path.join(site_dir, site_init_filename) site_tools_dir = os.path.join(site_dir, site_tools_dirname) if os.path.exists(site_init_file): - import imp + import imp, re # TODO(2.4): turn this into try:-except:-finally: try: try: @@ -705,14 +711,26 @@ def _load_site_scons_dir(topdir, site_dir_name=None): fmt = 'cannot import site_init.py: missing SCons.Script module %s' raise SCons.Errors.InternalError(fmt % repr(e)) try: + sfx = description[0] + modname = os.path.basename(pathname)[:-len(sfx)] + site_m = {"__file__": pathname, "__name__": modname, "__doc__": None} + re_special = re.compile("__[^_]+__") + for k in m.__dict__.keys(): + if not re_special.match(k): + site_m[k] = m.__dict__[k] + # This is the magic. - exec fp in m.__dict__ + exec fp in site_m except KeyboardInterrupt: raise except Exception, e: fmt = '*** Error loading site_init file %s:\n' sys.stderr.write(fmt % repr(site_init_file)) raise + else: + for k in site_m: + if not re_special.match(k): + m.__dict__[k] = site_m[k] except KeyboardInterrupt: raise except ImportError, e: @@ -723,7 +741,55 @@ def _load_site_scons_dir(topdir, site_dir_name=None): if fp: fp.close() if os.path.exists(site_tools_dir): - SCons.Tool.DefaultToolpath.append(os.path.abspath(site_tools_dir)) + # prepend to DefaultToolpath + SCons.Tool.DefaultToolpath.insert(0, os.path.abspath(site_tools_dir)) + +def _load_all_site_scons_dirs(topdir, verbose=None): + """Load all of the predefined site_scons dir. + Order is significant; we load them in order from most generic + (machine-wide) to most specific (topdir). + The verbose argument is only for testing. + """ + platform = SCons.Platform.platform_default() + + def homedir(d): + return os.path.expanduser('~/'+d) + + if platform == 'win32' or platform == 'cygwin': + # Note we use $ here instead of %...% because older + # pythons (prior to 2.6?) didn't expand %...% on Windows. + # This set of dirs should work on XP, Vista, 7 and later. + sysdirs=[ + os.path.expandvars('$ALLUSERSPROFILE\\Application Data\\scons'), + os.path.expandvars('$USERPROFILE\\Local Settings\\Application Data\\scons')] + appdatadir = os.path.expandvars('$APPDATA\\scons') + if appdatadir not in sysdirs: + sysdirs.append(appdatadir) + sysdirs.append(homedir('.scons')) + + elif platform == 'darwin': # MacOS X + sysdirs=['/Library/Application Support/SCons', + '/opt/local/share/scons', # (for MacPorts) + '/sw/share/scons', # (for Fink) + homedir('Library/Application Support/SCons'), + homedir('.scons')] + elif platform == 'sunos': # Solaris + sysdirs=['/opt/sfw/scons', + '/usr/share/scons', + homedir('.scons')] + else: # Linux, HPUX, etc. + # assume posix-like, i.e. platform == 'posix' + sysdirs=['/usr/share/scons', + homedir('.scons')] + + dirs=sysdirs + [topdir] + for d in dirs: + if verbose: # this is used by unit tests. + print "Loading site dir ", d + _load_site_scons_dir(d) + +def test_load_all_site_scons_dirs(d): + _load_all_site_scons_dirs(d, True) def version_string(label, module): version = module.__version__ @@ -739,6 +805,10 @@ def version_string(label, module): module.__developer__, module.__buildsys__) +def path_string(label, module): + path = module.__path__ + return "\t%s path: %s\n"%(label,path) + def _main(parser): global exit_status global this_build_status @@ -860,9 +930,9 @@ def _main(parser): progress_display.set_mode(0) if options.site_dir: - _load_site_scons_dir(d, options.site_dir) + _load_site_scons_dir(d.path, options.site_dir) elif not options.no_site_dir: - _load_site_scons_dir(d) + _load_all_site_scons_dirs(d.path) if options.include_dir: sys.path = options.include_dir + sys.path @@ -1258,7 +1328,8 @@ def main(): # __main__.__version__, hence there is no script version. pass parts.append(version_string("engine", SCons)) - parts.append("Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation") + parts.append(path_string("engine", SCons)) + parts.append("Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation") version = ''.join(parts) import SConsOptions diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml new file mode 100644 index 0000000..9c97826 --- /dev/null +++ b/src/engine/SCons/Script/Main.xml @@ -0,0 +1,710 @@ + + + + +(arguments) + + +This function adds a new command-line option to be recognized. +The specified +arguments +are the same as supported by the standard Python +optparse.add_option() +method (with a few additional capabilities noted below); +see the documentation for +optparse +for a thorough discussion of its option-processing capabities. + +In addition to the arguments and values supported by the +optparse.add_option() +method, +the SCons +&f-AddOption; +function allows you to set the +nargs +keyword value to +'?' +(a string with just the question mark) +to indicate that the specified long option(s) take(s) an +optional +argument. +When +nargs = '?' +is passed to the +&f-AddOption; +function, the +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 +default= +keyword argument is supplied when calling +&f-AddOption;, +the option will have a default value of +None. + +Once a new command-line option has been added with +&f-AddOption;, +the option value may be accessed using +&f-GetOption; +or +env.GetOption(). +The value may also be set, using +&f-SetOption; +or +env.SetOption(), +if conditions in a +&SConscript; +require overriding any default value. +Note, however, that a +value specified on the command line will +always +override a value set by any SConscript file. + +Any specified +help= +strings for the new option(s) +will be displayed by the + +or + +options +(the latter only if no other help text is +specified in the SConscript files). +The help text for the local options specified by +&f-AddOption; +will appear below the SCons options themselves, +under a separate +Local Options +heading. +The options will appear in the help text +in the order in which the +&f-AddOption; +calls occur. + +Example: + + +AddOption('--prefix', + dest='prefix', + nargs=1, type='string', + action='store', + metavar='DIR', + help='installation prefix') +env = Environment(PREFIX = GetOption('prefix')) + + + + + + +() + + +Returns a list of exceptions for the +actions that failed while +attempting to build targets. +Each element in the returned list is a +BuildError +object +with the following attributes +that record various aspects +of the build failure: + +.node +The node that was being built +when the build failure occurred. + +.status +The numeric exit status +returned by the command or Python function +that failed when trying to build the +specified Node. + +.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.) + +.filename +The name of the file or +directory that actually caused the failure. +This may be different from the +.node +attribute. +For example, +if an attempt to build a target named +sub/dir/target +fails because the +sub/dir +directory could not be created, +then the +.node +attribute will be +sub/dir/target +but the +.filename +attribute will be +sub/dir. + +.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. + +.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. + +.command +The actual expanded command that was executed and failed, +after expansion of +&cv-link-TARGET;, +&cv-link-SOURCE;, +and other construction variables. + +Note that the +&f-GetBuildFailures; +function +will always return an empty list +until any build failure has occurred, +which means that +&f-GetBuildFailures; +will always return an empty list +while the +&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 +atexit.register() +function. +Example: + + +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) + + + + + + +(name) + + +This function provides a way to query the value of +SCons options set on scons command line +(or set using the +&f-link-SetOption; +function). +The options supported are: + + + +cache_debug + + +which corresponds to --cache-debug; + + + + +cache_disable + + +which corresponds to --cache-disable; + + + + +cache_force + + +which corresponds to --cache-force; + + + + +cache_show + + +which corresponds to --cache-show; + + + + +clean + + +which corresponds to -c, --clean and --remove; + + + + +config + + +which corresponds to --config; + + + + +directory + + +which corresponds to -C and --directory; + + + + +diskcheck + + +which corresponds to --diskcheck + + + + +duplicate + + +which corresponds to --duplicate; + + + + +file + + +which corresponds to -f, --file, --makefile and --sconstruct; + + + + +help + + +which corresponds to -h and --help; + + + + +ignore_errors + + +which corresponds to --ignore-errors; + + + + +implicit_cache + + +which corresponds to --implicit-cache; + + + + +implicit_deps_changed + + +which corresponds to --implicit-deps-changed; + + + + +implicit_deps_unchanged + + +which corresponds to --implicit-deps-unchanged; + + + + +interactive + + +which corresponds to --interact and --interactive; + + + + +keep_going + + +which corresponds to -k and --keep-going; + + + + +max_drift + + +which corresponds to --max-drift; + + + + +no_exec + + +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; + + + + +no_site_dir + + +which corresponds to --no-site-dir; + + + + +num_jobs + + +which corresponds to -j and --jobs; + + + + +profile_file + + +which corresponds to --profile; + + + + +question + + +which corresponds to -q and --question; + + + + +random + + +which corresponds to --random; + + + + +repository + + +which corresponds to -Y, --repository and --srcdir; + + + + +silent + + +which corresponds to -s, --silent and --quiet; + + + + +site_dir + + +which corresponds to --site-dir; + + + + +stack_size + + +which corresponds to --stack-size; + + + + +taskmastertrace_file + + +which corresponds to --taskmastertrace; and + + + + +warn + + +which corresponds to --warn and --warning. + + + + + +See the documentation for the +corresponding command line object for information about each specific +option. + + + + + +(callable, [interval]) + + +(string, [interval, file, overwrite]) + + +(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 +__call__() +method), +the function will be called +once every +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 +*args +and +**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: + + +def my_progress_function(node, *args, **kw): + print 'Evaluating node %s!' % node +Progress(my_progress_function, interval=10) + + +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 +\r +(a carriage return) +at the end so that the string +will overwrite itself on a display: + + +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) + + +If the first argument +&f-link-Progress; +is a string, +the string will be displayed +every +interval +evaluated Nodes. +The default is to print the string on standard output; +an alternate output stream +may be specified with the +file= +argument. +The following will print a series of dots +on the error output, +one dot for every 100 evaluated Nodes: + + +import sys +Progress('.', interval=100, file=sys.stderr) + + +If the string contains the verbatim substring +&cv-TARGET;, +it will be replaced with the Node. +Note that, for performance reasons, this is +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 +\r +(carriage return) to cause each line to overwritten by the next line, +and the +overwrite= +keyword argument to make sure the previously-printed +file name is overwritten with blank spaces: + + +import sys +Progress('$TARGET\r', overwrite=True) + + +If the first argument to +&f-Progress; +is a list of strings, +then each string in the list will be displayed +in rotating fashion every +interval +evaluated Nodes. +This can be used to implement a "spinner" +on the user's screen as follows: + + +Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) + + + + + + +(target, ...) + + +Marks each given +target +as precious so it is not deleted before it is rebuilt. Normally +&scons; +deletes a target before building it. +Multiple targets can be passed in to a single call to +&f-Precious;. + + + + + +(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: + + + +clean + + +which corresponds to -c, --clean and --remove; + + + + +duplicate + + +which corresponds to --duplicate; + + + + +help + + +which corresponds to -h and --help; + + + + +implicit_cache + + +which corresponds to --implicit-cache; + + + + +max_drift + + +which corresponds to --max-drift; + + + + +no_exec + + +which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; + + + + +num_jobs + + +which corresponds to -j and --jobs; + + + + +random + + +which corresponds to --random; and + + + + +stack_size + + +which corresponds to --stack-size. + + + + + +See the documentation for the +corresponding command line object for information about each specific +option. + +Example: + + +SetOption('max_drift', 1) + + + diff --git a/src/engine/SCons/Script/MainTests.py b/src/engine/SCons/Script/MainTests.py index 923f791..06780d8 100644 --- a/src/engine/SCons/Script/MainTests.py +++ b/src/engine/SCons/Script/MainTests.py @@ -1,5 +1,5 @@ # -# 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 @@ -21,7 +21,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # -__revision__ = "src/engine/SCons/Script/MainTests.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/MainTests.py 5357 2011/09/09 21:31:03 bdeegan" import unittest import SCons.Errors diff --git a/src/engine/SCons/Script/SConsOptions.py b/src/engine/SCons/Script/SConsOptions.py index 8afedf6..79d9927 100644 --- a/src/engine/SCons/Script/SConsOptions.py +++ b/src/engine/SCons/Script/SConsOptions.py @@ -1,5 +1,5 @@ # -# 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 @@ -21,7 +21,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # -__revision__ = "src/engine/SCons/Script/SConsOptions.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/SConsOptions.py 5357 2011/09/09 21:31:03 bdeegan" import optparse import re @@ -596,9 +596,9 @@ def Parser(version): "tree" : '; please use --tree=all instead', } - debug_options = ["count", "explain", "findlibs", + debug_options = ["count", "duplicate", "explain", "findlibs", "includes", "memoizer", "memory", "objects", - "pdb", "presub", "stacktrace", + "pdb", "prepare", "presub", "stacktrace", "time"] + list(deprecated_debug_options.keys()) def opt_debug(option, opt, value, parser, @@ -867,7 +867,7 @@ def Parser(version): sys.stderr.write(msg) op.add_option('-l', '--load-average', '--max-load', - nargs=1, type="int", + nargs=1, type="float", dest="load_average", default=0, action="callback", callback=opt_not_yet, # action="store", diff --git a/src/engine/SCons/Script/SConscript.py b/src/engine/SCons/Script/SConscript.py index 5e896f1..ee5e290 100644 --- a/src/engine/SCons/Script/SConscript.py +++ b/src/engine/SCons/Script/SConscript.py @@ -6,7 +6,7 @@ files. """ # -# 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 @@ -28,7 +28,7 @@ files. # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. from __future__ import division -__revision__ = "src/engine/SCons/Script/SConscript.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/SConscript.py 5357 2011/09/09 21:31:03 bdeegan" import SCons import SCons.Action diff --git a/src/engine/SCons/Script/SConscript.xml b/src/engine/SCons/Script/SConscript.xml new file mode 100644 index 0000000..f24ca78 --- /dev/null +++ b/src/engine/SCons/Script/SConscript.xml @@ -0,0 +1,509 @@ + + + + +(targets) + + +This specifies a list of default targets, +which will be built by +&scons; +if no explicit targets are given on the command line. +Multiple calls to +&f-Default; +are legal, +and add to the list of default targets. + +Multiple targets should be specified as +separate arguments to the +&f-Default; +method, or as a list. +&f-Default; +will also accept the Node returned by any +of a construction environment's +builder methods. + +Examples: + + +Default('foo', 'bar', 'baz') +env.Default(['a', 'b', 'c']) +hello = env.Program('hello', 'hello.c') +env.Default(hello) + + +An argument to +&f-Default; +of +None +will clear all default targets. +Later calls to +&f-Default; +will add to the (now empty) default-target list +like normal. + +The current list of targets added using the +&f-Default; +function or method is available in the +DEFAULT_TARGETS +list; +see below. + + + + + +(major, minor) + + +Ensure that the Python version is at least +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: + + +EnsurePythonVersion(2,2) + + + + + + +(major, minor, [revision]) + + +Ensure that the SCons version is at least +major.minor, +or +major.minor.revision. +if +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: + + +EnsureSConsVersion(0,14) + +EnsureSConsVersion(0,96,90) + + + + + + +([value]) + + +This tells +&scons; +to exit immediately +with the specified +value. +A default exit value of +0 +(zero) +is used if no value is specified. + + + + + +(vars) + + +This tells +&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 +&f-Export; +will over-write previous exports that have the same name. +Multiple variable names can be passed to +&f-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: + + +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}) + + +Note that the +&f-SConscript; +function supports an +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 +&f-SConscript; +function, below. + + + + + +() + + +Returns the absolute path name of the directory from which +&scons; +was initially invoked. +This can be useful when using the +, + +or + +options, which internally +change to the directory in which the +&SConstruct; +file is found. + + + + + +(text) + + +This specifies help text to be printed if the + +argument is given to +&scons;. +If +&f-Help; +is called multiple times, the text is appended together in the order +that +&f-Help; +is called. + + + + + +(vars) + + +This tells +&scons; +to import a list of variables into the current SConscript file. This +will import variables that were exported with +&f-Export; +or in the +exports +argument to +&f-link-SConscript;. +Variables exported by +&f-SConscript; +have precedence. +Multiple variable names can be passed to +&f-Import; +as separate arguments or as a list. The variable "*" can be used +to import all variables. + +Examples: + + +Import("env") +Import("env", "variable") +Import(["env", "variable"]) +Import("*") + + + + + + +([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 +vars +string arguments. +Multiple strings contaning variable names may be passed to +&f-Return;. +Any strings that contain white space + +The optional +stop= +keyword argument may be set to a false value +to continue processing the rest of the SConscript +file after the +&f-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 +vars +at the point +&f-Return; +is called. + +Examples: + + +# 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') + + + + + + +(scripts, [exports, variant_dir, duplicate]) + + + +(dirs=subdirs, [name=script, exports, variant_dir, duplicate]) + + + +This tells +&scons; +to execute +one or more subsidiary SConscript (configuration) files. +Any variables returned by a called script using +&f-link-Return; +will be returned by the call to +&f-SConscript;. +There are two ways to call the +&f-SConscript; +function. + +The first way you can call +&f-SConscript; +is to explicitly specify one or more +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 +&f-Split;). +Examples: + +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') + + +The second way you can call +&f-SConscript; +is to specify a list of (sub)directory names +as a +dirs=subdirs +keyword argument. +In this case, +&scons; +will, by default, +execute a subsidiary configuration file named +&SConscript; +in each of the specified directories. +You may specify a name other than +&SConscript; +by supplying an optional +name=script +keyword argument. +The first three examples below have the same effect +as the first three examples above: + +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') + + +The optional +exports +argument provides a list of variable names or a dictionary of +named values to export to the +script(s). +These variables are locally exported only to the specified +script(s), +and do not affect the global pool of variables used by the +&f-Export; +function. + +The subsidiary +script(s) +must use the +&f-link-Import; +function to import the variables. +Examples: + +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') + + +If the optional +variant_dir +argument is present, it causes an effect equivalent to the +&f-link-VariantDir; +method described below. +(If +variant_dir +is not present, the + +duplicate + +argument is ignored.) +The +variant_dir + +argument is interpreted relative to the directory of the calling +&SConscript; +file. +See the description of the +&f-VariantDir; +function below for additional details and restrictions. + +If +variant_dir +is present, + +the source directory is the directory in which the +&SConscript; +file resides and the +&SConscript; +file is evaluated as if it were in the +variant_dir +directory: + +SConscript('src/SConscript', variant_dir = 'build') + + +is equivalent to + + +VariantDir('build', 'src') +SConscript('build/SConscript') + + +This later paradigm is often used when the sources are +in the same directory as the +&SConstruct;: + + +SConscript('SConscript', variant_dir = 'build') + + +is equivalent to + + +VariantDir('build', '.') +SConscript('build/SConscript') + + + + +Here are some composite examples: + + +# 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') + + + +# 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) + + + +# 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) + + + +# 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) + + + diff --git a/src/engine/SCons/Script/SConscriptTests.py b/src/engine/SCons/Script/SConscriptTests.py index 6d855ef..ebd89fc 100644 --- a/src/engine/SCons/Script/SConscriptTests.py +++ b/src/engine/SCons/Script/SConscriptTests.py @@ -1,5 +1,5 @@ # -# 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 @@ -21,7 +21,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # -__revision__ = "src/engine/SCons/Script/SConscriptTests.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/SConscriptTests.py 5357 2011/09/09 21:31:03 bdeegan" import SCons.Script.SConscript diff --git a/src/engine/SCons/Script/__init__.py b/src/engine/SCons/Script/__init__.py index b4545ec..f2503ae 100644 --- a/src/engine/SCons/Script/__init__.py +++ b/src/engine/SCons/Script/__init__.py @@ -12,7 +12,7 @@ it goes here. """ # -# 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 @@ it goes here. # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # -__revision__ = "src/engine/SCons/Script/__init__.py 5134 2010/08/16 23:02:40 bdeegan" +__revision__ = "src/engine/SCons/Script/__init__.py 5357 2011/09/09 21:31:03 bdeegan" import time start_time = time.time() -- cgit v1.2.3