From 738149c9bfb9965d013d01ef99f9bb1c2819e7e8 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Tue, 15 Jun 2010 14:28:22 +0000 Subject: Imported Upstream version 2.0.0 --- doc/user/actions.in | 4 +- doc/user/actions.xml | 4 +- doc/user/build-install.in | 35 ++++++----------- doc/user/build-install.xml | 35 ++++++----------- doc/user/builders-built-in.in | 13 ------ doc/user/builders-built-in.xml | 13 ------ doc/user/builders-writing.in | 30 +++++++------- doc/user/builders-writing.xml | 14 +++---- doc/user/command-line.in | 8 ++-- doc/user/command-line.xml | 8 ++-- doc/user/depends.in | 7 ++-- doc/user/depends.xml | 7 ++-- doc/user/environments.in | 88 +++++++++++++++++++++++++++++++++++++---- doc/user/environments.xml | 89 ++++++++++++++++++++++++++++++++++++++---- doc/user/less-simple.in | 2 +- doc/user/less-simple.xml | 2 +- doc/user/main.in | 11 +----- doc/user/main.xml | 7 ---- doc/user/misc.in | 4 +- doc/user/misc.xml | 6 +-- doc/user/nodes.in | 45 +++++++++++++++++++++ doc/user/nodes.xml | 45 +++++++++++++++++++++ doc/user/parseflags.in | 16 ++------ doc/user/parseflags.xml | 16 ++------ doc/user/scanners.in | 50 ++++++++++++++++++++++++ doc/user/scanners.xml | 48 +++++++++++++++++++++++ doc/user/tasks.in | 27 ------------- doc/user/tasks.xml | 27 ------------- doc/user/troubleshoot.xml | 40 +++++++++---------- 29 files changed, 452 insertions(+), 249 deletions(-) (limited to 'doc/user') diff --git a/doc/user/actions.in b/doc/user/actions.in index 3f91c67..06dcd63 100644 --- a/doc/user/actions.in +++ b/doc/user/actions.in @@ -245,7 +245,7 @@ solutions to the above limitations. - b = Builder(action = 'build < $SOURCE > $TARGET') + b = Builder(action = 'build < $SOURCE > $TARGET') @@ -255,7 +255,7 @@ solutions to the above limitations. - b = Builder(action = Action('build < $SOURCE > $TARGET')) + b = Builder(action = Action('build < $SOURCE > $TARGET')) diff --git a/doc/user/actions.xml b/doc/user/actions.xml index f969698..7231a70 100644 --- a/doc/user/actions.xml +++ b/doc/user/actions.xml @@ -245,7 +245,7 @@ solutions to the above limitations. - b = Builder(action = 'build < $SOURCE > $TARGET') + b = Builder(action = 'build < $SOURCE > $TARGET') @@ -255,7 +255,7 @@ solutions to the above limitations. - b = Builder(action = Action('build < $SOURCE > $TARGET')) + b = Builder(action = Action('build < $SOURCE > $TARGET')) diff --git a/doc/user/build-install.in b/doc/user/build-install.in index 577c140..05ead9d 100644 --- a/doc/user/build-install.in +++ b/doc/user/build-install.in @@ -111,17 +111,6 @@ - (Note that the option - was added to Python version 2.0, - so if your system only has an earlier version available - you may see an - "Unknown option: -V" - error message.) - - - - - The standard location for information about downloading and installing Python is http://www.python.org/download/. @@ -132,10 +121,10 @@ - &SCons; will work with any version of Python from 1.5.2 or later. + &SCons; will work with any version of Python from 2.4 or later. If you need to install Python and have a choice, - we recommend using the most recent Python 2.5 version available. - Python 2.5 has significant improvements + we recommend using the most recent Python version available. + Newer Pythons have significant improvements that help speed up the performance of &SCons;. @@ -209,7 +198,7 @@ - # rpm -Uvh scons-1.3.0-1.noarch.rpm + # rpm -Uvh scons-2.0.0.final.0-1.noarch.rpm @@ -271,7 +260,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the scons-1.3.0.win32.exe + Download the scons-2.0.0.final.0.win32.exe file from the &SCons; download page at http://www.scons.org/download.php. Then all you need to do is execute the file @@ -381,8 +370,8 @@ The first step is to download either the - scons-1.3.0.tar.gz - or scons-1.3.0.zip, + scons-2.0.0.final.0.tar.gz + or scons-2.0.0.final.0.zip, which are available from the SCons download page at http://www.scons.org/download.html. @@ -395,7 +384,7 @@ on Linux or UNIX, or WinZip on Windows. This will create a directory called - scons-1.3.0, + scons-2.0.0.final.0, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -403,7 +392,7 @@ - # cd scons-1.3.0 + # cd scons-2.0.0.final.0 # python setup.py install @@ -471,9 +460,9 @@ This will install the &SCons; build engine in the - /usr/lib/scons-1.3.0 + /usr/lib/scons-2.0.0.final.0 or - C:\Python25\scons-1.3.0 + C:\Python25\scons-2.0.0.final.0 directory, for example. @@ -530,7 +519,7 @@ relative to the specified prefix. Adding to the above example would install the build engine in - /opt/scons/lib/scons-1.3.0. + /opt/scons/lib/scons-2.0.0.final.0. diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index 577c140..05ead9d 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -111,17 +111,6 @@ - (Note that the option - was added to Python version 2.0, - so if your system only has an earlier version available - you may see an - "Unknown option: -V" - error message.) - - - - - The standard location for information about downloading and installing Python is http://www.python.org/download/. @@ -132,10 +121,10 @@ - &SCons; will work with any version of Python from 1.5.2 or later. + &SCons; will work with any version of Python from 2.4 or later. If you need to install Python and have a choice, - we recommend using the most recent Python 2.5 version available. - Python 2.5 has significant improvements + we recommend using the most recent Python version available. + Newer Pythons have significant improvements that help speed up the performance of &SCons;. @@ -209,7 +198,7 @@ - # rpm -Uvh scons-1.3.0-1.noarch.rpm + # rpm -Uvh scons-2.0.0.final.0-1.noarch.rpm @@ -271,7 +260,7 @@ &SCons; provides a Windows installer that makes installation extremely easy. - Download the scons-1.3.0.win32.exe + Download the scons-2.0.0.final.0.win32.exe file from the &SCons; download page at http://www.scons.org/download.php. Then all you need to do is execute the file @@ -381,8 +370,8 @@ The first step is to download either the - scons-1.3.0.tar.gz - or scons-1.3.0.zip, + scons-2.0.0.final.0.tar.gz + or scons-2.0.0.final.0.zip, which are available from the SCons download page at http://www.scons.org/download.html. @@ -395,7 +384,7 @@ on Linux or UNIX, or WinZip on Windows. This will create a directory called - scons-1.3.0, + scons-2.0.0.final.0, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: @@ -403,7 +392,7 @@ - # cd scons-1.3.0 + # cd scons-2.0.0.final.0 # python setup.py install @@ -471,9 +460,9 @@ This will install the &SCons; build engine in the - /usr/lib/scons-1.3.0 + /usr/lib/scons-2.0.0.final.0 or - C:\Python25\scons-1.3.0 + C:\Python25\scons-2.0.0.final.0 directory, for example. @@ -530,7 +519,7 @@ relative to the specified prefix. Adding to the above example would install the build engine in - /opt/scons/lib/scons-1.3.0. + /opt/scons/lib/scons-2.0.0.final.0. diff --git a/doc/user/builders-built-in.in b/doc/user/builders-built-in.in index 2c3045b..f7da806 100644 --- a/doc/user/builders-built-in.in +++ b/doc/user/builders-built-in.in @@ -838,19 +838,6 @@ scons -Q . - - - If you're using Python version 1.5.2 to run &SCons;, - then &SCons; will try to use an external - &zip; program as follows: - - - - - % scons -Q . - zip /home/my/project/zip.out file1 file2 - - diff --git a/doc/user/builders-built-in.xml b/doc/user/builders-built-in.xml index a947f8b..3d47f5c 100644 --- a/doc/user/builders-built-in.xml +++ b/doc/user/builders-built-in.xml @@ -812,19 +812,6 @@ zip(["out.zip"], ["file1", "file2"]) - - - If you're using Python version 1.5.2 to run &SCons;, - then &SCons; will try to use an external - &zip; program as follows: - - - - - % scons -Q . - zip /home/my/project/zip.out file1 file2 - - diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index fda83cd..0bf6971 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -129,7 +129,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') @@ -165,7 +165,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() @@ -180,7 +180,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) @@ -276,7 +276,7 @@ This functionality could be invoked as in the following example: env = Environment() import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -294,7 +294,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -309,7 +309,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -352,7 +352,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -373,7 +373,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -544,7 +544,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (target[0], source[0]) + return 'foobuild < %s > %s' % (target[0], source[0]) @@ -647,7 +647,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -666,7 +666,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -790,7 +790,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'my_command $SOURCES > $TARGET', + bld = Builder(action = 'my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') @@ -828,7 +828,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'my_command $SOURCES > $TARGET', + bld = Builder(action = 'my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') @@ -934,8 +934,8 @@ This functionality could be invoked as in the following example: def TOOL_ADD_HEADER(env): """A Tool to add a header from $HEADER to the source file""" - add_header = Builder(action=['echo "$HEADER" > $TARGET', - 'cat $SOURCE >> $TARGET']) + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) env.Append(BUILDERS = {'AddHeader' : add_header}) env['HEADER'] = '' # set default value diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index 5c01934..f364e27 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -166,7 +166,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) @@ -233,7 +233,7 @@ This functionality could be invoked as in the following example: % scons -Q - AttributeError: SConsEnvironment instance has no attribute 'Program': + AttributeError: 'SConsEnvironment' object has no attribute 'Program': File "/home/my/project/SConstruct", line 4: env.Program('hello.c') @@ -251,7 +251,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -266,7 +266,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -313,7 +313,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -586,7 +586,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -708,7 +708,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'my_command $SOURCES > $TARGET', + bld = Builder(action = 'my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') diff --git a/doc/user/command-line.in b/doc/user/command-line.in index d910546..cd5ead6 100644 --- a/doc/user/command-line.in +++ b/doc/user/command-line.in @@ -943,8 +943,8 @@ These older names still work, and you may encounter them in older &SConscript; fles, - but their use is discouraged - and will be officially deprecated some day. + but they have been officially deprecated + as of &SCons; version 2.0. @@ -1237,7 +1237,7 @@ choices to a specific set of allowed colors. This can be set up quite easily using the &EnumVariable;, - which takes a list of &allowed_values + which takes a list of &allowed_values; in addition to the variable name, default value, and help text arguments: @@ -2154,7 +2154,7 @@ &SCons; supports a &DEFAULT_TARGETS; variable that lets you get at the current list of default targets. - The &DEFAULT_TARGETS variable has + The &DEFAULT_TARGETS; variable has two important differences from the &COMMAND_LINE_TARGETS; variable. First, the &DEFAULT_TARGETS; variable is a list of internal &SCons; nodes, diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 21b52dd..8bc72bb 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -926,8 +926,8 @@ These older names still work, and you may encounter them in older &SConscript; fles, - but their use is discouraged - and will be officially deprecated some day. + but they have been officially deprecated + as of &SCons; version 2.0. @@ -1208,7 +1208,7 @@ choices to a specific set of allowed colors. This can be set up quite easily using the &EnumVariable;, - which takes a list of &allowed_values + which takes a list of &allowed_values; in addition to the variable name, default value, and help text arguments: @@ -2064,7 +2064,7 @@ &SCons; supports a &DEFAULT_TARGETS; variable that lets you get at the current list of default targets. - The &DEFAULT_TARGETS variable has + The &DEFAULT_TARGETS; variable has two important differences from the &COMMAND_LINE_TARGETS; variable. First, the &DEFAULT_TARGETS; variable is a list of internal &SCons; nodes, diff --git a/doc/user/depends.in b/doc/user/depends.in index 213713f..69bb242 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -672,13 +672,14 @@ &SCons; still supports two functions that used to be the primary methods for configuring the decision about whether or not an input file has changed. - Although they're not officially deprecated yet, - their use is discouraged, + These functions have been officially deprecated + as &SCons; version 2.0, + and their use is discouraged, mainly because they rely on a somewhat confusing distinction between how source files and target files are handled. These functions are documented here mainly in case you - encounter them in existing &SConscript; files. + encounter them in older &SConscript; files. diff --git a/doc/user/depends.xml b/doc/user/depends.xml index d386a1f..430e64a 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -661,13 +661,14 @@ &SCons; still supports two functions that used to be the primary methods for configuring the decision about whether or not an input file has changed. - Although they're not officially deprecated yet, - their use is discouraged, + These functions have been officially deprecated + as &SCons; version 2.0, + and their use is discouraged, mainly because they rely on a somewhat confusing distinction between how source files and target files are handled. These functions are documented here mainly in case you - encounter them in existing &SConscript; files. + encounter them in older &SConscript; files. diff --git a/doc/user/environments.in b/doc/user/environments.in index dfe98f2..9ce5568 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -672,11 +672,8 @@ environment, of directory names, suffixes, etc. env = Environment() - dict = env.Dictionary() - keys = dict.keys() - keys.sort() - for key in keys: - print "construction variable = '%s', value = '%s'" % (key, dict[key]) + for item in sorted(env.Dictionary().items()): + print "construction variable = '%s', value = '%s'" % item @@ -774,6 +771,82 @@ environment, of directory names, suffixes, etc. +
+ Handling Problems With Value Expansion + + + + If a problem occurs when expanding a construction variable, + by default it is expanded to '' + (a null string), and will not cause scons to fail. + + + + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + + scons -Q + + + This default behaviour can be changed using the &AllowSubstExceptions; + function. + When a problem occurs with a variable expansion it generates + an exception, and the &AllowSubstExceptions; function controls + which of these exceptions are actually fatal and which are + allowed to occur safely. By default, &NameError; and &IndexError; + are the two exceptions that are allowed to occur: so instead of + causing scons to fail, these are caught, the variable expanded to + '' + and scons execution continues. + To require that all construction variable names exist, and that + indexes out of range are not allowed, call &AllowSubstExceptions; + with no extra arguments. + + + + + AllowSubstExceptions() + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + + scons -Q + + + + This can also be used to allow other exceptions that might occur, + most usefully with the ${...} construction + variable syntax. For example, this would allow zero-division to + occur in a variable expansion in addition to the default exceptions + allowed + + + + + AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) + env = Environment() + print "value is:", env.subst( '->${1 / 0}<-' ) + + + + + scons -Q + + + + + + If &AllowSubstExceptions; is called multiple times, each call + completely overwrites the previous list of allowed exceptions. + + +
+
Controlling the Default &ConsEnv;: the &DefaultEnvironment; Function @@ -1556,11 +1629,10 @@ environment, of directory names, suffixes, etc. #!/usr/bin/env python import os import sys - if len(sys.argv) > 1: + if len(sys.argv) > 1: keys = sys.argv[1:] else: - keys = os.environ.keys() - keys.sort() + keys = sorted(os.environ.keys()) for key in keys: print " " + key + "=" + os.environ[key] diff --git a/doc/user/environments.xml b/doc/user/environments.xml index fafb120..5bb1089 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -672,11 +672,8 @@ environment, of directory names, suffixes, etc. env = Environment() - dict = env.Dictionary() - keys = dict.keys() - keys.sort() - for key in keys: - print "construction variable = '%s', value = '%s'" % (key, dict[key]) + for item in sorted(env.Dictionary().items()): + print "construction variable = '%s', value = '%s'" % item
@@ -774,6 +771,83 @@ environment, of directory names, suffixes, etc. +
+ Handling Problems With Value Expansion + + + + If a problem occurs when expanding a construction variable, + by default it is expanded to '' + (a null string), and will not cause scons to fail. + + + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + % scons -Q + value is: -><- + scons: `.' is up to date. + + + This default behaviour can be changed using the &AllowSubstExceptions; + function. + When a problem occurs with a variable expansion it generates + an exception, and the &AllowSubstExceptions; function controls + which of these exceptions are actually fatal and which are + allowed to occur safely. By default, &NameError; and &IndexError; + are the two exceptions that are allowed to occur: so instead of + causing scons to fail, these are caught, the variable expanded to + '' + and scons execution continues. + To require that all construction variable names exist, and that + indexes out of range are not allowed, call &AllowSubstExceptions; + with no extra arguments. + + + + AllowSubstExceptions() + env = Environment() + print "value is:", env.subst( '->$MISSING<-' ) + + + + % scons -Q + value is: + scons: *** NameError `MISSING' trying to evaluate `$MISSING' + File "/home/my/project/SConstruct", line 3, in <module> + + + + This can also be used to allow other exceptions that might occur, + most usefully with the ${...} construction + variable syntax. For example, this would allow zero-division to + occur in a variable expansion in addition to the default exceptions + allowed + + + + AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) + env = Environment() + print "value is:", env.subst( '->${1 / 0}<-' ) + + + + % scons -Q + value is: -><- + scons: `.' is up to date. + + + + + + If &AllowSubstExceptions; is called multiple times, each call + completely overwrites the previous list of allowed exceptions. + + +
+
Controlling the Default &ConsEnv;: the &DefaultEnvironment; Function @@ -1543,11 +1617,10 @@ environment, of directory names, suffixes, etc. #!/usr/bin/env python import os import sys - if len(sys.argv) > 1: + if len(sys.argv) > 1: keys = sys.argv[1:] else: - keys = os.environ.keys() - keys.sort() + keys = sorted(os.environ.keys()) for key in keys: print " " + key + "=" + os.environ[key] diff --git a/doc/user/less-simple.in b/doc/user/less-simple.in index 4cd00e9..cccad83 100644 --- a/doc/user/less-simple.in +++ b/doc/user/less-simple.in @@ -371,7 +371,7 @@ you'll have realized that this is similar to the split() method in the Python standard string module. - Unlike the string.split() method, + Unlike the split() member function of strings, however, the &Split; function does not require a string as input and will wrap up a single non-string object in a list, diff --git a/doc/user/less-simple.xml b/doc/user/less-simple.xml index 17ce181..24b45e6 100644 --- a/doc/user/less-simple.xml +++ b/doc/user/less-simple.xml @@ -360,7 +360,7 @@ you'll have realized that this is similar to the split() method in the Python standard string module. - Unlike the string.split() method, + Unlike the split() member function of strings, however, the &Split; function does not require a string as input and will wrap up a single non-string object in a list, diff --git a/doc/user/main.in b/doc/user/main.in index be4fd21..fbc28df 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -96,14 +96,7 @@
+ +
+ Adding a search path to a scanner: &FindPathDirs; + + + + Many scanners need to search for included files or dependencies + using a path variable; this is how &cv-link-CPPPATH; and + &cv-link-LIBPATH; work. The path to search is passed to your + scanner as the path argument. Path variables + may be lists of nodes, semicolon-separated strings, or even + contain SCons variables which need to be expanded. Fortunately, + &SCons; provides the &FindPathDirs; function which itself returns + a function to expand a given path (given as a SCons construction + variable name) to a list of paths at the time the scanner is + called. Deferring evaluation until that point allows, for + instance, the path to contain $TARGET references which differ for + each file scanned. + + + + + + Using &FindPathDirs; is quite easy. Continuing the above example, + using KPATH as the construction variable with the search path + (analogous to &cv-link-CPPPATH;), we just modify the &Scanner; + constructor call to include a path keyword arg: + + + + + + kscan = Scanner(function = kfile_scan, + skeys = ['.k'], + path=FindPathDirs('KPATH')) + + + + + + FindPathDirs returns a callable object that, when called, will + essentially expand the elements in env['KPATH'] and tell the + scanner to search in those dirs. It will also properly add + related repository and variant dirs to the search list. As a side + note, the returned method stores the path in an efficient way so + lookups are fast even when variable substitutions may be needed. + This is important since many files get scanned in a typical build. + + +
diff --git a/doc/user/scanners.xml b/doc/user/scanners.xml index 7921577..2aba7d2 100644 --- a/doc/user/scanners.xml +++ b/doc/user/scanners.xml @@ -315,3 +315,51 @@ over the file scanning rather than being called for each input line: --> + +
+ Adding a search path to a scanner: &FindPathDirs; + + + + Many scanners need to search for included files or dependencies + using a path variable; this is how &cv-link-CPPPATH; and + &cv-link-LIBPATH; work. The path to search is passed to your + scanner as the path argument. Path variables + may be lists of nodes, semicolon-separated strings, or even + contain SCons variables which need to be expanded. Fortunately, + &SCons; provides the &FindPathDirs; function which itself returns + a function to expand a given path (given as a SCons construction + variable name) to a list of paths at the time the scanner is + called. Deferring evaluation until that point allows, for + instance, the path to contain $TARGET references which differ for + each file scanned. + + + + + + Using &FindPathDirs; is quite easy. Continuing the above example, + using KPATH as the construction variable with the search path + (analogous to &cv-link-CPPPATH;), we just modify the &Scanner; + constructor call to include a path keyword arg: + + + + + kscan = Scanner(function = kfile_scan, + skeys = ['.k'], + path=FindPathDirs('KPATH')) + + + + + FindPathDirs returns a callable object that, when called, will + essentially expand the elements in env['KPATH'] and tell the + scanner to search in those dirs. It will also properly add + related repository and variant dirs to the search list. As a side + note, the returned method stores the path in an efficient way so + lookups are fast even when variable substitutions may be needed. + This is important since many files get scanned in a typical build. + + +
diff --git a/doc/user/tasks.in b/doc/user/tasks.in index fd87bd2..2945d1c 100644 --- a/doc/user/tasks.in +++ b/doc/user/tasks.in @@ -53,15 +53,6 @@ filename = os.path.splitext(filename)[0]+extension import os.path filenames = [os.path.join(prefix, x) for x in filenames] - -or in Python 1.5.2: - - -import os.path -new_filenames = [] -for x in filenames: - new_filenames.append(os.path.join(prefix, x)) - @@ -70,14 +61,6 @@ for x in filenames: if filename.find(old_prefix) == 0: filename = filename.replace(old_prefix, new_prefix) - -or in Python 1.5.2: - - -import string -if string.find(filename, old_prefix) == 0: - filename = string.replace(filename, old_prefix, new_prefix) - @@ -87,16 +70,6 @@ of extensions import os.path filenames = [x for x in filenames if os.path.splitext(x)[1] in extensions] - -or in Python 1.5.2: - - -import os.path -new_filenames = [] -for x in filenames: - if os.path.splitext(x)[1] in extensions: - new_filenames.append(x) - diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml index fd87bd2..2945d1c 100644 --- a/doc/user/tasks.xml +++ b/doc/user/tasks.xml @@ -53,15 +53,6 @@ filename = os.path.splitext(filename)[0]+extension import os.path filenames = [os.path.join(prefix, x) for x in filenames] - -or in Python 1.5.2: - - -import os.path -new_filenames = [] -for x in filenames: - new_filenames.append(os.path.join(prefix, x)) - @@ -70,14 +61,6 @@ for x in filenames: if filename.find(old_prefix) == 0: filename = filename.replace(old_prefix, new_prefix) - -or in Python 1.5.2: - - -import string -if string.find(filename, old_prefix) == 0: - filename = string.replace(filename, old_prefix, new_prefix) - @@ -87,16 +70,6 @@ of extensions import os.path filenames = [x for x in filenames if os.path.splitext(x)[1] in extensions] - -or in Python 1.5.2: - - -import os.path -new_filenames = [] -for x in filenames: - if os.path.splitext(x)[1] in extensions: - new_filenames.append(x) - diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index 428aa69..468af92 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -284,11 +284,11 @@ '.spp', '.SPP'], 'DSUFFIXES': ['.d'], - 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, - 'Dirs': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, - 'ENV': {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}, + 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, + 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, + 'ENV': { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'}, 'ESCAPE': <function escape at 0x700000>, - 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, + 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'HOST_ARCH': None, 'HOST_OS': None, 'IDLSUFFIXES': ['.idl', '.IDL'], @@ -304,7 +304,7 @@ 'PROGPREFIX': '', 'PROGSUFFIX': '', 'PSPAWN': <function piped_env_spawn at 0x700000>, - 'RDirs': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, + 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'SCANNERS': [], 'SHELL': 'sh', 'SHLIBPREFIX': '$LIBPREFIX', @@ -314,7 +314,7 @@ 'SPAWN': <function spawnvpe_spawn at 0x700000>, 'TARGET_ARCH': None, 'TARGET_OS': None, - 'TEMPFILE': <class SCons.Platform.TempFileMunge at 0x700000>, + 'TEMPFILE': <class 'SCons.Platform.TempFileMunge'>, 'TEMPFILEPREFIX': '@', 'TOOLS': ['install', 'install'], '_CPPDEFFLAGS': '${_defines(CPPDEFPREFIX, CPPDEFINES, CPPDEFSUFFIX, __env__)}', @@ -341,9 +341,9 @@ C:\>scons scons: Reading SConscript files ... - { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'PCH': <SCons.Builder.BuilderBase instance at 0x700000>, 'RES': <SCons.Builder.BuilderBase instance at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder instance at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, + { 'BUILDERS': {'_InternalInstall': <function InstallBuilderWrapper at 0x700000>, 'Object': <SCons.Builder.CompositeBuilder object at 0x700000>, 'PCH': <SCons.Builder.BuilderBase object at 0x700000>, 'RES': <SCons.Builder.BuilderBase object at 0x700000>, 'SharedObject': <SCons.Builder.CompositeBuilder object at 0x700000>, 'StaticObject': <SCons.Builder.CompositeBuilder object at 0x700000>, '_InternalInstallAs': <function InstallAsBuilderWrapper at 0x700000>}, 'CC': 'cl', - 'CCCOM': <SCons.Action.FunctionAction instance at 0x700000>, + 'CCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'CCFLAGS': ['/nologo'], 'CCPCHFLAGS': ['${(PCH and "/Yu%s /Fp%s"%(PCHSTOP or "",File(PCH))) or ""}'], 'CCPDBFLAGS': ['${(PDB and "/Z7") or ""}'], @@ -377,13 +377,13 @@ 'CXXFILESUFFIX': '.cc', 'CXXFLAGS': ['$(', '/TP', '$)'], 'DSUFFIXES': ['.d'], - 'Dir': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, - 'Dirs': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, + 'Dir': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, + 'Dirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'ENV': { 'PATH': 'C:\\WINDOWS\\System32', 'PATHEXT': '.COM;.EXE;.BAT;.CMD', 'SystemRoot': 'C:\\WINDOWS'}, 'ESCAPE': <function escape at 0x700000>, - 'File': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, + 'File': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'HOST_ARCH': '', 'HOST_OS': 'win32', 'IDLSUFFIXES': ['.idl', '.IDL'], @@ -405,13 +405,13 @@ 'PROGSUFFIX': '.exe', 'PSPAWN': <function piped_spawn at 0x700000>, 'RC': 'rc', - 'RCCOM': <SCons.Action.FunctionAction instance at 0x700000>, + 'RCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'RCFLAGS': [], 'RCSUFFIXES': ['.rc', '.rc2'], - 'RDirs': <SCons.Defaults.Variable_Method_Caller instance at 0x700000>, + 'RDirs': <SCons.Defaults.Variable_Method_Caller object at 0x700000>, 'SCANNERS': [], 'SHCC': '$CC', - 'SHCCCOM': <SCons.Action.FunctionAction instance at 0x700000>, + 'SHCCCOM': <SCons.Action.FunctionAction object at 0x700000>, 'SHCCFLAGS': ['$CCFLAGS'], 'SHCFLAGS': ['$CFLAGS'], 'SHCXX': '$CXX', @@ -426,7 +426,7 @@ 'STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME': 1, 'TARGET_ARCH': '', 'TARGET_OS': 'win32', - 'TEMPFILE': <class SCons.Platform.TempFileMunge at 0x700000>, + 'TEMPFILE': <class 'SCons.Platform.TempFileMunge'>, 'TEMPFILEPREFIX': '@', 'TOOLS': ['msvc', 'install', 'install'], '_CCCOMCOM': '$CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $CCPCHFLAGS $CCPDBFLAGS', @@ -489,7 +489,7 @@ % scons scons: Reading SConscript files ... - {'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'} + { 'PATH': '/usr/local/bin:/opt/bin:/bin:/usr/bin'} scons: done reading SConscript files. scons: Building targets ... scons: `.' is up to date. @@ -1118,14 +1118,14 @@ % scons -Q --debug=stacktrace scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. scons: internal stack trace: - File "bootstrap/src/engine/SCons/Job.py", line 197, in start + 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 return SCons.Taskmaster.OutOfDateTask.prepare(self) - File "bootstrap/src/engine/SCons/Taskmaster.py", line 190, in prepare + File "bootstrap/src/engine/SCons/Taskmaster.py", line 187, in prepare executor.prepare() - File "bootstrap/src/engine/SCons/Executor.py", line 397, in prepare - raise SCons.Errors.StopError, msg % (s, self.batches[0].targets[0]) + File "bootstrap/src/engine/SCons/Executor.py", line 392, in prepare + raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0])) -- cgit v1.2.3