From 0e027777d2a09da586616f4acd72974feb7bf8eb Mon Sep 17 00:00:00 2001 From: Steven Knight Date: Thu, 22 Jul 2010 04:20:51 +0000 Subject: Add the generated function documentation to the User's Guide as an appendix. Fixes and refactoring in the bin/scons-proc.py script to support this. Fixes to various parts of the XML input. --- bin/scons-proc.py | 87 +++++++++------ doc/SConscript | 5 +- doc/user/MANIFEST | 1 + doc/user/functions.in | 38 +++++++ doc/user/functions.xml | 38 +++++++ doc/user/main.in | 10 ++ doc/user/main.xml | 10 ++ src/engine/SCons/Environment.xml | 41 ++++--- src/engine/SCons/Script/Main.xml | 156 +++++++++++++-------------- src/engine/SCons/Tool/packaging/__init__.xml | 2 +- 10 files changed, 253 insertions(+), 135 deletions(-) create mode 100644 doc/user/functions.in create mode 100644 doc/user/functions.xml diff --git a/bin/scons-proc.py b/bin/scons-proc.py index 157521a..19c3e0c 100644 --- a/bin/scons-proc.py +++ b/bin/scons-proc.py @@ -13,6 +13,7 @@ import getopt import os import re +import string import sys import xml.sax try: @@ -153,9 +154,7 @@ class SCons_XML_to_XML(SCons_XML): for v in self.values: f.write('\n\n' % (v.prefix, v.idfunc())) - for term in v.termfunc(): - f.write('<%s>%s\n' % - (v.tag, term, v.tag)) + f.write('%s\n' % v.xml_term()) f.write('\n') for chunk in v.summary.body: f.write(str(chunk)) @@ -229,8 +228,8 @@ class SCons_XML_to_man(SCons_XML): f = self.fopen(filename) chunks = [] for v in self.values: - chunks.extend(v.mansep()) - chunks.extend(v.initial_chunks()) + chunks.extend(v.man_separator()) + chunks.extend(v.initial_man_chunks()) chunks.extend(list(map(str, v.summary.body))) body = ''.join(chunks) @@ -327,32 +326,62 @@ class Proxy(object): return cmp(self.__subject, other) return cmp(self.__dict__, other.__dict__) -class Builder(Proxy): +class SConsThing(Proxy): + def idfunc(self): + return self.name + def xml_term(self): + return '%s' % self.name + +class Builder(SConsThing): description = 'builder' prefix = 'b-' tag = 'function' - def idfunc(self): - return self.name - def termfunc(self): - return ['%s()' % self.name, 'env.%s()' % self.name] + def xml_term(self): + return ('<%s>%s()\n<%s>env.%s()' % + (self.tag, self.name, self.tag, self.tag, self.name, self.tag)) def entityfunc(self): return self.name - def mansep(self): + def man_separator(self): return ['\n', "'\\" + '"'*69 + '\n'] - def initial_chunks(self): - return [ '.IP %s\n' % t for t in self.termfunc() ] + def initial_man_chunks(self): + return [ '.IP %s()\n.IP env.%s()\n' % (self.name, self.name) ] -class Function(Proxy): +class Function(SConsThing): description = 'function' prefix = 'f-' tag = 'function' - def idfunc(self): - return self.name - def termfunc(self): - return ['%s()' % self.name, 'env.%s()' % self.name] + def args_to_xml(self, arg): + s = ''.join(arg.body).strip() + result = [] + for m in re.findall('([a-zA-Z/_]+=?|[^a-zA-Z/_]+)', s): + if m[0] in string.letters: + if m[-1] == '=': + result.append('%s=' % m[:-1]) + else: + result.append('%s' % m) + else: + result.append(m) + return ''.join(result) + def xml_term(self): + try: + arguments = self.arguments + except AttributeError: + arguments = ['()'] + result = [] + for arg in arguments: + try: + signature = arg.signature + except AttributeError: + signature = "both" + s = self.args_to_xml(arg) + if signature in ('both', 'global'): + result.append('%s%s\n' % (self.name, s)) #
+ if signature in ('both', 'env'): + result.append('env.%s%s\n' % (self.name, s)) + return ''.join(result) def entityfunc(self): return self.name - def mansep(self): + def man_separator(self): return ['\n', "'\\" + '"'*69 + '\n'] def args_to_man(self, arg): """Converts the contents of an tag, which @@ -380,7 +409,7 @@ class Function(Proxy): m = '"%s"' % m result.append(m) return ' '.join(result) - def initial_chunks(self): + def initial_man_chunks(self): try: arguments = self.arguments except AttributeError: @@ -398,34 +427,28 @@ class Function(Proxy): result.append('.TP\n.IR env .%s%s\n' % (self.name, s)) return result -class Tool(Proxy): +class Tool(SConsThing): description = 'tool' prefix = 't-' tag = 'literal' def idfunc(self): return self.name.replace('+', 'X') - def termfunc(self): - return [self.name] def entityfunc(self): return self.name - def mansep(self): + def man_separator(self): return ['\n'] - def initial_chunks(self): + def initial_man_chunks(self): return ['.IP %s\n' % self.name] -class Variable(Proxy): +class Variable(SConsThing): description = 'construction variable' prefix = 'cv-' tag = 'envar' - def idfunc(self): - return self.name - def termfunc(self): - return [self.name] def entityfunc(self): return '$' + self.name - def mansep(self): + def man_separator(self): return ['\n'] - def initial_chunks(self): + def initial_man_chunks(self): return ['.IP %s\n' % self.name] if output_type == '--man': diff --git a/doc/SConscript b/doc/SConscript index ffffe59..1b145da 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -151,6 +151,8 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. builders_gen = os.path.join(build, 'user', 'builders.gen') builders_mod = os.path.join(build, 'user', 'builders.mod') + functions_gen = os.path.join(build, 'user', 'functions.gen') + functions_mod = os.path.join(build, 'user', 'functions.mod') tools_gen = os.path.join(build, 'user', 'tools.gen') tools_mod = os.path.join(build, 'user', 'tools.mod') variables_gen = os.path.join(build, 'user', 'variables.gen') @@ -163,11 +165,12 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. # vs. the other. The *.gen and *.mod targets will still be dependent # on the list of the files themselves. doc_output_files = [builders_gen, builders_mod, + functions_gen, functions_mod, tools_gen, tools_mod, variables_gen, variables_mod] b = env.Command(doc_output_files, scons_doc_files, - "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $( $SOURCES $)") + "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -f ${TARGETS[2]},${TARGETS[3]} -t ${TARGETS[4]},${TARGETS[5]} -v ${TARGETS[6]},${TARGETS[7]} $( $SOURCES $)") env.Depends(b, "$SCONS_PROC_PY") env.Local(b) diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index ef273d3..0994f2b 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -17,6 +17,7 @@ errors.xml example.xml factories.xml file-removal.xml +functions.xml hierarchy.xml install.xml java.xml diff --git a/doc/user/functions.in b/doc/user/functions.in new file mode 100644 index 0000000..1b1b280 --- /dev/null +++ b/doc/user/functions.in @@ -0,0 +1,38 @@ + + + + +This appendix contains descriptions of all of the +function and construction environment methods +in this version of &SCons; + + + + + +&functions-gen; + + diff --git a/doc/user/functions.xml b/doc/user/functions.xml new file mode 100644 index 0000000..1b1b280 --- /dev/null +++ b/doc/user/functions.xml @@ -0,0 +1,38 @@ + + + + +This appendix contains descriptions of all of the +function and construction environment methods +in this version of &SCons; + + + + + +&functions-gen; + + diff --git a/doc/user/main.in b/doc/user/main.in index d592c49..4b0807d 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -37,6 +37,9 @@ %builders-mod; + + %functions-mod; + %tools-mod; @@ -61,6 +64,7 @@ + @@ -89,6 +93,7 @@ + @@ -358,6 +363,11 @@ &tools; + + Functions and Environment Methods + &functions; + + Handling Common Tasks &tasks; diff --git a/doc/user/main.xml b/doc/user/main.xml index d592c49..4b0807d 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -37,6 +37,9 @@ %builders-mod; + + %functions-mod; + %tools-mod; @@ -61,6 +64,7 @@ + @@ -89,6 +93,7 @@ + @@ -358,6 +363,11 @@ &tools; + + Functions and Environment Methods + &functions; + + Handling Common Tasks &tasks; diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index a86b984..b5e7026 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -897,7 +897,7 @@ to be performed: timestamp-newer - + Specifies that a target shall be considered out of date and rebuilt if the dependency's timestamp is newer than the target file's timestamp. This is the behavior of the classic Make utility, @@ -905,12 +905,11 @@ and make can be used a synonym for timestamp-newer. - + - timestamp-match - + Specifies that a target shall be considered out of date and rebuilt if the dependency's timestamp is different than the timestamp recorded the last time the target was built. @@ -921,12 +920,11 @@ except that the target will also be rebuilt if a dependency file has been restored to a version with an earlier timestamp, such as can happen when restoring files from backup archives. - + - MD5 - + Specifies that a target shall be considered out of date and rebuilt if the dependency's content has changed sine the last time the target was built, @@ -937,12 +935,11 @@ last time the target was built. content can be used as a synonym for MD5. - + - MD5-timestamp - + Specifies that a target shall be considered out of date and rebuilt if the dependency's content has changed sine the last time the target was built, @@ -966,7 +963,7 @@ that runs a build, updates a file, and runs the build again, all within a single second. - + @@ -990,7 +987,7 @@ that takes the following three arguments: dependency - + The Node (file) which should cause the target @@ -998,24 +995,22 @@ to be rebuilt if it has "changed" since the last tme target was built. - + - target - + The Node (file) being built. In the normal case, this is what should get rebuilt if the dependency has "changed." - + - prev_ni - + Stored information about the state of the dependency the last time the @@ -1025,7 +1020,7 @@ This can be consulted to match various file characteristics such as the timestamp, size, or content signature. - + @@ -2681,11 +2676,11 @@ keyword arguments must be set to lists of target and source nodes, respectively, if you want the -&TARGET;, -&TARGETS;, -&SOURCE; +&cv-TARGET;, +&cv-TARGETS;, +&cv-SOURCE; and -&SOURCES; +&cv-SOURCES; to be available for expansion. This is usually necessary if you are calling diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml index bb46824..0380755 100644 --- a/src/engine/SCons/Script/Main.xml +++ b/src/engine/SCons/Script/Main.xml @@ -229,183 +229,183 @@ The options supported are: cache_debug - + which corresponds to --cache-debug; - + cache_disable - + which corresponds to --cache-disable; - + cache_force - + which corresponds to --cache-force; - + cache_show - + which corresponds to --cache-show; - + clean - + which corresponds to -c, --clean and --remove; - + config - + which corresponds to --config; - + directory - + which corresponds to -C and --directory; - + diskcheck - + which corresponds to --diskcheck - + duplicate - + which corresponds to --duplicate; - + file - + which corresponds to -f, --file, --makefile and --sconstruct; - + help - + which corresponds to -h and --help; - + ignore_errors - + which corresponds to --ignore-errors; - + implicit_cache - + which corresponds to --implicit-cache; - + implicit_deps_changed - + which corresponds to --implicit-deps-changed; - + implicit_deps_unchanged - + which corresponds to --implicit-deps-unchanged; - + interactive - + which corresponds to --interact and --interactive; - + keep_going - + which corresponds to -k and --keep-going; - + max_drift - + which corresponds to --max-drift; - + no_exec - + which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; - + no_site_dir - + which corresponds to --no-site-dir; - + num_jobs - + which corresponds to -j and --jobs; - + profile_file - + which corresponds to --profile; - + question - + which corresponds to -q and --question; - + random - + which corresponds to --random; - + repository - + which corresponds to -Y, --repository and --srcdir; - + silent - + which corresponds to -s, --silent and --quiet; - + site_dir - + which corresponds to --site-dir; - + stack_size - + which corresponds to --stack-size; - + taskmastertrace_file - + which corresponds to --taskmastertrace; and - + warn - + which corresponds to --warn and --warning. - + @@ -565,57 +565,57 @@ line options from a SConscript file. The options supported are: clean - + which corresponds to -c, --clean and --remove; - + duplicate - + which corresponds to --duplicate; - + help - + which corresponds to -h and --help; - + implicit_cache - + which corresponds to --implicit-cache; - + max_drift - + which corresponds to --max-drift; - + no_exec - + which corresponds to -n, --no-exec, --just-print, --dry-run and --recon; - + num_jobs - + which corresponds to -j and --jobs; - + random - + which corresponds to --random; and - + stack_size - + which corresponds to --stack-size. - + diff --git a/src/engine/SCons/Tool/packaging/__init__.xml b/src/engine/SCons/Tool/packaging/__init__.xml index 6fec7bd..246b9ec 100644 --- a/src/engine/SCons/Tool/packaging/__init__.xml +++ b/src/engine/SCons/Tool/packaging/__init__.xml @@ -633,7 +633,7 @@ TODO Annotates file or directory Nodes with information about how the -&f-link-Package; +&b-link-Package; Builder should package those files or directories. All tags are optional. -- cgit v0.12