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/SConscript | 35 +++++++---------- doc/design/engine.xml | 12 +++--- doc/design/goals.xml | 2 +- doc/design/native.xml | 6 +-- doc/design/overview.xml | 2 +- doc/developer/preface.xml | 2 +- doc/man/scons-time.1 | 4 +- doc/man/scons.1 | 88 ++++++++++++++++++++++++++--------------- doc/man/sconsign.1 | 4 +- doc/python10/abstract.xml | 2 +- doc/python10/design.xml | 50 ++++++++++++------------ doc/python10/main.xml | 2 +- doc/python10/process.xml | 4 +- doc/scons.mod | 7 +++- 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 +++++++++---------- 43 files changed, 574 insertions(+), 347 deletions(-) (limited to 'doc') diff --git a/doc/SConscript b/doc/SConscript index 9ad4d12..e0b3f71 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -23,11 +23,9 @@ # 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. -# import os.path import re -import string Import('build_dir', 'env', 'whereis') @@ -93,7 +91,7 @@ def scanxml(node, env, target): if tail == 'doc': break a = [tail] + a - file = apply(os.path.join, a, {}) + file = os.path.join(*a) includes.append(file) return includes @@ -119,8 +117,8 @@ def chop(s): return s[:-1] #manifest_in = File('#src/engine/MANIFEST.in').rstr() manifest_xml_in = File('#src/engine/MANIFEST-xml.in').rstr() -scons_doc_files = map(chop, open(manifest_xml_in).readlines()) -scons_doc_files = map(lambda x: File('#src/engine/'+x).rstr(), scons_doc_files) +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." @@ -240,7 +238,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. # get included by the document XML files in the subdirectories. # manifest = File('MANIFEST').rstr() - src_files = map(lambda x: x[:-1], open(manifest).readlines()) + src_files = [x[:-1] for x in open(manifest).readlines()] for s in src_files: base, ext = os.path.splitext(s) if ext in ['.fig', '.jpg']: @@ -255,8 +253,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. # for doc in docs.keys(): manifest = File(os.path.join(doc, 'MANIFEST')).rstr() - src_files = map(lambda x: x[:-1], - open(manifest).readlines()) + src_files = [x[:-1] for x in open(manifest).readlines()] build_doc = docs[doc].get('scons-doc') and int(ARGUMENTS.get('BUILDDOC', 0)) for s in src_files: doc_s = os.path.join(doc, s) @@ -408,8 +405,7 @@ for m in man_page_list: man_i_files = ['builders.man', 'tools.man', 'variables.man'] -man_intermediate_files = map(lambda x: os.path.join(build, 'man', x), - man_i_files) +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 $)" man_intermediate_files = env.Command(man_intermediate_files, @@ -444,12 +440,12 @@ for man_1 in man_page_list: def strip_to_first_html_tag(target, source, env): t = str(target[0]) contents = open(t).read() - contents = contents[string.find(contents, ''):] + contents = contents[contents.find(''):] open(t, 'w').write(contents) return 0 cmds = [ - "( cd %s/man && cp %s .. )" % (build, string.join(man_i_files)), + "( cd %s/man && cp %s .. )" % (build, ' '.join(man_i_files)), "( cd ${SOURCE.dir} && man2html ${SOURCE.file} ) > $TARGET", Action(strip_to_first_html_tag), ] @@ -469,15 +465,15 @@ else: # the SConstruct file. e = os.path.join('#src', 'engine') manifest_in = File(os.path.join(e, 'MANIFEST.in')).rstr() - sources = map(lambda x: x[:-1], open(manifest_in).readlines()) - sources = filter(lambda x: string.find(x, 'Optik') == -1, sources) - sources = filter(lambda x: string.find(x, 'Platform') == -1, sources) - sources = filter(lambda x: string.find(x, 'Tool') == -1, sources) + sources = [x[:-1] for x in open(manifest_in).readlines()] + sources = [x for x in sources if x.find('Optik') == -1] + sources = [x for x in sources if x.find('Platform') == -1] + sources = [x for x in sources if x.find('Tool') == -1] # XXX - sources = filter(lambda x: string.find(x, 'Options') == -1, sources) + sources = [x for x in sources if x.find('Options') == -1] e = os.path.join(build, '..', 'scons', 'engine') - sources = map(lambda x, e=e: os.path.join(e, x), sources) + sources = [os.path.join(e, x) for x in sources] epydoc_commands = [ Delete('$OUTDIR'), @@ -519,8 +515,7 @@ else: # for easy distribution to the web site. # if tar_deps: - tar_list = string.join(map(lambda x, b=build+'/': string.replace(x, b, ''), - tar_list)) + tar_list = ' '.join([x.replace(build+'/', '') for x in tar_list]) t = env.Command(dist_doc_tar_gz, tar_deps, "tar cf${TAR_HFLAG} - -C %s %s | gzip > $TARGET" % (build, tar_list)) AddPostAction(dist_doc_tar_gz, Chmod(dist_doc_tar_gz, 0644)) diff --git a/doc/design/engine.xml b/doc/design/engine.xml index 1a1e335..afe9877 100644 --- a/doc/design/engine.xml +++ b/doc/design/engine.xml @@ -85,7 +85,7 @@
- &ConsEnvs + &ConsEnvs; @@ -129,7 +129,7 @@ It would be nice if we could avoid re-inventing the wheel here by - using some other Python-based tool &Autoconf replacement--like what + using some other Python-based tool &Autoconf; replacement--like what was supposed to come out of the Software Carpentry configuration tool contest. It will probably be most efficient to roll our own logic initially and convert if something better does come along. @@ -283,7 +283,7 @@ MyBuilder = Builder(command = "$XX $XXFLAGS -c $_INPUTS -o $target") env.Command(targets = 'bar.out', sources = 'bar.in', - command = "sed '1d' < $source > $target") + command = "sed '1d' < $source > $target") @@ -317,7 +317,7 @@ env = Environment(FUNC = myfunc) env.Command(target = 'foo.out', source = 'foo.in', - command = "${FUNC($<)}") + command = "${FUNC($<)}") @@ -1678,8 +1678,8 @@ I dunno, maybe this is fine as it is... target (that is, one passed to the &Build; or &Clean; method). Objects which a top-level target is directly dependent upon have a - level of <1>, their direct dependencies have a - level of <2>, etc. Typically used to indent + level of <1>, their direct dependencies have a + level of <2>, etc. Typically used to indent output to reflect the recursive levels. diff --git a/doc/design/goals.xml b/doc/design/goals.xml index 2a7b69b..f2e6b7c 100644 --- a/doc/design/goals.xml +++ b/doc/design/goals.xml @@ -26,7 +26,7 @@ As a next-generation build tool, - &SCons should fundamentally + &SCons; should fundamentally improve on its predecessors. Rather than simply being driven by trying to not be like previous tools, diff --git a/doc/design/native.xml b/doc/design/native.xml index 8cdd867..c665e0c 100644 --- a/doc/design/native.xml +++ b/doc/design/native.xml @@ -52,7 +52,7 @@ By default, the &SCons; utility searches for a file named - &SConstruct;, &Sconstruct; or &sconstruct (in that order) in the + &SConstruct;, &Sconstruct; or &sconstruct; (in that order) in the current directory, and reads its configuration from the first file found. A command-line option exists to read a different file name. @@ -175,7 +175,7 @@ Any variables (not just &SCons; objects) that are to be shared between configuration files must be explicitly passed in the &SConscript; call - using the &Export method: + using the &Export; method: @@ -261,7 +261,7 @@ Equivalent to the above example: - &SCons; will allow users to share &consenvs, as well as other &SCons; + &SCons; will allow users to share &consenvs;, as well as other &SCons; objects and Python variables, by importing them from a central, shared repository using normal Python syntax: diff --git a/doc/design/overview.xml b/doc/design/overview.xml index 38e4258..266c9e8 100644 --- a/doc/design/overview.xml +++ b/doc/design/overview.xml @@ -409,7 +409,7 @@ This is where it will go, anyway... An alternate &SCons; interface would provide backwards - compatibility with the classic &Make utility. + compatibility with the classic &Make; utility. This would be done by embedding the &SCons; Build Engine in a Python script that can translate existing &Makefile;s into the underlying calls to the diff --git a/doc/developer/preface.xml b/doc/developer/preface.xml index 05b7562..da2964c 100644 --- a/doc/developer/preface.xml +++ b/doc/developer/preface.xml @@ -36,7 +36,7 @@ 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;: diff --git a/doc/man/scons-time.1 b/doc/man/scons-time.1 index 4160986..81417c3 100644 --- a/doc/man/scons-time.1 +++ b/doc/man/scons-time.1 @@ -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 4720 2010/03/24 03:14:11 jars +.\" doc/man/scons-time.1 5023 2010/06/14 22:05:46 scons .\" .\" 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 "March 2010" +.TH SCONS-TIME 1 "June 2010" .SH NAME scons-time \- generate and display SCons timing information '\"========================================================================== diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 0cfe62a..9617fec 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -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 4720 2010/03/24 03:14:11 jars +.\" doc/man/scons.1 5023 2010/06/14 22:05:46 scons .\" -.TH SCONS 1 "March 2010" +.TH SCONS 1 "June 2010" .\" ES - Example Start - indents and turns off line fill .rm ES .de ES @@ -380,7 +380,7 @@ try to access a list member that does not exist. .B scons -requires Python version 1.5.2 or later. +requires Python version 2.4 or later. There should be no other dependencies or requirements to run .B scons. @@ -591,10 +591,9 @@ Print how many objects are created of the various classes used internally by SCons before and after reading the SConscript files and before and after building targets. -This is not supported when run under Python versions earlier than 2.1, -when SCons is executed with the Python +This is not supported when SCons is executed with the Python .B -O -(optimized) option, +(optimized) option or when the SCons modules have been compiled with optimization (that is, when executing from @@ -642,7 +641,6 @@ Prints a summary of hits and misses using the Memoizer, an internal subsystem that counts how often SCons uses cached values in memory instead of recomputing them each time they're needed. -Only available when using Python 2.2 or later. .TP --debug=memory @@ -658,7 +656,6 @@ A deprecated option preserved for backwards compatibility. --debug=objects Prints a list of the various objects of the various classes used internally by SCons. -This only works when run under Python 2.1 or later. .TP --debug=pdb @@ -1841,9 +1838,7 @@ and a same-named environment method that split a single string into a list, separated on strings of white-space characters. -(These are similar to the -string.split() method -from the standard Python library, +(These are similar to the split() member function of Python strings but work even if the input isn't a string.) Like all Python arguments, @@ -1862,7 +1857,7 @@ env.Program('bar', env.Split('bar.c foo.c')) env.Program(source = ['bar.c', 'foo.c'], target = 'bar') env.Program(target = 'bar', Split('bar.c foo.c')) env.Program(target = 'bar', env.Split('bar.c foo.c')) -env.Program('bar', source = string.split('bar.c foo.c')) +env.Program('bar', source = 'bar.c foo.c'.split()) .EE Target and source file names @@ -2273,11 +2268,13 @@ and Builders by adding them to the .B SourceFileScanner -object as follows: - +object. See the section "Scanner Objects," -below, for a more information about -defining your own Scanner objects. +below, for more information about +defining your own Scanner objects +and using the +.B SourceFileScanner +object. .SS Methods and Functions to Do Things In addition to Builder methods, @@ -2448,13 +2445,6 @@ method (with a few additional capabilities noted below); see the documentation for .B optparse for a thorough discussion of its option-processing capabities. -(Note that although the -.B optparse -module was not a standard module until Python 2.3, -.B scons -contains a compatible version of the module -that is used to provide identical functionality -when run by earlier Python versions.) In addition to the arguments and values supported by the .B optparse.add_option () @@ -2796,6 +2786,10 @@ 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 @@ -3178,6 +3172,10 @@ 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 @@ -3745,7 +3743,7 @@ 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 filesytem, +In addition to searching for files that exist in the filesystem, this function also searches for derived files that have not yet been built. @@ -4729,6 +4727,10 @@ 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 @@ -4844,7 +4846,7 @@ will overwrite itself on a display: .ES import sys -class ProgressCounter: +class ProgressCounter(object): count = 0 def __call__(self, node, *args, **kw): self.count += 100 @@ -5022,6 +5024,10 @@ 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 @@ -5190,6 +5196,10 @@ 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 @@ -5502,7 +5512,7 @@ The default is to use a custom .B SCons.dblite module that uses pickled Python data structures, -and which works on all Python versions from 1.5.2 on. +and which works on all Python versions. Examples: @@ -5534,7 +5544,7 @@ The following statements are equivalent: .ES env.SetDefault(FOO = 'foo') -if not env.has_key('FOO'): env['FOO'] = 'foo' +if 'FOO' not in env: env['FOO'] = 'foo' .EE '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -5648,6 +5658,13 @@ function. .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 @@ -5836,6 +5853,10 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST', '\"directory hierarchy in your '\"local build directory. '\" +'\"This function is deprecated. For details, see the entry for the +'\".B SourceCode +'\"function. +'\" '\"Example: '\" '\".ES @@ -7395,7 +7416,7 @@ vars.Add('CC', 'The C compiler') def validate_color(key, val, env): if not val in ['red', 'blue', 'yellow']: - raise "Invalid color value '%s'" % val + raise Exception("Invalid color value '%s'" % val) vars.Add('COLOR', validator=valid_color) .EE @@ -8006,7 +8027,7 @@ may be indicated by a dictionary entry with a key value of None. .P .ES -b = Builder("build_it < $SOURCE > $TARGET" +b = Builder("build_it < $SOURCE > $TARGET", prefix = "file-") def gen_prefix(env, sources): @@ -9259,7 +9280,7 @@ be associated with the instantiation of the class: .ES -class foo: +class foo(object): def __init__(self, arg): self.arg = arg @@ -9382,7 +9403,9 @@ You can use the function to define objects to scan new file types for implicit dependencies. -Scanner accepts the following arguments: +The +.B Scanner +function accepts the following arguments: .IP function This can be either: @@ -9533,6 +9556,7 @@ that should be scanned recursively; this can be used to select a specific subset of Nodes for additional scanning. +.RE Note that .B scons has a global @@ -9901,7 +9925,7 @@ as follows: def pf(env, dir, target, source, arg): top_dir = Dir('#').abspath results = [] - if env.has_key('MYPATH'): + if 'MYPATH' in env: for p in env['MYPATH']: results.append(top_dir + os.sep + p) return results diff --git a/doc/man/sconsign.1 b/doc/man/sconsign.1 index aed21d7..eb3894c 100644 --- a/doc/man/sconsign.1 +++ b/doc/man/sconsign.1 @@ -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 4720 2010/03/24 03:14:11 jars +.\" doc/man/sconsign.1 5023 2010/06/14 22:05:46 scons .\" .\" ES - Example Start - indents and turns off line fill .de ES @@ -31,7 +31,7 @@ .RE .fi .. -.TH SCONSIGN 1 "March 2010" +.TH SCONSIGN 1 "June 2010" .SH NAME sconsign \- print SCons .sconsign file information .SH SYNOPSIS diff --git a/doc/python10/abstract.xml b/doc/python10/abstract.xml index 294180b..45b4918 100644 --- a/doc/python10/abstract.xml +++ b/doc/python10/abstract.xml @@ -3,7 +3,7 @@ &SCons; is a software construction tool (build tool, or make tool) implemented in Python, which uses Python scripts as "configuration files" for software builds. Based on the design which won the - Software Carpentry build tool competition, &SCons solves a number of + Software Carpentry build tool competition, &SCons; solves a number of problems associated with other build tools, especially including the classic and ubiquitous &Make; itself. diff --git a/doc/python10/design.xml b/doc/python10/design.xml index cb58af9..0dd5faa 100644 --- a/doc/python10/design.xml +++ b/doc/python10/design.xml @@ -6,14 +6,14 @@ - + - + @@ -166,14 +166,14 @@ - + - + @@ -230,14 +230,14 @@ - + - + @@ -264,7 +264,7 @@ signature information for &Node; objects. The signature subsystem in &SCons; supports multiple ways to - determine whether a &Node is up-to-date + determine whether a &Node; is up-to-date by using an abstract &Sig; class as a strategy wrapper: @@ -272,14 +272,14 @@ - + - + @@ -328,14 +328,14 @@ - + - + @@ -391,14 +391,14 @@ - + - + @@ -435,7 +435,7 @@ - The &Taskmaster uses the node subsystem's + The &Taskmaster; uses the node subsystem's &Walker; class to walk the dependency tree, and the &Sig; class to use the appropriate method @@ -629,8 +629,8 @@ &Builder; objects are associated with a &consenv; through a - &consvar; named &BUILDERS;, a list of the &Builder objects that - will be available for execution through the &consenv: + &consvar; named &BUILDERS;, a list of the &Builder; objects that + will be available for execution through the &consenv;: @@ -679,7 +679,7 @@ &Scanner; objects are associated with a &consenv; through a &consvar; named &SCANNERS;, a list of the &Scanner; objects that - will be available through the &consenv: + will be available through the &consenv;: @@ -818,10 +818,10 @@ The most noticeable difference between &scons; and &Make;, or most other build tools, is that the configuration files are actually Python scripts, generically called "SConscripts" (although the - top-level "Makefile" is named &SConstruct). Users do not have to + top-level "Makefile" is named &SConstruct;). Users do not have to learn a new language syntax, but instead configure dependency information by making direct calls to the Python API of the - &SCons; Build Engine. Here is an example &SConstruct file which + &SCons; Build Engine. Here is an example &SConstruct; file which builds a program in side-by-side normal and debug versions: diff --git a/doc/python10/main.xml b/doc/python10/main.xml index 42bc4af..e061b90 100644 --- a/doc/python10/main.xml +++ b/doc/python10/main.xml @@ -182,7 +182,7 @@ O'Reilly & Associates, Inc. - O'Reilly & Associates, Inc. + O'Reilly & Associates, Inc. Managing Projects with Make, 2nd Ed. diff --git a/doc/python10/process.xml b/doc/python10/process.xml index f1b2479..4ff0ab1 100644 --- a/doc/python10/process.xml +++ b/doc/python10/process.xml @@ -13,7 +13,7 @@ - &SCons; will be written to Python version 1.5.2 (to ensure + &SCons; will be written to Python version 2.4 (to ensure usability by a wide install base). @@ -181,7 +181,7 @@ - In practice, these restrictions can be overridden as necessary­for + In practice, these restrictions can be overridden as necessary--for example, when changing comments or documentation. diff --git a/doc/scons.mod b/doc/scons.mod index b500101..b1993d4 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -157,6 +157,7 @@ AddVariables"> Alias"> Aliases"> +AllowSubstExceptions"> AlwaysBuild"> Append"> AppendENVPath"> @@ -191,10 +192,12 @@ File"> FindFile"> FindInstalledFiles"> +FindPathDirs"> Finish"> Flatten"> GenerateHelpText"> GetBuildFailures"> +GetBuildPath"> GetLaunchDir"> GetOption"> Glob"> @@ -279,7 +282,9 @@ TryRun"> - + +IndexError"> +NameError"> str"> zipfile"> 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